All Products
Search
Document Center

Object Storage Service:GetObject

Last Updated:Dec 07, 2023

Queries an object. To call this operation, you must have read permissions on the object.

Usage notes

  • By default, the GetObject operation supports access over HTTP and HTTPS. To allow access to a bucket only over HTTPS, configure a bucket policy to specify the access method. For more information, see Configure a bucket policy

  • If you want to query an Archive object, you must send a RestoreObject request to restore the object or enable real-time access of Archive objects for the bucket in which the Archive object is stored before you call the GetObject operation.

Versioning

By default, only the current version of an object is returned after GetObject is called.

If the version ID of the object is specified in the request, OSS returns the specified version of the object. If the version ID is set to null in the request, OSS returns the version of the object whose version ID is null.

Request syntax

GET /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Range: bytes=ByteRange (optional)

For more information about how to calculate the authorization header, see Include signatures in the Authorization header.

If you download an object larger than 100 MB from OSS in poor network conditions, the object may fail to be downloaded. You can specify the Range header to query part of the content of the large object.

You can specify only a range in a GetObject request. Range specifies the content range of the object that you want to query. Valid values of Range: 0 to object size - 1. Unit: bytes. Examples:

  • Range: bytes=0-499 specifies the first 500 bytes.

  • Range: bytes=500-999 specifies the second 500 bytes.

  • Range: bytes=-500 specifies the last 500 bytes.

  • Range: bytes=500- specifies the content range from the 500th byte to the end of the object.

  • Range: bytes=0- specifies data from the first byte to the last byte, which is the entire object.

Important

If you set Range to an invalid value, the InvalidRange error code is reported. For example, the maximum valid range for an object that has 1,000 bytes is 0-999. If you set Range to bytes=0-1000, the InvalidRange error code is reported.

For more information about how to use the Range header to query resources in OSS, see How to Obtain OSS Resources by Segmenting HTTP Range Requests.

Request headers

When you initiate a GetObject request, you can set request headers to customize response headers. However, the response headers are set to the values specified in the request headers only if the request is successful. If the request is successful, 200 OK is returned.

Note

When you initiate a GetObject request as an anonymous user, you cannot set request headers to customize response headers.

Header

Type

Required

Description

response-content-type

String

No

The Content-Type header to be returned in the response.

By default, this header is left empty.

response-content-language

String

No

The Content-language header to be returned in the response.

By default, this header is left empty.

response-expires

String

No

The Expires header to be returned in the response.

By default, this header is left empty.

response-cache-control

String

No

The Cache-control header to be returned in the response.

By default, this header is left empty.

response-content-disposition

String

No

The Content-disposition header to be returned in the response.

By default, this header is left empty.

response-content-encoding

String

No

The Content-encoding header to be returned in the response.

By default, this header is left empty.

Range

String

No

The range of data that you want to query.

  • If the specified range is valid, the total size of the object and the range of data are returned. For example, Content-Range: bytes 0~9/44 indicates that the total size of the object is 44 bytes, and the range of data returned is the first 10 bytes.

  • However, if the specified range is invalid, the entire object is returned, and the response does not include the Content-Range header.

By default, this header is left empty.

If-Modified-Since

String

No

If the time specified in this header is earlier than the last modified time of the object or is invalid, the object and 200 OK are returned. Otherwise, 304 Not Modified is returned.

The time must be in GMT. Example: Fri, 13 Nov 2015 14:47:53 GMT.

By default, this header is left empty.

If-Unmodified-Since

String

No

If the time specified in this header is the same as or later than the last modified time of the object, the object and 200 OK are returned. Otherwise, 412 Precondition Failed is returned.

The time must be in GMT. Example: Fri, 13 Nov 2015 14:47:53 GMT.

You can specify the If-Modified-Since and If-Unmodified-Since headers in a request.

By default, this header is left empty.

If-Match

String

No

If the ETag specified in the request matches the ETag value of the object, the object and 200 OK are returned. Otherwise, 412 Precondition Failed is returned.

