All Products
Search
Document Center

Object Storage Service:HeadObject

Last Updated:Dec 07, 2023

Queries the metadata of an object. When you call this operation, the object content is not returned in the response.

Versioning

  • By default, if you call the HeadObject operation to query the metadata of an object and do not specify a version ID in the request, the metadata of the current version of the object is returned. If the current version of the object is a delete marker, Object Storage Service (OSS) returns the HTTP status code 404 and the NoSuchKey error code.

  • If you call the HeadObject operation to query the metadata of an object and specify a version ID in the request, the metadata of the object of the specified version is returned. If you specify the version ID of a delete marker in a HeadObject request, OSS returns the HTTP status code 405 and the MethodNotAllowed error code.

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. Otherwise, OSS returns the HTTP status code 304 and the NotModified error code.

By default, this header is left empty.

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. Otherwise, OSS returns the HTTP status code 412 and the PreconditionFailed error code.

By default, this header is left empty.

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. Otherwise, OSS returns the HTTP status code 412 and the PreconditionFailed error code.

By default, this header is left empty.

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. Otherwise, OSS returns the HTTP status code 304 and the NotModified error code.

By default, this header is left empty.

For more information about the common request headers in HeadObject requests, such as Host and Date, see Common request headers.

Response headers

If the requested object is a symbolic link, take note of the following headers in the response:

  • The Content-Length, ETag, x-oss-storage-class, and Content-Md5 headers are the metadata of the object to which the symbolic link points.

  • The return value of the Last-Modified header uses 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 response headers are the metadata of the symbolic link.

Header

Type

Description

x-oss-meta-*

String

The custom headers that are prefixed with x-oss-meta-. These headers describe user metadata. If you specify headers prefixed with x-oss-meta- in a PutObject request, the user metadata of the object is included in the response.

Custom 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, the headers are included in the response. Example: x-oss-persistent-headers: key1:base64_encode(value1),key2:base64_encode(value2).....

x-oss-server-side-encryption

String

The algorithm used to encrypt the object at the server side. This header is included in the response if the object is encrypted by using the server-side encryption algorithm based on entropy encoding.

x-oss-server-side-encryption-key-id

String

The ID of the customer master key (CMK) that is used to encrypt the object. This header is included in the response if the object is encrypted by using Key Management Service (KMS) on the server side.

x-oss-storage-class

String

The storage class of the object. Valid values: Standard, IA, Archive, ColdArchive, and DeepColdArchive.

For more information about storage classes, see Overview.

x-oss-object-type

String

The type of the object. Valid values:

  • Normal: The object is uploaded by calling the PutObject or CreateDirectory operation.

  • Appendable: The object is uploaded by calling the AppendObject operation.

  • Multipart: The object is uploaded by using multipart upload.

x-oss-next-append-position

String

The position for the next append operation. If the type of the object is Appendable, this header is included in the response.

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 CRC-64, this header may not be included in the response when you call the HeadObject operation to query the metadata of the object.

x-oss-expiration

String

The expiration time of the object in the bucket for which lifecycle rules are configured.

  • Versioning enabled for the bucket

    • Version ID not included in the request

      If the object requested matches the delete conditions specified in the lifecycle rule, the x-oss-expiration header is included in the response to indicate the expiration time of the current version of the object.

    • Version ID included in the request

      Whether the object requested matches the delete conditions specified in the lifecycle rule, the x-oss-expiration header is not included in the response.

  • Versioning not enabled for the bucket

    • If the object requested matches the delete conditions specified in the lifecycle rule, the x-oss-expiration header is included in the response.

    • If the object requested does not match the delete conditions specified in the lifecycle rule, the x-oss-expiration header is not included in the response.

x-oss-restore

String

The status of the object when you restore an object. If a RestoreObject request is submitted for an Archive, Cold Archive, or Deep Cold Archive object, this header is included in the response.

  • If the RestoreObject request is not submitted or times out, this header is not included in the response.

  • If the RestoreObject request is submitted and the restoration is incomplete, the return value of this header is ongoing-request="true".

  • If the RestoreObject request is submitted and the restoration is complete, the return value of this header is in the following format: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT". The value of the expiry-date parameter indicates the time before which the restored object can be read.

