You can call this operation to query the metadata of an object. The object content is not included in the returned results.
Versioning
By default, the HeadObject operation queries the metadata of the current version of an object. If the current version of the object is a delete marker, OSS returns 404 Not Found. If you specify the version ID in your request, OSS returns the metadata of the object with the specified version ID.
Request syntax
HEAD /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Request headers
Header | Type | Required | Description |
---|---|---|---|
If-Modified-Since | String | No | The information return condition. If the specified time is earlier than the last modified
time of the object, OSS returns the metadata of the object and 200 OK. If the specified
time is equal to or later than the last modified time of the object, OSS returns 304
Not Modified.
Default value: none |
If-Unmodified-Since | String | No | The information return condition. If the specified time is equal to or later than
the last modified time of the object, OSS returns the metadata of the object and 200
OK. If the specified time is earlier than the last modified time of the object, OSS
returns 412 Precondition Failed.
Default value: none |
If-Match | String | No | The information return condition. If the input ETag value matches the ETag value of
the object, OSS returns the metadata of the object and 200 OK. If the input ETag value
does not match the ETag value of the object, OSS returns 412 Precondition Failed.
Default value: none |
If-None-Match | String | No | The information return condition. If the input ETag value does not match the ETag
value of the object, OSS returns the metadata of the object and 200 OK. If the input
ETag value matches the ETag value of the object, OSS returns 304 Not Modified.
Default value: none |
Response headers
If the requested object is a symbolic link, the following headers are included in the response:
- The Content-Length, ETag, and Content-Md5 header are the metadata of the object that the symbolic link points to.
- The Last-Modified header is the later one of the last modified time of the symbolic link and the object that the symbolic link points to.
- Other headers are the metadata of the symbolic link.
Header | Type | Description |
---|---|---|
x-oss-meta-* | String | Headers prefixed with x-oss-meta- are the user metadata. If you specify headers prefixed with x-oss-meta- in the PutObject request, the user metadata of the object is included in the response. |
User metadata headers that are not prefixed with x-oss-meta- | String | If you specify headers that are not prefixed with x-oss-meta- in the PutObject request to configure the user metadata of the object, for example, x-oss-persistent-headers:key1:base64_encode(value1),key2:base64_encode(value2)...., the headers are included in the response. |
x-oss-server-side-encryption | String | This header is included in the response if the object is encrypted by using entropy encoding at the server side. The value of this header is the algorithm used to encrypt the object at the server side. |
x-oss-server-side-encryption-key-id | String | This header is included in the response if the object is encrypted by using KMS at the server side. The value of this header is the CMK ID used to encrypt the object. |
x-oss-storage-class | String | The storage class of the object.
Valid values:
|
x-oss-object-type | String | The type of the object. Valid values:
|
x-oss-next-append-position | String | The position for the next append operation. This header is included in the response only when the type of the object is Appendable. |
x-oss-hash-crc64ecma | String | The 64-bit CRC value of the object. This value is calculated based on the ECMA-182
standard.
If an object is created before OSS supports CRC64, this header may not be included in the response when you call HeadObject to query the metadata of the object. |
x-oss-expiration | String | The lifecycle information about the object. This header is included in the response if lifecycle rules are configured for the object. This header contains two parameters: expiry-date that specifies the expiration date of the object, and rule-id that specifies the ID of the matched lifecycle rule. |
x-oss-restore | String | The restoration state of the object. This header is included in the response when
the storage class of the bucket is Archive and a RestoreObject request is submitted.
|
x-oss-process-status | String | The result of event notification performed for the object. This header is included in the response if you create an OSS event notification rule by using MNS and an operation performed on the object triggers the rule. The value of this header is base64-encoded and in the JSON format. |
x-oss-request-charged | String | This header is included in the response when pay-by-requester is enabled for the bucket and the requester is not the bucket owner. The value of this header is requester. |
Content-Md5 | String |
|
Last-Modified | String | The latest time when the object is modified. The time is in the GMT format specified in HTTP 1.1. |
Access-Control-Allow-Origin | String | The allowed origins in CORS. This header is included in the response when a CORS rule is configured for the bucket that stores the object and the Origin header in the request meets the CORS rule. |
Access-Control-Allow-Methods | String | The allowed methods in CORS. This header is included in the response when a CORS rule is configured for the bucket that stores the object and the Access-Control-Request-Method header in the request meets the CORS rule. |
Access-Control-Max-Age | String | The maximum cache period in CORS. This header is included in the response when a CORS rule is configured for the bucket that stores the object and the request meets the CORS rule. |
Access-Control-Allow-Headers | String | The allowed headers in CORS. This header is included in the response when a CORS rule is configured for the bucket that stores the object and the request meets the CORS rule. |
Access-Control-Expose-Headers | String | The list of header fields that can be accessed by JavaScript applications on the client. The exposed headers in CORS. This header is included in the response when a CORS rule is configured for the bucket that stores the object and the request meets the CORS rule. |
x-oss-tagging-count | String | The number of tags added to the object. This header is included in the response only when you have read permissions on tags. |
Examples
- Sample request for querying the metadata of an object in an unversioned bucket
HEAD /oss.jpg HTTP/1.1 Host: oss-example.oss-cn-hangzhou.aliyuncs.com Date: Fri, 7 Aug 2020 07:32:52 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:JbzF2LxZUtanlJ5dLA092wpD****
Sample responseHTTP/1.1 200 OK x-oss-request-id: 559CC9BDC755F95A6448**** x-oss-object-type: Normal x-oss-storage-class: Archive Date: Fri, 7 Aug 2020 07:32:52 GMT Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT ETag: "fba9dede5f27731c9771645a3986****" Content-Length: 344606 Content-Type: image/jpg Connection: keep-alive Server: AliyunOSS
- Sample request for querying the metadata of a specified object version in a versioned
bucket
HEAD /example? versionId=CAEQNRiBgICb8o6D0BYiIDNlNzk5NGE2M2Y3ZjRhZTViYTAxZGE0ZTEyMWYy**** Host: versioning-test.oss-cn-hangzhou.aliyuncs.com Date: Fri, 7 Aug 2020 06:27:12 GMT Authorization: OSS ryghu9rp3mqp1ya:RvyjGvKxaUhdF0ibyEwX5mOM****
Sample responseHTTP/1.1 200 OK x-oss-versionId: CAEQNRiBgICb8o6D0BYiIDNlNzk5NGE2M2Y3ZjRhZTViYTAxZGE0ZTEyMWYy**** x-oss-request-id: 5CAC3B40B7AEADE01700**** x-oss-object-type: Normal x-oss-storage-class: Archive Date: Fri, 7 Aug 2020 06:27:12 GMT Last-Modified: Fri, 7 Aug 2020 06:27:12 GMT ETag: "A082B659EF78733A5A042FA253B1****" Content-Length: 481827 Content-Type: text/html Connection: keep-alive Server: AliyunOSS
- Sample request for querying the metadata of the current object version in a versioned
bucket
HEAD /example HTTP/1.1 Host: versioning-test.oss-cn-hangzhou.aliyuncs.com Date: Fri, 7 Aug 2020 06:27:12 GMT Authorization: OSS ryghu9rp3mqp1ya:RvyjGvKxaUhdF0ibyEwX5mOM****
Sample responseHTTP/1.1 200 OK x-oss-versionId: CAEQMxiBgMCZov2D0BYiIDY4MDllOTc2YmY5MjQxMzdiOGI3OTlhNTU0ODIx**** x-oss-request-id: 5CAC3B40B7AEADE01700**** x-oss-object-type: Normal x-oss-storage-class: Archive Date: Fri, 7 Aug 2020 06:27:12 GMT Last-Modified: Fri, 7 Aug 2020 06:27:12 GMT ETag: "3663F7B0B9D3153F884C821E7CF4****" Content-Length: 485859 Content-Type: text/html Connection: keep-alive Server: AliyunOSS
- Sample request for querying the metadata of an object for which the RestoreObject
request is submitted but the restoration is not complete
HEAD /oss.jpg HTTP/1.1 Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com Date: Fri, 7 Aug 2020 07:32:52 GMT Authorization: OSS e1Unnbm1rgdnpI:KKxkdNrUBu2t1kqlDh0MLbDb****
Sample responseHTTP/1.1 200 OK x-oss-request-id: 58F71A164529F18D7F00**** x-oss-object-type: Normal x-oss-storage-class: Archive x-oss-restore: ongoing-request="true" Date: Fri, 7 Aug 2020 07:32:52 GMT Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT ETag: "fba9dede5f27731c9771645a3986****" Content-Length: 344606 Content-Type: image/jpg Connection: keep-alive Server: AliyunOSS
- Sample request for querying the metadata of an object for which the RestoreObject
request is submitted and the restoration is complete
HEAD /oss.jpg HTTP/1.1 Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com Date: Fri, 7 Aug 2020 09:35:51 GMT Authorization: OSS e1Unnbm1rgdnpI:21qtGJ+ykDVmdu6O6FMJnn+W****
Sample responseHTTP/1.1 200 OK x-oss-request-id: 58F725344529F18D7F00**** x-oss-object-type: Normal x-oss-storage-class: Archive x-oss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT" Date: Fri, 7 Aug 2020 09:35:51 GMT Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT ETag: "fba9dede5f27731c9771645a3986****" Content-Length: 344606
- Sample request for querying the metadata of an object that is encrypted by using SSE-OSS
at the server side
HEAD /oss.jpg HTTP/1.1 Host: oss-example.oss-cn-hangzhou.aliyuncs.com Date: Fri, 7 Aug 2020 07:32:52 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:JbzF2LxZUtanlJ5dLA092wpD****
Sample response
HTTP/1.1 200 OK x-oss-request-id: 559CC9BDC755F95A6448**** x-oss-object-type: Normal x-oss-storage-class: Archive x-oss-server-side-encryption: AES256 Date: Fri, 7 Aug 2020 07:32:52 GMT Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT ETag: "fba9dede5f27731c9771645a3986****" Content-Length: 344606 Content-Type: image/jpg Connection: keep-alive Server: AliyunOSS
- Sample request for querying the metadata of an object that is encrypted by using SSE-KMS
at the server side
HEAD /oss.jpg HTTP/1.1 Host: oss-example.oss-cn-hangzhou.aliyuncs.com Date: Fri, 7 Aug 2020 07:32:52 GMT Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:JbzF2LxZUtanlJ5dLA092wpD****
Sample response
HTTP/1.1 200 OK x-oss-request-id: 559CC9BDC755F95A64485981 x-oss-object-type: Normal x-oss-storage-class: Archive x-oss-server-side-encryption: KMS x-oss-server-side-encryption-key-id: 9468da86-3509-4f8d-a61e-6eab1eac**** Date: Fri, 7 Aug 2020 07:32:52 GMT Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT ETag: "fba9dede5f27731c9771645a3986****" Content-Length: 344606 Content-Type: image/jpg Connection: keep-alive Server: AliyunOSS
Error codes
Error code | HTTP status code | Description |
---|---|---|
NoSuchKey | 404 | The error message returned because the requested object does not exist. |
SymlinkTargetNotExist | 404 | The error message returned because the requested object is a symbolic link. |
InvalidTargetType | 400 | The error message returned because the requested object is a symbolic link that points to another symbolic link. |
Not Modified | 304 |
|
Precondition Failed | 412 |
|