Obtains the meta information about an object without returning the object content.

Note If you upload the user meta information prefixed with x-oss-meta- when sending a PutObject request, for example, x-oss-meta-location, the user meta information is returned.

Versioning

By default, HeadObject obtains the meta information about the current version of an object. If the current version of the target object is a delete marker, the 404 Not Found error is returned. You can specify the versionId to obtain the meta information about a specified version of the target object.

Request syntax

HEAD /ObjectName HTTP/1.1
Host: BucketName/oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request header

Header Type Required? Description
If-Modified-Since String No If the time specified in the parameter is earlier than the modification time, OSS returns the 200 OK message and the object meta information. Otherwise, the 304 Not Modified message is returned.

Default value: None
If-Unmodified-Since String No If the time specified in the parameter is the same as or later than the object modification time, OSS returns the 200 OK message and the object meta information. Otherwise, the 412 Precondition Failed message is returned.

Default value: None
If-Match String No If the introduced ETag matches the ETag of the object, OSS returns the 200 OK message and the object meta information. Otherwise, the 412 Precondition Failed message is returned.

Default value: None
If-None-Match String No If the introduced ETag does not match the ETag of the object, OSS returns the 200 OK message and the object meta information. Otherwise, the 304 Not Modified message is returned.

Default value: None

Response header

Note If the type of the requested object is symbol link, the content of the object is returned. In the response header, Content-Length, ETag, and Content-Md5 are the meta information of the requested object, Last-Modified is the maximum value of the requested object and symbol link (that is, the later modification time), and other parameters are the meta information of the symbol link.
Header Type Description
x-oss-meta-* String Indicates a custom meta header. If you upload the user meta information prefixed with x-oss-meta- when sending a PutObject request, the user meta information is returned.
Custom header with a prefix excluding x-oss-meta- String Indicates a custom header with a prefix excluding x-oss-meta-. If you upload the user meta information with a prefix (excluding x-oss-meta-), for example, x-oss-persistent-headers key1:base64_encode(value1),key2:base64_encode(value2)...., when sending a PutObject request, the user meta information prefixed with the corresponding custom headers is returned.
x-oss-server-side-encryption String If the requested object is encrypted with the entropy coding algorithm on the server, OSS decrypts the object and includes this header in the response to indicate the encryption algorithm used to encrypt the object on the server.
x-oss-server-side-encryption-key-id String Indicates the Key Management Service (KMS) key ID of a user. This header is returned if you use KMS to encrypt an object when crating the object.
x-oss-storage-class String Indicates the storage class of an object. The storage class includes Standard, IA, Archive and ColdArchive.
  • Standard storage provides highly reliable, highly available, and high-performance object storage services that support frequent data access.
  • Infrequent Access storage is applicable to the scenario where data needs to be stored for a long time and is not frequently accessed. (The monthly access frequency is 1 to 2 times on average.)
  • Archive storage is applicable to the scenario where data needs to be stored for more than six months and is rarely accessed during the storage period. The stored data takes about one minute to become readable.
  • Cold Archive storage is applicable to the scenario where data needs to be stored for a very long time and is rarely accessed during the storage period.
x-oss-object-type String Indicates the object type.
  • The type of objects that are uploaded through PutObject is Normal.
  • The type of objects that are uploaded through AppendObject is Appendable.
  • The type of objects that are uploaded through MultipartUpload is Multipart.
x-oss-next-append-position String Specifies the position to be provided for the next request. This header is returned for Appendable objects.
x-oss-hash-crc64ecma String Indicates the 64-bit CRC value of the object. This value is calculated based on the ECMA-182 standard. An existing object may not have this value.
x-oss-expiration String If the lifecycle rule is configured for the object, the x-oss-expiration header is returned. In the returned header, the value of expiry-date is the expiration date of the object, and the value of rule-id is the corresponding rule ID.
x-oss-restore String If the bucket type is Archive and the Restore request is submitted, the Restore state of the object is indicated by x-oss-restore in the response header.
  • If the Restore request is not submitted or times out, the field is not returned.
  • If the Restore request is submitted and does not time out, the value of x-oss-restore returned is ongoing-request=”true”.
  • If the Restore request is submitted and completed, the value of x-oss-restore returned is ongoing-request=”false”, expiry-date=”Sun, 16 Apr 2017 08:12:33 GMT”. In the returned value, the value of expiry-date is the expiration date of the readable state of the restored file.
