Downloading an Object¶

Functions¶

This operation downloads an object from OBS. Before using this GET operation, check that you have the read permission for the target object. If the object owner has granted anonymous users the read permission for the object, anonymous users can access this object without using the authentication header field.

Server-Side Encryption¶

If the object uploaded to the server is encrypted on the server using the encryption key provided by the client, downloading the object requires including the encryption key in the message.

Versioning¶

By default, the GET operation returns the current version of an object. If the current version of the object is a delete marker, OBS returns a code meaning that the object does not exist. To obtain an object of a specified version, the versionId parameter can be used to specify the desired version.

Cold Objects¶

If the object you want to download is in the Cold storage class, ensure that this object has been restored before you download it. The response varies depending on the object's restore state. If an object has been restored, the x-obs-restore header (indicating the expiry date of the object) is returned when the object is successfully downloaded. If you send a request to download Cold objects that have not been restored or are being restored, a 403 Forbidden error will be returned.

Request Syntax¶

GET /ObjectName HTTP/1.1
Host: bucketname.obs.region.example.com
Date: date
Authorization: authorization
Range:bytes=byte_range
<Optional Additional Header>

Note

The field is optional. If it does not exist, you can obtain the whole content.

Request Parameters¶

In a GET request, you can override values for a set of message headers using the request parameters. Message headers that you can override are Content-Type, Content-Language, Expires, Cache-Control, Content-Disposition, and Content-Encoding. If the target object has multiple versions, use the versionId parameter to specify the version to be downloaded. For details, see Table 1.

Note

OBS does not process Accept-Encoding carried in a request or compress or decompress the uploaded data. The client determines whether to compress or decompress the data. Some HTTP clients may decompress data based on the Content-Encoding returned by the server. The client program needs to determine whether to decompress and how to decompress the data. To decompress the data, it can modify Content-Encoding (the object metadata stored in OBS) or rewrite Content-Encoding the object is downloaded. If an object download request specifies the rewrite header, the standard HTTP message header returned by OBS is subject to the rewrite content specified in the request.

**Table 1** Request parameters¶
Parameter	Type	Mandatory (Yes/No)	Description
response-content-type	String	No	Explanation: Content-Type is rewritten in the response. Restrictions: None Value range: See the Content-Type values defined in HTTP. Default value: None
response-content-language	String	No	Explanation: Content-Language is rewritten in the response. Restrictions: None Value range: See the Content-Language values defined in HTTP. Default value: None
response-expires	String	No	Explanation: Expires is rewritten in the response. Restrictions: None Value range: See the Expires values defined in HTTP. Default value: None
response-cache-control	String	No	Explanation: Cache-Control is rewritten in the response. Restrictions: None Value range: See the Cache-control values defined in HTTP. Default value: None
response-content-disposition	String	No	Explanation: Content-Disposition is rewritten in the response. Example: response-content-disposition=attachment; filename=utf-8''name1 In this example, the downloaded object is renamed name1. If the new name contains any full-width characters, such characters must be URL-encoded. Restrictions: None Value range: None Default value*: None
response-content-encoding	String	No	Explanation: Content-Encoding is rewritten in the response. Restrictions: None Value range: See the Content-Encoding values defined in HTTP. Default value: None
versionId	String	No	Explanation: Indicates the version ID of the object to be obtained. Restrictions: None Value range: The value must contain 32 characters. Default value: None. If this parameter is not configured, the latest version of the object is obtained.
attname	String	No	Explanation: Content-Disposition is rewritten in the response. Example: attname=name1 This example renames the downloaded object as name1. Restrictions: None Value range: None Default value: None

Request Headers¶

This request uses common headers. In addition, you can add additional headers to this request. Table 2 describes the additional headers.