x-oss-process-status

String

The result of an event notification that is triggered for the object. If you create an OSS event notification rule by using Message Service (MNS) and an operation performed on the object triggers the rule, this header is included in the response. The return value of this header is Base64-encoded in the JSON format.

x-oss-request-charged

String

The requester. This header is included in the response if the pay-by-requester mode is enabled for the bucket and the requester is not the bucket owner. The value of this header is requester.

Content-Md5

String

  • The Content-Md5. This header is included in the response if the object type is Normal. The value of this header is calculated by performing the following process: 1. Calculate the MD5 hash of the message content based on RFC 1864 to obtain a 128-bit digit. Do not include headers to calculate the MD5 hash. 2. Encode the digit by using Base64.

  • If the object type is Multipart or Appendable, this header is not included in the response.

Last-Modified

String

The time when the object was last modified. The time is in GMT specified in HTTP/1.1.

Access-Control-Allow-Origin

String

The origin allowed for cross-origin resource sharing (CORS). If a CORS rule is configured for the bucket that stores the object and the Origin header in the request meets the CORS rule, this header is included in the response.

Access-Control-Allow-Methods

String

The methods allowed for CORS. If 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, this header is included in the response.

Access-Control-Max-Age

String

The maximum caching period for CORS. If a CORS rule is configured for the bucket that stores the object and the request meets the CORS rule, this header is included in the response.

Access-Control-Allow-Headers

String

The headers allowed for CORS. If a CORS rule is configured for the bucket that stores the object and the request meets the CORS rule, this header is included in the response.

Access-Control-Expose-Headers

String

The headers that can be accessed by JavaScript applications on the client. If a CORS rule is configured for the bucket that stores the object and the request meets the CORS rule, this header is included in the response.

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.

For more information about the common response headers, such as ETag and x-oss-request-id, in the responses to HeadObject requests, see Common response headers.

Examples

  • Query the metadata of an object in an unversioned bucket

    Sample request

    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 for an object

    HTTP/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 response for a directory

    HTTP/1.1 200 OK
    x-oss-request-id: 559CC9BDC755F95A6448****
    x-oss-object-type: Normal
    x-oss-storage-class: Standard
    Date: Wed, 31 Mar 2021 07:32:52 GMT
    Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
    ETag: "null"
    Content-Length: 0
    Content-Type: application/x-directory
    Connection: keep-alive
    Server: AliyunOSS
  • Query the metadata of a specific version of an object in a versioning-enabled bucket

    Sample request

    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 response

    HTTP/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
  • Query the metadata of the current version of an object in a versioning-enabled bucket

    Sample request

    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 response

    HTTP/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
  • Query the metadata of an object for which the RestoreObject request is submitted and restoration is in progress

    Sample request

    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 response

    HTTP/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
  • Query the metadata of an object for which the RestoreObject request is submitted and restoration is complete

    Sample request

    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 response

    HTTP/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
  • Query the metadata of an object that is encrypted by using SSE-OSS

    Sample request

    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
  • Query the metadata of an object that is encrypted by using SSE-KMS

    Sample request

    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 requested object does not exist.

SymlinkTargetNotExist

404

The requested object is a symbolic link.

InvalidTargetType

400

The requested object is a symbolic link that points to another symbolic link.

NotModified

304

Possible causes:

  • The If-Modified-Since header is specified in the request, but the requested object has not been modified since the time specified in the request.

  • The If-None-Match header is specified in the request, and the ETag value in the request is the same as the ETag value of the requested object.

PreconditionFailed

412

Possible causes:

  • The If-Unmodified-Since header is specified in the request, but the specified time is earlier than the last modified time of the requested object.

  • The If-Match header is specified in the request, but the ETag value in the request is different from the ETag value of the requested object.