全部產品
Search
文件中心

Object Storage Service:HeadObject

更新時間:Feb 28, 2024

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的類型。

  • 通過PutObject上傳或者通過CreateDirectory建立的Object類型為Normal。

  • 通過AppendObject上傳的Object類型為Appendable。

  • 通過MultipartUpload上傳的Object類型為Multipart。

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-expiration

字串

配置了生命週期規則的Bucket中Object的到期時間。

  • Bucket已開啟版本控制

    • 未攜帶versionId發起請求

      如果請求的Object命中生命週期的刪除規則,回應標頭中會返回x-oss-expiration頭,表示Object目前的版本的到期時間。

    • 攜帶versionId發起請求

      無論請求的Object是否命中生命週期的刪除規則,回應標頭中都不會返回x-oss-expiration頭。

  • Bucket未開啟版本控制

    • 如果請求的Object命中生命週期的刪除規則,則回應標頭中會返回x-oss-expiration頭。

    • 如果請求的Object未命中生命週期的刪除規則,則回應標頭中不會返回x-oss-expiration頭。

x-oss-restore

字串

如果Object儲存類型為Archive、ColdArchive或者DeepColdArchive,且您已提交Restore請求,則回應標頭中會以x-oss-restore返回該Object的Restore狀態,分如下幾種情況:

  • 如果沒有提交Restore或者Restore已經逾時,則不返回該欄位。

  • 如果已經提交Restore,且Restore沒有完成,則返回的x-oss-restore值為ongoing-request=”true”。

  • 如果已經提交Restore,且Restore已經完成,則返回的x-oss-restore值為ongoing-request=”false”, expiry-date=”Sun, 16 Apr 2017 08:12:33 GMT”,其中expiry-date是Restore完成後Object進入可讀狀態的到期時間。

x-oss-process-status

字串

當使用者通過MNSMessage Service建立OSS事件通知後,在進行請求OSS相關操作時如果有匹配的事件通知規則,則響應中會攜帶這個Header,值為經過Base64編碼JSON格式的事件通知結果。

x-oss-request-charged

字串

當Object所屬的Bucket被設定為要求者付費模式,且要求者不是Bucket的擁有者時,響應中將攜帶此Header,值為requester。

Content-Md5

字串

  • 對於Normal類型的Object,根據RFC 1864標準對訊息內容(不包括Header)計算Md5值獲得128位元位元字,對該數字進行Base64編碼作為一個訊息的Content-Md5值。

  • Multipart和Appendable類型的檔案不會返回這個Header。

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 qn6qrrqxo2oawuk53otfjbyc:JbzF2LxZUtanlJ5dLA092wpD****

    返回樣本(當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 ryghu9rp3mqp1ya:RvyjGvKxaUhdF0ibyEwX5mOM****

    返回樣本

    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 ryghu9rp3mqp1ya:RvyjGvKxaUhdF0ibyEwX5mOM****

    返回樣本

    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 e1Unnbm1rgdnpI:KKxkdNrUBu2t1kqlDh0MLbDb****

    返回樣本

    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 e1Unnbm1rgdnpI:21qtGJ+ykDVmdu6O6FMJnn+W****

    返回樣本

    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 qn6qrrqxo2oawuk53otfjbyc:JbzF2LxZUtanlJ5dLA092wpD****

    返回樣本

    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 qn6qrrqxo2oawuk53otfjbyc:JbzF2LxZUtanlJ5dLA092wpD****

    返回樣本

    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

返回該錯誤的可能原因如下:

  • 指定了If-Modified-Since要求標頭,但源Object在指定的時間後沒被修改過。

  • 指定了If-None-Match要求標頭,且源Object的ETag值和您提供的ETag相等。

PreconditionFailed

412

返回該錯誤的可能原因如下:

  • 指定了If-Unmodified-Since,但指定的時間早於Object實際修改時間。

  • 指定了If-Match,但源Object的ETag值和您提供的ETag不相等。