**Table 2** Request headers¶
Header	Type	Mandatory (Yes/No)	Description
Range	String	No	Explanation: Obtains the object content within the scope defined by Range. If the parameter value is invalid, the entire object is obtained. Restrictions: Range value starts from 0, and the maximum value equals the object length minus 1. The start value of Range is mandatory. If only the start value is specified, the system obtains the object content from the start value to default maximum value. bytes=byte_range Example 1: bytes=0-4 Example 2: bytes=1024 Example 3: bytes=10-20, 30-40 (multiple ranges) After the Range header field is carried, the value of ETag in the response message is the ETag of the object instead of the ETag of the object in the Range field. Value range: Range value starts from 0, and the maximum value equals the object length minus 1. Default value: None
If-Modified-Since	HTTP time string complying with the format specified at http://www.ietf.org/rfc/rfc2616.txt.	No	Explanation: Returns the object only if it has been modified since the time specified by this header. Otherwise, 304 Not Modified is returned. Restrictions: The time specified by this parameter cannot be later than the current server time (GMT time), or this parameter does not take effect. Value range: HTTP time string complying with the format specified at http://www.ietf.org/rfc/rfc2616.txt. EEE, dd MMM yyyy HH:mm:ss z EEEE, dd-MMM-yy HH:mm:ss z EEE MMM dd HH:mm:ss yyyy Examples: if-modified-since: Sun, 06 Nov 1994 08:49:37 GMT if-modified-since: Sunday, 06-Nov-94 08:49:37 GMT if-modified-since: Sun Nov 6 08:49:37 1994 Default value: None
If-Unmodified-Since	HTTP time string complying with the format specified at http://www.ietf.org/rfc/rfc2616.txt.	No	Explanation: If the object has not been modified since the time specified by this header, it is returned. Otherwise, 412 (precondition failed) is returned. Restrictions: The time specified by this parameter cannot be later than the current server time (GMT time), or this parameter does not take effect. Value range: HTTP time string complying with the format specified at http://www.ietf.org/rfc/rfc2616.txt. EEE, dd MMM yyyy HH:mm:ss z EEEE, dd-MMM-yy HH:mm:ss z EEE MMM dd HH:mm:ss yyyy Examples: if-unmodified-since: Sun, 06 Nov 1994 08:49:37 GMT if-unmodified-since: Sunday, 06-Nov-94 08:49:37 GMT if-unmodified-since: Sun Nov 6 08:49:37 1994 Default value: None
If-Match	String	No	Explanation: Returns the object only if its ETag is the same as the one specified by this header. Otherwise, 412 Precondition Failed is returned. ETag example: 0f64741bf7cb1089e988e4585d0d3434 Restrictions: None Value range: Object ETag Default value: None
If-None-Match	String	No	Explanation: Returns the object only if its ETag is different from the one specified by this header. Otherwise, 304 Not Modified is returned. ETag example: 0f64741bf7cb1089e988e4585d0d3434 Restrictions: None Value range: Object ETag Default value: None
x-obs-server-side-encryption-customer-algorithm	String	No. This header is required when SSE-C is used.	Explanation: Indicates the encryption algorithm used when SSE-C is used. Example: x-obs-server-side-encryption-customer-algorithm:AES256 Restrictions: This header must be used together with x-obs-server-side-encryption-customer-key and x-obs-server-side-encryption-customer-key-MD5. Value range: AES256 Default value: None
x-obs-server-side-encryption-customer-key	String	No. This header is required when SSE-C is used.	Explanation: Indicates the encryption key used when SSE-C is used. This key is used to decrypt objects. Example: x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= Restrictions: This header is a Base64-encoded 256-bit key and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key-MD5. Value range: None Default value: None
x-obs-server-side-encryption-customer-key-MD5	String	No. This header is required when SSE-C is used.	Explanation: Indicates the MD5 value of the encryption key when SSE-C is used. The MD5 value is used to check whether any error occurs during the transmission of the key. Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Restrictions: This header is a Base64-encoded 128-bit MD5 value and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key. Value range: Base64-encoded MD5 value of the key ID. Default value: None

Request Elements¶

This request involves no elements.

Response Syntax¶

HTTP/1.1 status_code
Content-Type: type
Date: date
Content-Length: length
Etag: etag
Last-Modified: time

<Object Content>

Response Headers¶

The response to the request uses common headers. For details, see Table 1.

In addition to the common response headers, the headers listed in Table 3 may be used.