The ETag of an object is used to check the data integrity of the object.

By default, this header is left empty.

If-None-Match

String

No

If the ETag specified in the request does not match the ETag of the object, the object and 200 OK are returned. Otherwise, 304 Not Modified is returned.

You can specify the If-Match and If-None-Match headers in a request.

By default, this header is left empty.

Accept-Encoding

String

No

The encoding method at the client side.

If you want an object to be returned in the GZIP format, you must include the Accept-Encoding:gzip header in your request. OSS determines whether to return the object compressed in the GZIP format based on the Content-Type header and whether the size of the object is greater than or equal to 1 KB.

Note
  • If an object is compressed in the GZIP format, the response does not include the ETag of the object.

  • If Content-Type is set to one of the following values, compression in the GZIP format is supported: text/cache-manifest, text/xml, text/plain, text/css, application/javascript, application/x-javascript, application/rss+xml, application/json, and text/json.

By default, this header is left empty.

Response headers

If the requested object is a symbolic link, the content of the object to which the symbolic link points is returned. The Content-Length, ETag, and Content-Md5 response headers indicate the metadata of the returned object. The return value of the Last-Modified header is the last modified time of the symbolic link or the last modified time of the object to which the symbolic link points, whichever is later. Other headers indicate the metadata of the symbolic link.

Header

Type

Description

x-oss-server-side-encryption

String

If the requested object is encrypted by using a server-side encryption algorithm based on entropy encoding, OSS automatically decrypts the object and returns the decrypted object after OSS receives the GetObject request. OSS includes the x-oss-server-side-encryption header in the response to indicate the encryption algorithm that is used to encrypt the object on the server.

x-oss-tagging-count

String

The number of tags added to the object. This header is returned only if you have the permissions to query the tags of the object.

x-oss-expiration

String

The expiration time of the object in the bucket for which lifecycle rules are configured.

  • Versioning enabled for the bucket

    • Version ID not included in the request

      If the object requested matches the delete conditions specified in the lifecycle rule, the x-oss-expiration header is included in the response to indicate the expiration time of the current version of the object.

    • Version ID included in the request

      The x-oss-expiration header is not included in the response regardless of whether the object requested matches the delete conditions specified in the lifecycle rule.

  • Versioning not enabled for the bucket

    • If the object requested matches the delete conditions specified in the lifecycle rule, the x-oss-expiration header is included in the response.

    • If the object requested does not match the delete conditions specified in the lifecycle rule, the x-oss-expiration header is not included in the response.

