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
要求標頭
名稱 | 類型 | 是否必選 | 描述 |
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。 |
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 Storage類型(Archive)、冷Archive Storage類型(ColdArchive)以及深度冷Archive Storage類型(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通過生命週期規則轉儲為冷歸檔或者深度冷Archive Storage類型的時間。 說明
|
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****************
返回樣本(當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
返回樣本(當Object為目錄時)
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
請求對象指定版本(啟用版本控制)
請求樣本
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 | 返回該錯誤的可能原因如下:
|