You can call this operation to obtain an object. To perform the GetObject operation, you must have the read permissions on the object.

Notice
  • By default, the GetObject operation supports access over both HTTP and HTTPS. To access a bucket only over HTTPS, set the access method in the bucket policy. For more information, see Use bucket policies to authorize other users to access OSS resources.
  • If the storage class of an object is Archive, you must send a RestoreObject request to restore the object before you call the GetObject operation.
  • The ETag value of an object is used to validate whether the content of the object has changed. You can validate data integrity based on the ETag value.

Versioning

By default, the GetObject operation returns only the current version of an object.
Note When you call the GetObject operation on an object in a bucket:
  • If the current version of the object is a delete marker, OSS returns 404 Not Found.
  • 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 specified as null in the request, OSS returns the version whose version ID is null.
  • If the version ID is specified as a delete marker, OSS returns 405 Method Not Allowed.

Request syntax

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

When you are downloading an object larger than 100 MB from OSS, transmission may fail due to the network environment. You can specify the HTTP Range header to query data of the large object.

OSS does not support multiple range parameters. You can only query one range at a time. ByteRange specifies the range of data that you request, in bytes. The valid values of ByteRange are from 0 to object size - 1. 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 data from the 500th byte to the end of the object.
  • Range: bytes=0- specifies data from the first byte to the last byte, that is, the entire object.

Request headers

Note
  • When you initiate a GET request in OSS, you can set headers in the request to customize some headers in the response. However, the headers in the response are set to the values specified in the headers in the request only when the request is successful (the 200 OK code is returned).
  • When you initiate a GET request in OSS as an anonymous user, you cannot set headers in the request to customize headers in the response.
  • You must sign the GET request before sending it.
Header Type Required Description
response-content-type String No Specifies the content-type header in the response returned by OSS.

This parameter is empty by default.

response-content-language String No Specifies the content-language header in the response returned by OSS.

This parameter is empty by default.

response-expires String No Specifies the expires header in the response returned by OSS.

This parameter is empty by default.

response-cache-control String No Specifies the cache-control header in the response returned by OSS.

This parameter is empty by default.

response-content-disposition String No Specifies the content-disposition header in the response returned by OSS.

This parameter is empty by default.

response-content-encoding String No Specifies the content-encoding header in the response returned by OSS.

This parameter is empty by default.

Range String No Specifies the range of data to be returned.

This parameter is empty by default.

  • If the value of Range is valid, the response returned by OSS includes the total size of the object and the range of data 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.
  • If the value of Range is invalid, the entire object is returned and the response returned by OSS does not include Content-Range.
If-Modified-Since String No If the time specified in this header is earlier than the object modification time or does not conform to the standards, OSS returns the object and 200 OK. Otherwise, OSS returns 304 Not Modified.

This parameter is empty by default.

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

If-Unmodified-Since String No If the time specified in this header is the same as or later than the object modification time, OSS returns the object and 200 OK. Otherwise, OSS returns 412 Precondition Failed.

This parameter is empty by default.

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

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

If-Match String No Specifies the object returning condition. If the ETag value specified in the request matches the ETag value of the object, OSS returns the object and 200 OK. Otherwise, OSS returns 412 Precondition Failed.

This parameter is empty by default.

If-None-Match String No Specifies the object returning condition. If the ETag value specified in the request does not match the ETag value of the object, OSS returns the object and 200 OK. Otherwise, OSS returns 304 Not Modified.

This parameter is empty by default.

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

Accept-Encoding String No Specifies the encoding type at the client side.

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

Note
  • If an object is compressed in GZIP format, the response returned by OSS does not include the ETag value of the object.
  • OSS supports GZIP compression for objects whose Content-Type header is one of the following values: HTML, JavaScript, CSS, XML, RSS, and JSON.

Response headers

Note If the requested object is a symbolic link, the content of the object is returned. Response headers Content-Length, ETag, and Content-Md5 indicate the metadata of the requested object. The Last-Modified header indicates the later one of the time points when the requested object and the symbolic link are last modified. All other headers indicate the metadata of the symbolic link.
Header Type Description
x-oss-server-side-encryption String If the requested object is entropy encrypted on the server, OSS automatically decrypts and returns the object after receiving the GetObject request. OSS includes x-oss-server-side-encryption in the response to indicate the encryption algorithm that is used to encrypt the object on the server.
x-oss-tagging-count String Indicates the number of tags associated with the object. This header is returned only if you have the read permissions on tags.

Examples

  • Sample request for a simple query
    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
    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 request with a Range header
    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]
  • Sample request with response headers customized
    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: Chinese
    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]
  • Sample request with the object type specified as symbolic link
    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****
  • Sample request for an object that is restored
    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]
  • Sample request with the version ID of the requested object specified
    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]
  • Sample request with the version ID not specified and the current version specified as a delete marker
    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>
  • Sample request with the version ID specified as a delete marker
    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>

SDKs

The SDKs of the GetObject operation for various programming languages are as follows:

Error codes

Error code HTTP status code Description
NoSuchKey 404 The error message returned because the requested object does not exist.
SymlinkTargetNotExist 404 The error message returned because the requested object is a symbolic link, and the object to which the symbolic link points does not exist.
InvalidTargetType 400 The error message returned because the requested object is a symbolic link, and the object to which the symbolic link points is still a symbolic link.
InvalidObjectState 403 The error message returned because the storage class of the requested object is Archive and the object restoration status is as follows:
  • 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
  • The error message returned because the If-Modified-Since header is specified in the request, but the requested object has not been modified since the time specified in the request.
  • The error message returned because the If-None-Match header is specified in the request, and the ETag value provided in the request is the same as the ETag value of the requested object.
Precondition Failed 412
  • The error message returned because the If-Unmodified-Since header is specified in the request, but the specified time is earlier than the modification time of the requested object.
  • The error message returned because the If-Match header is specified in the request, but the ETag value provided in the request is different from the ETag value of the requested object.