Document Center

Head Object

Last Updated: Apr 17, 2018

Head Object is used to return the meta information of a certain object without returning the file content.

Request syntax

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

Request header

Name Description
If-Modified-Since If the specified time is earlier than the actual modification time, the system returns the 200 OK message and the object metadata; otherwise, the system returns the 304 Not Modified message.
Type: string
Default value: None
If-Unmodified-Since If the specified time is same as or later than the actual file modification time, the system returns the 200 OK message and the object metadata; otherwise, the system returns the 412 Precondition Failed message.
Type: string
Default value: None
If-Match If the expected ETag that is introduced matches the ETag of the object, the system returns the 200 OK message and the object metadata; otherwise, the system returns the 412 Precondition Failed message.
Type: string
Default value: None
If-None-Match If the introduced ETag does not match the ETag of the object, the system returns the 200 OK message and the object metadata; otherwise, the system returns the 304 Not Modified message.
Type: string
Default value: None

Detail analysis

  1. After the Head Object request is sent, no message body is returned even if the system returns the 200 OK message or an error message.
  2. The If-Modified-Since, If-Unmodified-Since, If-Match, and If-None-Match query conditions can be set in the header of the Head Object request. For the detailed setting rules, see the related fields in the Get Object request. If no modification is made, the system returns the 304 Not Modified message.
  3. If you upload the user meta prefixed with x-oss-meta- when sending a Put Object request, for example, x-oss-meta-location, the user meta is returned.
  4. If the file does not exist, the system returns Error 404 Not Found.
  5. If this object is entropy encrypted on the server, the system returns x-oss-server-side-encryption in the header of the response to the Head Object request. The value of x-oss-server-side-encryption indicates the server-side encryption algorithm of the object.
  6. If the file type is symbolic link, in the response header, Content-Length, ETag, and Content-Md5 are metadata of the target file, Last-Modified is the maximum value of the target file and symbolic link, and others are metadata of symbolic links.
  7. If the file type is symbolic link and the target file does not exist, the system returns Error 404 Not Found. The error code is “SymlinkTargetNotExist”.
  8. If the file type is symbolic link and the target file type is symbolic link, the system returns Error 400 Bad request. The error code is “InvalidTargetType”.
  9. If the bucket type is Archive, the object storage type is indicated by x-oss-storage-class in the response header.
  10. If the bucket type is Archive and the Restore request has been submitted, the Restore state of 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 has been submitted and does not time out, the value of x-oss-restore returned is ongoing-request=”true”.
    • If the Restore request has been submitted and completed, the value of x-oss-restore returned is ngoing-request=”false”, expiry-date=”Sun, 16 Apr 2017 08:12:33 GMT”.

Example

Request example:

  1. HEAD /oss.jpg HTTP/1.1
  2. Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  3. Date: Fri, 24 Feb 2012 07:32:52 GMT
  4. Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:JbzF2LxZUtanlJ5dLA092wpDC/E=

Return example:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 559CC9BDC755F95A64485981
  3. x-oss-object-type: Normal
  4. Date: Fri, 24 Feb 2012 07:32:52 GMT
  5. Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
  6. ETag: "fba9dede5f27731c9771645a39863328"
  7. Content-Length: 344606
  8. Content-Type: image/jpg
  9. Connection: keep-alive
  10. Server: AliyunOSS

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

  1. HEAD /oss.jpg HTTP/1.1
  2. Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
  3. Date: Sat, 15 Apr 2017 07:32:52 GMT
  4. Authorization: OSS e1Unnbm1rgdnpI:KKxkdNrUBu2t1kqlDh0MLbDb99I=

Return example:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 58F71A164529F18D7F000045
  3. x-oss-object-type: Normal
  4. x-oss-restore: ongoing-request="true"
  5. Date: Sat, 15 Apr 2017 07:32:52 GMT
  6. Last-Modified: Sat, 15 Apr 2017 06:07:48 GMT
  7. ETag: "fba9dede5f27731c9771645a39863328"
  8. Content-Length: 344606
  9. Content-Type: image/jpg
  10. Connection: keep-alive
  11. Server: AliyunOSS

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

  1. HEAD /oss.jpg HTTP/1.1
  2. Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
  3. Date: Sat, 15 Apr 2017 09:35:51 GMT
  4. Authorization: OSS e1Unnbm1rgdnpI:21qtGJ+ykDVmdu6O6FMJnn+WuBw=

Return example:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 58F725344529F18D7F000055
  3. x-oss-object-type: Normal
  4. x-oss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT"
  5. Date: Sat, 15 Apr 2017 09:35:51 GMT
  6. Last-Modified: Sat, 15 Apr 2017 06:07:48 GMT
  7. ETag: "fba9dede5f27731c9771645a39863328"
  8. Content-Length: 344606
Thank you! We've received your feedback.
Free Trial Free Trial