All Products
Search

This Product

    Object Storage Service:HeadObject

    Document Center

    Object Storage Service:HeadObject

    Last Updated:Oct 31, 2024

    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-transition-time

    String

    The time when the storage class of the returned objects is changed to Cold Archive or Deep Cold Archive based on lifecycle rules.

    Note

    • If the object is stored for more than 180 days after the storage class of the object is converted, you are not charged for the storage usage of the Cold Archive or Deep Cold Archive object that is stored for less than the minimum storage duration. If the object is stored for less than 180 days after the storage class of the object is converted, you are charged for the storage usage of the Cold Archive or Deep Cold Archive object that is stored for less than the minimum storage duration.

    • You cannot use this header to query the time when the storage class of the object is converted to Infrequent Access (IA) or Archive based on lifecycle rules. You can determine whether the object is stored for more than the minimum storage duration based on the value of the Last-Modified header.

    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 Simple Message Queue (SMQ) 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.

    Note

    • The minimum storage duration (30 days) of IA objects is calculated based on the last modified time of the objects. If the value of the Last-Modified header is 30 days earlier than the current time, you are not charged for the storage usage of the IA object that is stored for less than the minimum storage duration.

    • The minimum storage duration (60 days) of Archive objects is calculated based on the last modified time of the objects. If the value of the Last-Modified header is 60 days earlier than the current time, you are not charged for the storage usage of the Archive object that is stored for less than the minimum storage duration.

    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 qn6q**************:77Dv****************

      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 qn6q**************:77Dv****************

      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 qn6q**************:77Dv****************

      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 qn6q**************:77Dv****************

      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 qn6q**************:77Dv****************

      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 qn6q**************:77Dv****************

      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 qn6q**************:77Dv****************

      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.