GET Object

You can perform this operation to download objects from OBS. Before using the GET API, check that you have the read permission for the target object. If the object owner grants the read permission to anonymous users, no authentication information is needed for accessing the target object.

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 deletion marker, OBS returns a code meaning non-existence of the object. You can specify versionId to obtain the content of an object of the desired version.

OBS Archive Objects

If the object to be downloaded is an Archive object, retrieve it first before downloading it. The response varies with the retrieval status of the object. If the object has been retrieved, the x-amz-restore header is returned indicating the expiry date of the object when it is successfully downloaded. If you request downloading Archive objects that are not restored or are being restored, a 403 Forbidden error is returned.

Request Syntax

GET /ObjectName HTTP/1.1
Host: bucketname.obs.cn-north-1.myhwclouds.com
Date: date
Authorization: authorization
Range:bytes=byte_range
<Optional Additional Header>
NOTE:

In this request, header Range is optional. If this header is not specified, all data of an object is returned.

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 more than versions, use the versionId parameter to specify the version to be downloaded. For details, see Table 1.

Table 1 Request parameters

Parameter

Description

Required or Optional

response-content-type

Overrides the Content-Type header in the response.

Type: string

Optional

response-content-language

Overrides the Content-Language header in the response.

Type: string

Optional

response-expires

Overrides the Expires header in the response.

Type: string

Optional

response-cache-control

Overrides the Cache-Control header in the response.

Type: string

Optional

response-content-disposition

Overrides the Content-Disposition header in the response.

Type: string

Optional

response-content-encoding

Overrides the Content-Encoding header in the response.

Type: string

Optional

versionId

Indicates the version ID of the object whose content is obtained.

Type: string

Optional

x-image-process

Image processing service.

Examples:

Command: x-image-process=image/commands

Style: x-image-process=style/stylename

For details, see the Image Processing Feature Guide.

Optional

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 Additional request headers

Header

Description

Required or Optional

Range

Obtains the specified range bytes of an object. The value is a range starting from 0 to maximum object length minus one. If the range is invalid, all object data is returned.

Type: String

Note: The header format is bytes=byte_range.

For example, bytes=0-4 or bytes=512-1024, or indicates multiple ranges: bytes=10-20,30-40.

Optional

If-Modified-Since

Returns the object only if it has been modified since the time specified by this header. Otherwise, 304 Not Modified is returned.

Type: HTTP time string complying with the format specified in http://www.ietf.org/rfc/rfc2616.txt.

Optional

If-Unmodified-Since

Returns the object only if it has not been modified since the time specified by this header. Otherwise, 412 Precondition Failed is returned.

Type: HTTP time string complying with the format specified in http://www.ietf.org/rfc/rfc2616.txt.

Optional

If-Match

Returns the object only if its ETag is the same as the one specified by this header. Otherwise, 412 Precondition Failed is returned.

Type: String

Note: An example ETag value is 0f64741bf7cb1089e988e4585d0d3434.

Optional

If-None-Match

Returns the object only if its ETag is different from the one specified by this header. Otherwise, 304 Not Modified is returned.

Type: String

Note: An example ETag value is 0f64741bf7cb1089e988e4585d0d3434.

Optional

x-amz-server-side-encryption-customer-algorithm

Indicates an encryption algorithm. The header is used in SSE-C mode.

Type: string

Example: x-amz-server-side-encryption-customer-algorithm:AES256

Constraints: This header must be used together with x-amz-server-side-encryption-customer-key and x-amz-server-side-encryption-customer-key-MD5.

Optional. This header is required when SSE-C is used.

x-amz-server-side-encryption-customer-key

Indicates a key used to decrypt objects. The header is used in SSE-C mode.

Type: string

Example: x-amz-server-side-encryption-customer-key:K7QkYpBkM5+hcs27fsNkUnNVaobncnLht/rCB2o/9Cw=

Constraints: This header is a base64-encoded 256-bit key and must be used together with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key-MD5.

Optional. This header is required when SSE-C is used.

x-amz-server-side-encryption-customer-key-MD5

Indicates the MD5 value of a key used to encrypt objects. The header is used in SSE-C mode. The MD5 value is used to check whether any error occurs during the transmission of the key.

Type: string

Example: x-amz-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Constraints: This header is a base64-encoded 128-bit MD5 value and must be used together with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key.

Optional. This header is required when SSE-C is used.

Request Elements

This request contains no element.

Response Syntax

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

<Object Content>

Response Headers

This response uses common headers. For details about common response headers, see Common Response Headers.

This response can also include additional headers. Table 3 describes these headers.

Table 3 Additional response headers

Header

Description

x-amz-expiration

This header is included in the response if the object expiration is configured. This header includes expiry-date and rule-id key value pairs to provide object expiration information.

Type: string

x-amz-website-redirect-location

When a bucket is configured as a website, you can set this metadata for the object so that the website endpoint will evaluate the request for the object as a 301 redirect to another object in the same bucket or an external URL.

Type: string

x-amz-delete-marker

Indicates whether an object is marked as deleted. If an object is not marked as deleted, the header is not returned.

Type: Boolean

Valid values: true or false

Default: false

x-amz-version-id

Indicates the version ID of an object. If an object has no version ID specified, this header is not returned.

Valid values: string

Default: none

x-amz-server-side-encryption

This header is included in a response if SSE-KMS is used.

Type: string

Example: x-amz-server-side-encryption:aws:kms

x-amz-server-side-encryption-aws-kms-key-id

Indicates the master key ID. This header is included in a response if SSE-KMS is used.

Example: x-amz-server-side-encryption-aws-kms-key-id:arn:aws:kms:sichuan:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0

x-amz-server-side-encryption-customer-algorithm

Indicates a decryption algorithm. This header is included in a response if SSE-C is used.

Type: string

Example: x-amz-server-side-encryption-customer-algorithm:AES256

x-amz-server-side-encryption-customer-key-MD5

Indicates the MD5 value of a key used to decrypt objects. This header is included in a response if SSE-C is used.

Type: string

Example: x-amz-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Response Elements

This response contains no element.

Error Responses

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

Registration