GetObject

Notes

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

• If the object is of the Archive type, 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.

Permission description

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account have no permissions by default. The Alibaba Cloud account or account administrator must grant permissions through RAM policy or bucket policy.

Versioning

By default, the GetObject operation returns only the current version of the object.

If a 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, 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 how to calculate the Authorization field.

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 Range header to query part of the content of the large object. For more examples of how to use the HTTP Range header to obtain OSS resources in segments, see how to obtain OSS resources in segments by using the HTTP Range header.

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.

Request parameters

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 headers are the metadata of the object to which the symbolic link points. The Last-Modified header is the later of the last modified time of the object to which the symbolic link points and the last modified time of the symbolic link. Other headers are the metadata of the symbolic link.

Examples

• Simple GetObject Request

  Request Example

  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 qn6q**************:77Dv****************

  Sample Response (when the object is a file)

  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 (when the object is a directory)

  Important

  If the object is a directory and the request includes custom response headers such as Range, the custom response headers are invalid.

  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 with Range Header

  Request Example

  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 qn6q**************:77Dv****************

  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 with Custom Response Headers

  Request Example

  GET /oss.jpg?response-expires=Thu%2C%2001%20Feb%202012%2017%3A00%3A00%20GMT&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: 中文
  Content-type: jpg
  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

  Request Example

  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 qn6q**************:77Dv****************

  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****

• RestoreObject Request Completed

  Request Example

  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 qn6q**************:77Dv****************

  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 with Specified Version ID

  Request Example

  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 qn6q**************:77Dv****************

  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 for an Object with a Delete Marker and No Specified Version ID

  Request Example

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

  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 for an Object with a Specified Version ID and a Delete Marker

  Request Example

  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 qn6q**************:77Dv****************

  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.aliyun*****</HostId>
    <Method>GET</Method>
    <ResourceType>DeleteMarker</ResourceType>
  </Error>

SDK

OSS SDKs for the following programming languages are available to call the GetObject operation:

• Java

• Python

• PHP

• Go V2

• C

• C++

• .NET

• Android

• iOS

• Node.js

• Browser.js

• Ruby

Command line tool ossutil

For more information about the ossutil command that corresponds to the GetObject operation, see get-object.

Error codes