Description
The GET Object API is used to download a file (object) from a COS bucket to a local directory. This operation requires the requester to have the read permission for the target object or the target object is publicly readable (public read).
Request
Request sample:
GET /<ObjectName> HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String
Note:
Authorization: Auth String (See Request Signature for details.)
Request Line
GET /{ObjectName} HTTP/1.1
This API accepts GET ask.
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| response-content-type | string | No | Set the Content-Type parameter in the response header. |
| response-content-language | string | No | Set the Content-Language parameter in the returned header. |
| response-expires | string | No | Set the Content-Expires parameter in the response header |
| response-cache-control | string | No | Set the Cache-Control parameter in the response header. |
| response-content-disposition | string | No | Set the Content-Disposition parameter in the response header. |
| response-content-encoding | string | No | Set the Content-Encoding parameter in the response header. |
| versionId | string | No | Version ID to download when versioning is enabled. If it is not specified, the latest version of the object is downloaded. |
Request Header
Common Headers
This request uses common request headers. For details, see Common Request Headers.
Non-common Headers
| Name | Type | Required | Description |
|---|---|---|---|
| Range | string | No | The specified file download range defined in RFC 2616, in bytes. |
| If-Unmodified-Since | string | No | The file content is returned only if the file modification time is earlier than or equal to the specified time. Otherwise, 412 (precondition failed) is returned. |
| If-Modified-Since | string | No | If the object has been modified after the specified time, the meta-information of the corresponding object is returned; otherwise, a 304 (not modified) response is returned. |
| If-Match | string | No | The file is returned only when the ETag matches the specified content. Otherwise, 412 (precondition failed) is returned. |
| If-None-Match | string | No | The file is returned only when the ETag does not match the specified content. Otherwise, 304 (not modified) is returned. |
Request Body
The request does not have a request body.
Response
Response Headers
In addition to common response headers, this API returns the following response headers. For details about common response headers, see Common Response Headers.
| Name | Description | Type |
|---|---|---|
| Cache-Control | Cache instruction defined in RFC 2616, which is returned only if it is contained in the object metadata or specified in the request parameters. | string |
| Content-Disposition | File name defined in RFC 2616, which is returned only if it is contained in the object metadata or specified in the request parameters. | string |
| Content-Encoding | Encoding format defined in RFC 2616, which is returned only if it is contained in the object metadata or specified in the request parameters. | string |
| Content-Range | Byte range of the content to be returned defined in RFC 2616, which is returned only when a Range request header is specified in the request. | string |
| Expires | Cache expiration time defined in RFC 2616, which is returned only if it is contained in the object metadata or specified in the request parameters. | string |
| x-cos-meta-* | Includes the user-defined metadata header suffix and user-defined metadata information. | string |
| x-cos-storage-class | Storage type of an object, such as STANDARD_IA and ARCHIVE. This header is returned only if the object is not of the standard storage (STANDARD) type. | Enum |
Versioning-related headers
The following table describes the response headers returned for objects in a versioning-enabled bucket.
| Name | Description | Type |
|---|---|---|
| x-cos-version-id | Version ID of an object. | string |
Response Body
The download was successful and the file content is in the response body.
Error Code
| Error Code | Description | HTTP Status Code |
|---|---|---|
| InvalidArgument | Wrong parameters provided | 400 Bad Request |
| SignatureDoesNotMatch | If this error code is returned, it means the provided signature is incorrect. | 403 Forbidden |
| NoSuchKey | If the downloaded file does not exist, this error code is returned | 404 Not Found |
Practical Case
Request 1
GET /123 HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Wed, 28 Oct 2014 22:32:00 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1484212200;32557108200&q-key-time=1484212200;32557108200&q-header-list=host&q-url-param-list=&q-signature=11522aa3346819b7e5e841507d5b7f156f34e639
Response 1
HTTP/1.1 200 OK
Date: Wed, 28 Oct 2014 22:32:00 GMT
Content-Type: application/octet-stream
Content-Length: 16087
Connection: keep-alive
Accept-Ranges: bytes
Content-Disposition: attachment; filename=\"filename.jpg\"
Content-Range: bytes 0-16086/16087
ETag: \"9a4802d5c99dafe1c04da0a8e7e166bf\"
Last-Modified: Wed, 28 Oct 2014 20:30:00 GMT
x-cos-request-id: NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ==
[Object]
Request 2
Carry response-xxx parameters
GET /123?response-content-type=application%2fxml HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Wed, 28 Oct 2014 22:32:00 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1484212200;32557108200&q-key-time=1484212200;32557108200&q-header-list=host&q-url-param-list=&q-signature=11522aa3346819b7e5e841507d5b7f156f34e639
Response 2
HTTP/1.1 200 OK
Date: Wed, 28 Oct 2014 22:32:00 GMT
Content-Type: application/xml
Content-Length: 16087
Connection: keep-alive
Accept-Ranges: bytes
Content-Disposition: attachment; filename=\"filename.jpg\"
Content-Range: bytes 0-16086/16087
ETag: \"9a4802d5c99dafe1c04da0a8e7e166bf\"
Last-Modified: Wed, 28 Oct 2014 20:30:00 GMT
x-cos-request-id: NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ==
[Object]