**Table 3** Additional response headers¶
Header	Type	Description
x-obs-expiration	String	Explanation: Expiration time of an object. Restrictions: When an object has its lifecycle rule, the object expiration time is subject to its lifecycle rule. This header field is use expiry-date to describe the object expiration date. If the lifecycle rule is configured only for the entire bucket not individual objects, the object expiration time is subject to the bucket lifecycle rule. This header field uses the expiry-date and rule-id to describe the detailed expiration information of objects. If no lifecycle rule is configured, this header field is not contained in the response. Value range: The time format is EEE, dd MMM yyyy HH:mm:ss z. Example: expiry-date=Sun, 06 Nov 1994 08:49:37 GMT Default value: None
x-obs-website-redirect-location	String	Explanation: Indicates where an object request is redirected. If the bucket that contains the object is configured with Website settings, this parameter can be set in the object metadata so that the request for the object can be redirected to another object in the same bucket or an external URL after the website returns a 301 redirect response. To another object in the same bucket: x-obs-website-redirect-location:/anotherPage.html To an external URL: x-obs-website-redirect-location:http://www.example.com/ OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation. Restrictions: The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB. OBS supports redirection for objects in the root directory of a bucket, not for those in folders. Default value: None
x-obs-delete-marker	Boolean	Explanation: Whether the deleted object is a delete marker. If the object is not marked as deleted, the response does not contain this header. Value range: true: The deleted object is a delete marker. false: The deleted object is not a delete marker. Default value: false
x-obs-version-id	String	Explanation: Object version ID. Restrictions: If the object has no version number specified, the response does not contain this header. Value range: The value must contain 32 characters. Default value: None
x-obs-server-side-encryption	String	Explanation: The encryption method used by the server. Example: x-obs-server-side-encryption:kms Restrictions: This header is included in a response if SSE-KMS is used. Value range: kms AES256 Default value: None
x-obs-server-side-encryption-kms-key-id	String	Explanation: ID of a specified key used for SSE-KMS encryption. Restrictions: This header can only be used when you specify kms for the x-obs-server-side-encryption header. Default value: If you specify kms for encryption but do not specify a key ID, the default master key will be used. If there is not a default master key, OBS will create one and use it.
x-obs-server-side-encryption-customer-algorithm	String	Explanation: Indicates a decryption algorithm. This header is included in a response if SSE-C is used. Example: x-obs-server-side-encryption-customer-algorithm:AES256 Restrictions: None Value range: AES256 Default value: None
x-obs-server-side-encryption-customer-key-MD5	String	Explanation: Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used. Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Value range: Base64-encoded MD5 value of the key ID. Default value: None
x-obs-object-type	String	Explanation: Object type Restrictions: This header is returned when the object is not a Normal object. Value range: Appendable Default value: None
x-obs-next-append-position	Integer	Explanation: Indicates the position that should be provided in the next request. Restrictions: This header field is returned when the object is an appendable object. Value range: None Default value: None
x-obs-tagging-count	String	Explanation: Number of tags associated with an object. Example: x-obs-tagging-count:1 Restrictions: This parameter is returned only when the user has the permission to read tags. Value range: None Default value: None

Response Elements¶

This response contains no elements.

Error Responses¶

No special error responses are returned. For details about error responses, see Table 2.

Sample Request: Downloading an Object¶

GET /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:24:33 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=

Sample Response: Downloading an Object¶

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 8DF400000163D3F2A89604C49ABEE55E
Accept-Ranges: bytes
ETag: "3b46eaf02d3b6b1206078bb86a7b7013"
Last-Modified: WED, 01 Jul 2015 01:20:29 GMT
Content-Type: binary/octet-stream
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSQwxJ2I1VvxD/Xgwuw2G2RQax30gdXU
Date: WED, 01 Jul 2015 04:24:33 GMT
Content-Length: 4572

[4572 Bytes object content]

Sample Request: Downloading a Specified Range of an Object¶

Download the specified range of an object (download a range of an object).

GET /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: Mon, 14 Sep 2020 09:59:04 GMT
Range:bytes=20-30
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:mNPLWQMDWg30PTkAWiqJaLl3ALg=

Download the specified range of an object (download multiple ranges of an object).

GET /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: Mon, 14 Sep 2020 10:02:43 GMT
Range:bytes=20-30,40-50
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:ZwM7Vk2d7sD9o8zRsRKehgKQDkk=

Sample Response: Downloading a Specified Range of an Object¶

Download the specified range of an object (download a range of an object).

HTTP/1.1 206 Partial Content
Server: OBS
x-obs-request-id: 000001748C0DBC35802E360C9E869F31
Accept-Ranges: bytes
ETag: "2200446c2082f27ed2a569601ca4e360"
Last-Modified: Mon, 14 Sep 2020 01:16:20 GMT
Content-Range: bytes 20-30/4583
Content-Type: binary/octet-stream
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSn2JHu4okx9NBRNZAvBGawa3lt3g31g
Date: Mon, 14 Sep 2020 09:59:04 GMT
Content-Length: 11

[ 11 Bytes object content]

Download the specified range of an object (download multiple ranges of an object).

HTTP/1.1 206 Partial Content
Server: OBS
x-obs-request-id: 8DF400000163D3F2A89604C49ABEE55E
Accept-Ranges: bytes
ETag: "2200446c2082f27ed2a569601ca4e360"
Last-Modified: Mon, 14 Sep 2020 01:16:20 GMT
Content-Type: multipart/byteranges;boundary=35bcf444-e65f-4c76-9430-7e4a68dd3d26
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSIBWFOVW8eeWujkqSnoIANC2mNR1cdF
Date: Mon, 14 Sep 2020 10:02:43 GMT
Content-Length: 288

