Object Storage Service:GetObject

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 for the bucket to specify the access method. For more information, see Configure bucket policies to authorize other users to access OSS resources.
• If the storage class of the object that you want to query is Archive, you must send a RestoreObject request to restore the object before you call the GetObject operation or enable real-time access for the bucket in which the Archive object is stored.

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, Object Storage Service (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 Calculation of the Authorization header.

If you download an object larger than 100 MB from OSS, the object may fail to download due to network errors. You can specify the HTTP Range header to query part of content of the large object.

You can specify only a single range in a GetObject request. ByteRange specifies the content range of the object to query. Unit: bytes. The value of ByteRange ranges 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 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.

For more information about how to use the Range parameter to obtain resources in OSS, see HTTP Range.

Request headers

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

Response headers

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

Examples

• Simple GetObject requests
  Sample requests

  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 success responses 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 success responses 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 requests that include the Range parameter
  Sample requests

  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 success responses

  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 requests that include custom response headers
  Sample requests

  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 success responses

  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]

• GetObject requests for a symbolic link
  Sample requests

  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 success responses

  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 requests for an object that is restored
  Sample requests

  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 success responses

  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 requests for a specified version of an object
  Sample requests

  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 success responses

  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 requests for an object for which the version ID is not specified and of which the current version is a delete marker
  Sample requests

  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 success responses

  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 requests for an object for which the version ID is specified and of which the version is a delete marker
  Sample requests

  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 success responses

  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

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

• Java
• Python
• PHP
• Go
• C
• C++
• .NET
• Android
• iOS
• Node.js
• Browser.js
• Ruby

Error codes