金山云-文档中心-HEAD Object

Standard Storage Service (KS3)

View more results

Document title with current keyword not found

Description

You can call this operation to obtain metadata from an object without getting the object. To call this operation, you must have the read permissions on the object.

The HEAD request and GET request on an object are fulfilled in the same way. The HEAD response is identical because it does not contain a response body.

Permission

To call this operation, you must have read permission on the object. If the requested object does not exist, Kingsoft Cloud Standard Storage Service (KS3) returns corresponding information based on whether you have read permission.

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

HEAD /{ObjectKey} HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}

References:

Request parameters

No request parameter is used.

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: 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 body

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 metadata is returned. Type: String
x-kss-restore	The object restoration status and expiration time. This header will be returned if the requested object is under restoration (with the value `x-kss-restore: ongoing-request="true"`) or has been restored (with the value `x-kss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT"`). This header will not be returned if the requested object is stored in standard or infrequent access storage or is archived. 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

HEAD /my-image.jpg HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample response

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "54a3be97af36cdc9f2516c74550fa95d"
x‑kss‑tagging‑count:2
Content-Length: 434234
Content-Type: text/plain
Connection: close
Server: Tengine
Content-MD5:VKO+l682zcnyUWx0VQ+pXQ==

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 response does not involve a response body regardless of the request result.
You can call this operation to check whether an object exists.
You can call this operation to obtain metadata of an object.
The x‑kss‑tagging‑count header is returned only if you have the ks3:GetObjectTagging permission on tags. If you have only the ks3:GetObject permission but not the ks3:GetObjectTagging permission, the x-kss-tagging-count header will not be returned.

On this page

Previous:GET Object

Next:PUT Object

Pure ModeNormal Mode

Pure Mode

Click to preview the document content in full screen