HeadObject接口用于獲取某個文件（Object）的元數據。使用此接口不會返回文件內容。
版本控制
在請求參數中不指定versionId的情況下執行HeadObject操作，默認獲取當前版本Object的元數據。如果當前版本Object為刪除標記，則返回404 NoSuchKey。
在請求參數中指定versionId的情況下執行HeadObject操作，返回指定版本Object的元數據。不支持在請求參數中指定刪除標記的versionId，否則返回405 MethodNotAllowed。
請求語法
HEAD /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue當您在OSS ON云盒中調用該接口時，您需要將Host替換為云盒Endpoint。更多信息，請參見云盒Endpoint。
請求頭
名稱 | 類型 | 是否必選 | 描述 |
If-Modified-Since | 字符串 | 否 | 如果傳入參數中的時間早于實際修改時間，則返回200 OK和Object Meta；否則返回304 Not Modified。 默認值：無 |
If-Unmodified-Since | 字符串 | 否 | 如果傳入參數中的時間等于或者晚于文件實際修改時間，則返回200 OK和Object Meta；否則返回412 Precondition Failed。 默認值：無 |
If-Match | 字符串 | 否 | 如果傳入期望的ETag和Object的 ETag匹配，則返回200 OK和Object Meta；否則返回412 precondition failed。 默認值：無 |
If-None-Match | 字符串 | 否 | 如果傳入期望的ETag值和Object的ETag不匹配，則返回200 OK和Object Meta；否則返回304 Not Modified。 默認值：無 |
此接口還包含Host、Date等公共請求頭。更多信息，請參見公共請求頭（Common Request Headers）。
響應頭
如果請求的文件類型為軟鏈接，則各個響應頭的信息說明如下：
Content-Length、ETag、x-oss-storage-class以及Content-Md5均為目標文件的元數據。
Last-Modified取軟鏈接的最后修改時間及目標文件的最后修改時間兩者中的較大值。
其他響應頭均表示軟鏈接的元數據。
名稱 | 類型 | 描述 |
x-oss-meta-* | 字符串 | 以x-oss-meta-為前綴的參數作為用戶自定義meta header。當用戶在PutObject時設置了以x-oss-meta-為前綴的自定義meta，則響應中會包含這些自定義meta。 |
非x-oss-meta-開頭的自定義header | 字符串 | 當用戶在PutObject時，自定義一些非x-oss-meta為前綴的Header，如x-oss-persistent-headers:key1:base64_encode(value1)，key2:base64_encode(value2).... ，響應中會增加相應的自定義Header。 具體操作，請參見OSS如何添加非x-oss-meta-開頭的自定義。 |
x-oss-server-side-encryption | 字符串 | 如果該Object進行服務器端熵編碼加密存儲的，則在響應頭中會返回此參數，其值表明該Object的服務器端加密算法。 |
x-oss-server-side-encryption-key-id | 字符串 | 如果用戶在創建Object時使用了服務端加密，且加密方法為KMS，則響應中會包含此Header，表示加密所使用的用戶KMS key ID。 |
x-oss-storage-class | 字符串 | 表示Object的存儲類型，分別為標準存儲類型（Standard）、低頻訪問存儲類型（IA）、歸檔存儲類型（Archive）、冷歸檔存儲類型（ColdArchive）以及深度冷歸檔存儲類型（DeepColdArchive）。 更多信息，請參見存儲類型介紹。 |
x-oss-object-type | 字符串 | 表示Object的類型。
|
x-oss-next-append-position | 字符串 | 對于Appendable類型的Object會返回此Header，指明下一次請求應當提供的position。 |
x-oss-hash-crc64ecma | 字符串 | 表示該Object的64位CRC值。該64位CRC根據ECMA-182標準計算得出。 對OSS支持CRC64校驗前創建的Object，調用HeadObject接口時可能不會返回此響應頭。 |
x-oss-transition-time | 字符串 | Object通過生命周期規則轉儲為冷歸檔或者深度冷歸檔存儲類型的時間。 說明
|
x-oss-expiration | 字符串 | 配置了生命周期規則的Bucket中Object的過期時間。
|
x-oss-restore | 字符串 | 如果Object存儲類型為Archive、ColdArchive或者DeepColdArchive，且您已提交Restore請求，則響應頭中會以x-oss-restore返回該Object的Restore狀態，分如下幾種情況：
|
x-oss-process-status | 字符串 | 當用戶通過輕量消息隊列SMQ創建OSS事件通知后，在進行請求OSS相關操作時如果有匹配的事件通知規則，則響應中會攜帶這個Header，值為經過Base64編碼JSON格式的事件通知結果。 |
x-oss-request-charged | 字符串 | 當Object所屬的Bucket被設置為請求者付費模式，且請求者不是Bucket的擁有者時，響應中將攜帶此Header，值為requester。 |
Content-Md5 | 字符串 |
|
Last-Modified | 字符串 | Object最后一次修改的日期，格式為HTTP 1.1協議中規定的GMT時間。 說明
|
Access-Control-Allow-Origin | 字符串 | 當Object所在的Bucket配置了CORS規則，且請求的Origin滿足指定的CORS規則時會在響應中包含這個Origin。 |
Access-Control-Allow-Methods | 字符串 | 當Object所在的Bucket配置了CORS規則，且請求的Access-Control-Request-Method滿足指定的CORS規則時會在響應中包含允許的Methods。 |
Access-Control-Max-Age | 字符串 | 當Object所在的Bucket配置了CORS規則，且請求滿足Bucket配置的CORS規則時會在響應中包含MaxAgeSeconds。 |
Access-Control-Allow-Headers | 字符串 | 當Object所在的Bucket配置了CORS規則，且請求滿足指定的CORS規則時會在響應中包含這些Headers。 |
Access-Control-Expose-Headers | 字符串 | 表示允許訪問客戶端JavaScript程序的headers列表。當Object所在的Bucket配置了CORS規則，且請求滿足指定的CORS規則時會在響應中包含ExposeHeader。 |
x-oss-tagging-count | 字符串 | 對象關聯的標簽個數。僅當用戶有讀取標簽權限時返回。 |
此接口還包含ETag、x-oss-request-id等公共響應頭。更多信息，請參見公共響應頭（Common Response Headers）。
示例
未啟用版本控制
請求示例
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****************返回示例
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請求對象指定版本（啟用版本控制）
請求示例
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****************返回示例
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請求對象最新版本（啟用版本控制）
請求示例
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****************返回示例
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提交Restore請求但Restore未完成
請求示例
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****************返回示例
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提交Restore請求且Restore已完成
請求示例
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****************返回示例
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使用服務端加密SSE-OSS
請求示例
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****************返回示例
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使用服務器端加密SSE-KMS
請求示例
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****************返回示例
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
錯誤碼
錯誤碼 | HTTP 狀態碼 | 描述 |
NoSuchKey | 404 | 請求的文件不存在。 |
SymlinkTargetNotExist | 404 | 請求的文件類型為軟鏈接。 |
InvalidTargetType | 400 | 請求的文件類型為軟鏈接，且對應的目標文件類型也為軟鏈接。 |
NotModified | 304 | 返回該錯誤的可能原因如下：
|
PreconditionFailed | 412 | 返回該錯誤的可能原因如下：
|