GET Object

Last updated:2021-09-18 10:58:43

Description

You can call this operation to obtain objects from Kingsoft Cloud Standard Storage Service (KS3). To call this operation, you must have the read permissions on the object. If you grant read permissions to the anonymous user, no signature is required in this operation. To generate a download link, see Send signatures by using URL query strings.

A KS3 bucket does not have a directory hierarchy, as you can find in a typical computer file system. However, you can set the value that implies a folder structure to the object key to achieve a logical hierarchy. For example, you can name an object photos/2006/February/sample.jpg instead of sample.jpg.

In this operation, you can specify the full name of an object to obtain an object with a logical hierarchy. Assume that an object named photos/2006/February/sample.jpg is placed in a bucket named as examplebucket. In this case, the logical resource name can be /examplebucket/photos/2006/February/sample.jpg.

Permission

To call this operation, you must have the read permissions on the object. If the requested object does not exist, KS3 responds based on whether you have the read permissions.

  • If you have the read permissions on the bucket, KS3 returns an HTTP 404 error with the error message “no such key.”
  • If you do not have the read permissions on the bucket, KS3 returns an HTTP 403 error with the error message “access denied.”

Request

Request syntax

GET /{ObjectKey} HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}
Range:bytes=byte_range

References:

Request parameters

Assume that you require a specific response header, for example, Content-Disposition to be returned in the GET response. You need to set the response header in the GET request.

You can set response headers by using the request parameters listed in the table below. The headers take effect only when KS3 returns HTTP status code 200. You can set Content-Type, Content-Language, Expires, Cache-Control, Content-Disposition, and Content-Encoding to be returned by using the following parameters.

Parameter Description Required
response-content-type Specifies the response header Content-Type.
Type: String
Default value: None
No
response-content-language Specifies the response header Content-Language.
Type: String
Default value: None
No
response-expires Specifies the response header Expires.
Type: String
Default value: None
No
response-cache-control Specifies the response header Cache-Control.
Type: String
Default value: None
No
response-content-disposition Specifies the response header Content-Disposition.
Type: String
Default value: None
No
response-content-encoding Specifies the response header Content-Encoding.
Type: String
Default value: None
No

Request headers

This operation supports all common request headers and the request headers that are described in the following table. For more information, see Common request headers.

Header Description Required
Range The range byte of an object to download. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.35.
Type: String
Default value: None
Constraint: None
No
If-Modified-Since Specifies whether the object is modified after the specified time. If the object is modified after the specified time, the object will be returned; otherwise, HTTP status code 304 is returned.
Type: String
Default value: None
Constraint: None
No
If-Unmodified-Since Specifies whether the object is not modified after the specified time. If the object is not modified after the specified time, the object will be returned; otherwise, HTTP status code 412 is returned.
Type: String
Default value: None
Constraint: None
No
If-Match Specifies whether the object matches the specified value. If the ETag(entity tag) of the object is the same as the specified value, the object is returned; otherwise, HTTP status code 412 is returned.
Type: String
Default value: None
Constraint: None
No
If-None-Match Specifies whether the object does not match the specified value. If the ETag(entity tag) of the object is different from the specified value, the object is returned; otherwise, HTTP status code 304 is returned.
Type: String
Default value: None
Constraint: None
No

Request

No request body is used.

Response

Response headers

Header Description
Content-MD5 The BASE64-coded MD5 value of the object. This header is returned only if the object is uploaded to KS3 through PUT or POST. It is not returned if the object is uploaded in multiple parts.
x-kss-meta-* The user metadata. This header is returned if you use user metadata in the PUT Object operation with a prefix of x-kss-meta- and a custom suffix. The same mta is returned.
Type: String
x-kss-storage-class The storage class of an object. Valid values: STANDARD_IA (indicating infrequent access storage) and ARCHIVE (indicating archival storage). If standard storage is used, this header will not be returned.
Type: String
ETag The 32-bit hexadecimal string used to identify the Object content. Each ETag specifies a unique Object. The ETag of an Object created by using the Put Object or Post Object request is the MD5 value of the object content. The ETag of an Object created by uploading in multiple parts is an MD5 value calculated after the MD5 values of all parts are combined. You can use the ETag to check whether the Object content has changed.
Type: String
x‑kss‑tagging‑count The number of tags associated with an object. This header is returned only if you have the read permissions on tags.
Type: String

Response body

No response body is returned.

Operation-specific errors

This operation does not return operation-specific errors.

Examples

Sample request

GET /my-image.jpg HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Fri, 26 Dec 2014 06:48:45 GMT
Authorization: authorization string

Sample response

HTTP/1.1 200 OK
x-kss-request-id: 5a868ca0ebd74bcc8eff1f1a7c9bcd6c
Date: Fri, 26 Dec 2014 06:48:46 GMT
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "798308f9638ea5b28d5f25e4d677ffac"
Content-Length: 434234
Content-Type: text/plain
Connection: close
Server: Tengine
Content-MD5:eYMI+WOOpbKNXyXk1nf/rA==
[434234 bytes of object data]

Notes:

1. If an object is uploaded to KS3 in multiple parts, the Content_MD5 header will not be returned when you call the GET operation.

2. If an object is uploaded to KS3 through PUT or POST, the Content_MD5 header will be returned when you call the GET operation.

Usage notes

  • The setting of request parameters takes effect only when KS3 returns HTTP status code 200.
  • The value of Range must be in the correct format; otherwise, KS3 will return HTTP status code 416.
  • The x‑kss‑tagging‑count header is returned only if you have the ks3:GetObjectTagging permission on tags. If you have the ks3:GetObject permission but not the ks3:GetObjectTagging permission, the x-kss-tagging-count header will not be returned.
  • For more information about how to download a private file by using a browser, see Send signatures by using URL query strings.

Did you find the above information helpful?

Unhelpful
Mostly Unhelpful
A little helpful
Helpful
Very helpful

What might be the problems?

Insufficient
Outdated
Unclear or awkward
Redundant or clumsy
Lack of context for the complex system or functionality

More suggestions

0/200

Please give us your feedback.

Submitted

Thank you for your feedback.

问题反馈