x-oss-process-status String After you create an OSS event notification through MNS and send a request to perform OSS operations, if a matching event notification rule is detected, this header is returned. In this case, the value is the event notification result in the Base64 encoded JSON format.
x-oss-request-charged String If fees of the bucket to which the object belongs is paid by the requester, not the bucket owner, this header is returned with the value of requester.
Content-Md5 String The message content (excluding headers) of Normal objects is calculated based on the RFC 1864 standard, and a 128-bit number is obtained. The Content-Md5 value of a message is obtained after the 128-bit number is encoded based on Base64. This header is not returned in Multipart and Appendable objects.
Last-Modified String Indicates 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 When the CORS rule is configured for the bucket to which the object belongs, if the requested origin meets the specified CORS rule, the origin is returned.
Access-Control-Allow-Methods String When the CORS rule is configured for the bucket to which the object belongs, if the requested Access-Control-Request-Method meets the specified CORS rule, the corresponding methods are returned.
Access-Control-Max-Age String When the CORS rule is configured for the bucket to which the object belongs, if a request meets the specified CORS rule, the value of MaxAgeSeconds is returned.
Access-Control-Allow-Headers String When the CORS rule is configured for the bucket to which the object belongs, if a request meets the specified CORS rule, the headers are returned.
Access-Control-Expose-Headers String Indicates the list of headers that can access the client JavaScript. When the CORS rule is configured for the bucket to which the object belongs, if a request meets the specified CORS rule, the ExposeHeader is returned.
x‑oss‑tagging‑count String Specifies the number of tags associated with the object. The value of this parameter returns only if the user has permission to read tags.

Examples

  • Normal request example:

    HEAD /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 07:32:52 GMT
Authorization: OSS qn6qrrqxo2oawuk53otf****:JbzF2LxZUtanlJ5dLA092wpD****

    Response example:

    HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Fri, 24 Feb 2012 07:32:52 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

  • Example of a request when the Restore request has been submitted but not completed:

    HEAD /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Sat, 15 Apr 2017 07:32:52 GMT
Authorization: OSS e1Unnbm1rg****:KKxkdNrUBu2t1kqlDh0MLbDb****

    Response example:

    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: Sat, 15 Apr 2017 07:32:52 GMT
Last-Modified: Sat, 15 Apr 2017 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

  • Example of a request when the Restore request has been submitted and completed:

    HEAD /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Sat, 15 Apr 2017 09:35:51 GMT
Authorization: OSS e1Unnbm1rg****:21qtGJ+ykDVmdu6O6FMJnn+W****

    Response example:

    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: Sat, 15 Apr 2017 09:35:51 GMT
Last-Modified: Sat, 15 Apr 2017 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 344606

  • Example of a request initiated to obtain the meta information about the current version of an object: 

    HEAD /example?versionId=CAEQNRiBgICb8o6D0BYiIDNlNzk5NGE2M2Y3ZjRhZTViYTAxZGE0ZTEyMWYyNDFm
Host: versioning-test.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 06:27:12 GMT
Authorization: OSS ryghu9rp3mq****:RvyjGvKxaUhdF0ibyEwX5mOM****

    Response example:

    HTTP/1.1 200 OK
x-oss-versionId: CAEQNRiBgICb8o6D0BYiIDNlNzk5NGE2M2Y3ZjRhZTViYTAxZGE0ZTEyMWYyNDFm
x-oss-request-id: 5CAC3B40B7AEADE01700****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Tue, 09 Apr 2019 06:27:12 GMT
Last-Modified: Tue, 09 Apr 2019 06:27:12 GMT
ETag: "A082B659EF78733A5A042FA253B19BA4"
Content-Length: 481827
Content-Type: text/html
Connection: keep-alive
Server: AliyunOSS

Error codes

Error code HTTP status code Description
NoSuchKey 404 The request object does not exist.
SymlinkTargetNotExist 404 The requested object is a symbol link.
InvalidTargetType 400 The requested and the target objects are a symbol link is a symbol link and the target.
Not Modified 304
  • The If-Modified-Since header is specified in the request, but the source object has not been modified after the time specified in the request.
  • The If-None-Match header is specified in the request, and the ETag provided in the request is the same as the ETag of the source object.
Precondition Failed 412
  • The If-Unmodified-Since header is specified, but the time specified in the request is earlier than the object modification time.
  • The If-Match header is specified, but the provided ETag is different from the ETag of the source object.