Examples

  • Simple GetObject request

    Sample request

    GET /oss.jpg HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 06:38:30 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:UNQDb7GapEgJkcde6OhZ9J*****

    Sample response for an object

    HTTP/1.1 200 OK
    x-oss-request-id: 3a8f-2e2d-7965-3ff9-51c875b*****
    x-oss-object-type: Normal
    Date: Fri, 24 Feb 2012 06:38:30 GMT
    Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
    ETag: "5B3C1A2E0563E1B002CC607C*****"
    Content-Type: image/jpg
    Content-Length: 344606
    Server: AliyunOSS
    [344606 bytes of object data]

    Sample response for a directory

    Important

    If a GetObject request is initiated for a directory, custom response headers such as response-content-type and Range specified in the GetObject request do not take effect.

    HTTP/1.1 200 OK
    x-oss-request-id: 3a8f-2e2d-7965-3ff9-51c875b*****
    x-oss-object-type: Normal
    Date: Wed, 31 Mar 2021 06:38:30 GMT
    Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
    ETag: "null"
    Content-Type: application/x-directory
    Content-Length: 0
    Server: AliyunOSS
  • GetObject request that includes the Range header

    Sample request

    GET /oss.jpg HTTP/1.1
    Host:oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 28 Feb 2012 05:38:42 GMT
    Range: bytes=100-900
    Authorization: OSS qn6qrrqxo2oawuk5jbyc:qZzjF3DUtd+yK16BdhGtFcC*****

    Sample response

    HTTP/1.1 206 Partial Content
    x-oss-request-id: 28f6-15ea-8224-234e-c0ce407*****
    x-oss-object-type: Normal
    Date: Fri, 28 Feb 2012 05:38:42 GMT
    Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
    ETag: "5B3C1A2E05E1B002CC607C*****"
    Accept-Ranges: bytes
    Content-Range: bytes 100-900/344606
    Content-Type: image/jpg
    Content-Length: 801
    Server: AliyunOSS
    [801 bytes of object data]
  • GetObject request that includes custom response headers

    Sample request

    GET /oss.jpg?response-expires=Thu%2C%2001%20Feb%202012%2017%3A00%3A00%20GMT& response-content-type=text&response-cache-control=No-cache&response-content-disposition=attachment%253B%2520filename%253Dtesting.txt&response-content-encoding=utf-8&response-content-language=%E4%B8%AD%E6%96%87 HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com:
    Date: Fri, 24 Feb 2012 06:09:48 GMT

    Sample response

    HTTP/1.1 200 OK
    x-oss-request-id: 559CC9BDC75A644*****
    x-oss-object-type: Normal
    Date: Fri, 24 Feb 2012 06:09:48 GMT 
    Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
    ETag: "5B3C1A2E053D1B002CC607*****"
    Content-Length: 344606
    Connection: keep-alive
    Content-disposition: attachment; filename=testing.txt
    Content-language: en
    Content-encoding: utf-8
    Content-type: text
    Cache-control: no-cache
    Expires: Fri, 24 Feb 2012 17:00:00 GMT
    Server: AliyunOSS
    [344606 bytes of object data]
  • GetObject request for a symbolic link

    Sample request

    GET /link-to-oss.jpg HTTP/1.1
    Accept-Encoding: identity
    Date: Tue, 08 Nov 2016 03:17:58 GMT
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Authorization: OSS qn6qrrqxok53otfjbyc:qZzjF3DUtd+yK16BdhGtFc*****

    Sample response

    HTTP/1.1 200 OK
    Server: AliyunOSS
    Date: Tue, 08 Nov 2016 03:17:58 GMT
    Content-Type: application/octet-stream
    Content-Length: 20
    Connection: keep-alive
    x-oss-request-id: 582143E6A212AD*****
    Accept-Ranges: bytes
    ETag: "8086265EFC021F9A2F09BF4****"
    Last-Modified: Tue, 08 Nov 2016 03:17:58 GMT
    x-oss-object-type: Symlink
    Content-MD5: gIYmXvwCEe0fmi8Jv0Y****
  • GetObject request for an object that is restored

    Sample request

    GET /oss.jpg HTTP/1.1
    Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
    Date: Sat, 15 Apr 2017 09:38:30 GMT
    Authorization: OSS qn6qrrqxo2o***k53otfjbyc:zUglwRPGkbByZxm1+y4eyu+*****

    Sample response

    HTTP/1.1 200 OK
    x-oss-request-id: 58F723829F29F18D7F00*****
    x-oss-object-type: Normal
    x-oss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT"
    Date: Sat, 15 Apr 2017 09:38:30 GMT
    Last-Modified: Sat, 15 Apr 2017 06:07:48 GMT
    ETag: "5B3C1A2E0763E1B002CC607C*****"
    Content-Type: image/jpg
    Content-Length: 344606
    Server: AliyunOSS
    [354606 bytes of object data]
  • GetObject request sent to query an object for which the version ID is specified

    Sample request

    GET /example?versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0**** HTTP/1.1
    Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 02:58:06 GMT
    Authorization: OSS lkojgxic6e:8wcOrEDt4iSxpBPfQW9OJNw*****

    Sample response

    HTTP/1.1 200 OK
    x-oss-request-id: 5CAC0A3EDE0170*****
    x-oss-version-id: CAEQNhiBgM0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY*****
    x-oss-object-type: Normal
    Date: Tue, 09 Apr 2019 02:58:06 GMT
    Last-Modified: Fri, 22 Mar 2018 08:07:50 GMT
    ETag: "5B3C1A2E053D7002CC607C5A*****"
    Content-Type: text/html
    Content-Length: 362149
    Server: AliyunOSS
    [362149 bytes of object data]
  • GetObject request sent to query an object for which the version ID is not specified and whose current version is a delete marker

    Sample request

    GET /example HTTP/1.1
    Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 03:22:33 GMT
    Authorization: OSS duagpvtn35:taVlDvAJMhEumrR+oLMWtQp*****

    Sample response

    HTTP/1.1 404 Not Found
    x-oss-request-id: 5CAC0FEADE0170*****
    x-oss-delete-marker: true
    x-oss-version-id: CAEQNxiBgyA0BYiIDc4ZDdmNTA2MGViZTRiNjE5NzZlZWM4OWM5OT*****
    Date: Tue, 09 Apr 2019 03:22:33 GMT
    Content-Type: application/xml
    Connection: keep-alive
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <Error>
      <Code>NoSuchKey</Code>
      <Message>The specified key does not exist.</Message>
      <RequestId>5CAC0FEADE0170*****</RequestId>
      <HostId>versioning-get.oss-cn-hangzhou.aliyun*****</HostId>
      <Key>example</Key>
    </Error>
  • GetObject request sent to query an object for which the version ID is specified and whose version is a delete marker

    Sample request

    GET /example?versionId=CAEQMxiBgMCfqaWA0BYiIDliMWI4MGQ0MTVmMjQ3MmE5MDNlMmY4YmFkYTk3**** HTTP/1.1
    Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 03:09:44 GMT
    Authorization: OSS tvqm50uz4y:51UaP+wQt5k1RQang/U6Eeq*****

    Sample response

    HTTP/1.1 405 Method Not Allowed
    x-oss-request-id: 5CAC0CF8DE01700*****
    x-oss-delete-marker: true
    x-oss-version-id: CAEQMxiBgMCfqaWADliMWI4MGQ0MTVmMjQ3MmE5MDNlMmY4YmFkYTk*****
    Allow: DELETE
    Date: Tue, 09 Apr 2019 03:09:44 GMT
    Content-Type: application/xml
    Content-Length: 318
    Connection: keep-alive
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <Error>
      <Code>MethodNotAllowed</Code>
      <Message>The specified method is not allowed against this resource.</Message>
      <RequestId>5CAC0CF8DE0170*****</RequestId>
      <HostId>versioning-get.oss-cn-hangzhou.aliyunc*****</HostId>
      <Method>GET</Method>
      <ResourceType>DeleteMarker</ResourceType>
    </Error>

OSS SDKs

You can use OSS SDKs for the following programming languages to call the GetObject operation:

Error codes

Error code

HTTP status code

Description

NoSuchKey

404

The specified object does not exist.

SymlinkTargetNotExist

404

The requested object is a symbolic link and the object to which the symbolic link points does not exist.

InvalidTargetType

400

The requested object is a symbolic link, and the object to which the symbolic link points is another symbolic link.

InvalidObjectState

403

One of the following scenarios occurs when you download an Archive object:

  • The RestoreObject request for the object was not initiated or timed out.

  • The RestoreObject request for the object has been initiated but the object is not restored.

Not Modified

304

Possible causes:

  • The If-Modified-Since header is specified in the request, but the requested object has not been modified since the specified time.

  • The If-None-Match header is specified in the request, and the ETag provided in the request is the same as the ETag of the requested object.

Precondition Failed

412

Possible causes:

  • The If-Unmodified-Since header is specified in the request, but the specified time is earlier than the modified time of the requested object.

  • The If-Match header is specified in the request, but the ETag provided in the request is different from the ETag of the requested object.

Not Found

404

The version ID of the object is not specified in the request and the current version of the object is a delete marker.

Method Not Allowed

405

The version ID of the object is specified in the request and the version is a delete marker.