--35bcf444-e65f-4c76-9430-7e4a68dd3d26
Content-type: binary/octet-stream
Content-range: bytes 20-30/4583
[ 11 Bytes object content]
--35bcf444-e65f-4c76-9430-7e4a68dd3d26
Content-type: binary/octet-stream
Content-range: bytes 40-50/4583
[ 11 Bytes object content]
--35bcf444-e65f-4c76-9430-7e4a68dd3d26

Sample Request: Checking the ETag Value of an Object¶

Download an object if its ETag value is matched.

GET /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:24:33 GMT
If-Match: 682e760adb130c60c120da3e333a8b09
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=

Sample Response: Checking the ETag Value of an Object (ETag Mismatch)¶

If the object's ETag value is not 682e760adb130c60c120da3e333a8b09, the system displays a download failure message.

HTTP/1.1 412 Precondition Failed
Server: OBS
x-obs-request-id: 8DF400000163D3F2A89604C49ABEE55E
Content-Type: application/xml
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSQwxJ2I1VvxD/Xgwuw2G2RQax30gdXU
Date: WED, 01 Jul 2015 04:20:51 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Error>
  <Code>PreconditionFailed</Code>
  <Message>At least one of the pre-conditions you specified did not hold</Message>
  <RequestId>8DF400000163D3F2A89604C49ABEE55E</RequestId>
  <HostId>ha0ZGaSKVm+uLOrCXXtx4Qn1aLzvoeblctVXRAqA7pty10mzUUW/yOzFue04lBqu</HostId>
  <Condition>If-Match</Condition>
</Error>

Sample Response: Checking the ETag Value of an Object (ETag Matched)¶

If the object's ETag value is 682e760adb130c60c120da3e333a8b09, the download is successful.

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 5DEB00000164A21E1FC826C58F6BA001
Accept-Ranges: bytes
ETag: "682e760adb130c60c120da3e333a8b09"
Last-Modified: Mon, 16 Jul 2015 08:03:34 GMT
Content-Type: application/octet-stream
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSbkdml1sLSvKnoHaRcOwRI+6+ustDwk
Date: Mon, 16 Jul 2015 08:04:00 GMT
Content-Length: 8

[ 8 Bytes object content]

Sample Request: Downloading an Object Using a Signed URL¶

GET /object02?AccessKeyId=H4IPJX0TQTHTHEBQQCEC&Expires=1532688887&Signature=EQmDuOhaLUrzrzRNZxwS72CXeXM%3D HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: Fri, 27 Jul 2018 10:52:31 GMT

Sample Response: Downloading an Object Using a Signed URL¶

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 804F00000164DB5E5B7FB908D3BA8E00
ETag: "682e760adb130c60c120da3e333a8b09"
Last-Modified: Mon, 16 Jul 2015 08:03:34 GMT
Content-Type: application/octet-stream
x-obs-id-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCTlpxILjhVK/heKOWIP8Wn2IWmQoerfw
Date: Fri, 27 Jul 2018 10:52:31 GMT
Content-Length: 8

[ 8 Bytes object content]

Sample Request: Downloading an Object and Renaming It (with response-content-disposition Used)¶

Use the response-content-disposition parameter to download and rename an object.

GET /object01?response-content-disposition=attachment; filename*=utf-8''name1 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:24:33 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=

Sample Response: Downloading an Object and Renaming It (with response-content-disposition Used)¶

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 804F00000164DB5E5B7FB908D3BA8E00
ETag: "682e760adb130c60c120da3e333a8b09"
Last-Modified: Mon, 16 Jul 2015 08:03:34 GMT
Content-Type: application/octet-stream
x-obs-id-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCTlpxILjhVK/heKOWIP8Wn2IWmQoerfw
Date: Fri, 27 Jul 2018 10:52:31 GMT
Content-Length: 8
Content-Disposition: attachment; filename*=utf-8''name1

[ 8 Bytes object content]

Sample Request: Downloading an Object and Renaming It (with attname Used)¶

Use the attname parameter to download and rename an object.

GET /object01?attname=name1 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:24:33 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=

Sample Response: Downloading an Object and Renaming It (with attname Used)¶

HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 804F00000164DB5E5B7FB908D3BA8E00
ETag: "682e760adb130c60c120da3e333a8b09"
Last-Modified: Mon, 16 Jul 2015 08:03:34 GMT
Content-Type: application/octet-stream
x-obs-id-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCTlpxILjhVK/heKOWIP8Wn2IWmQoerfw
Date: Fri, 27 Jul 2018 10:52:31 GMT
Content-Length: 8
Content-Disposition: attachment; filename*=utf-8''name1

[ 8 Bytes object content]

last updated: 2024-12-11 10:27 UTC - commit: 1084b97f9d241d7af788bdfaa536dba9679533f7