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 bucket policies to authorize other users to access OSS resources.
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 Calculation of 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. For more information, 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.
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-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.
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: 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: 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 use Gzip compression based on the Content-Type header and whether the size of the object is greater than or equal to 1 KB. When conditions are met, data is transmitted in the compressed form. Otherwise, data is transmitted in its original form. Note
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.
|
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 qn6q**************:77Dv****************
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
ImportantIf a GetObject request is initiated for a directory, custom response headers such as 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 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 that includes custom response headers
Sample request
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: en Content-encoding: utf-8 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
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 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****
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 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 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 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 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 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 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 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.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:
|
Not Modified | 304 | Possible causes:
|
Precondition Failed | 412 | Possible causes:
|
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. |