全部產品
Search

搜尋本產品

    Object Storage Service：HeadObject

    文件中心

    Object Storage Service：HeadObject

    更新時間：Mar 07, 2026

    HeadObject介面用於擷取某個檔案（Object）的中繼資料。使用此介面不會返迴文件內容。

    版本控制

    • 在請求參數中不指定versionId的情況下執行HeadObject操作，預設擷取目前的版本Object的中繼資料。如果目前的版本Object為刪除標記，則返回404 NoSuchKey。

    • 在請求參數中指定versionId的情況下執行HeadObject操作，返回指定版本Object的中繼資料。不支援在請求參數中指定刪除標記的versionId，否則返回405 MethodNotAllowed。

    Permissions

    By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

    API

    Action

    Description

    HeadObject

    oss:GetObject

    Queries the metadata of an object.

    請求文法

    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根據CRC64/XZ計算得出。

    對OSS支援CRC64校正前建立的Object，調用HeadObject介面時可能不會返回此回應標頭。

    x-oss-sealed-time

    字串

    對於已經處於Sealed狀態的Appendable類型的Object會返回此Header，表示該檔案執行seal操作的時間，格式為HTTP 1.1協議中規定的GMT時間，如Sat, 11 Oct 2025 06:41:42 GMT。

    x-oss-transition-time

    字串

    Object通過生命週期規則轉儲為冷歸檔或者深度冷Archive Storage類型的時間。

    說明

    • 如果擷取的轉儲時間距離目前時間超過180天，則提前刪除冷歸檔或者深度冷歸檔Object不會產生儲存不足規定時間長度費用。如果轉儲時間距離目前時間不超過180天，則提前刪除冷歸檔或者深度冷歸檔Object會產生儲存不足規定時間長度費用。

    • 不支援通過該欄位統計Object通過生命週期規則轉儲為低頻或者Archive Storage類型的時間。判斷低頻或者Archive Storage類型是否滿足最低儲存時間長度的要求取決於Last-Modified時間。

    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

    字串

    當使用者通過輕量訊息佇列SMQ建立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時間。

    說明

    • 低頻訪問類型最低儲存時間（30天）以Object儲存在OSS的Last Modified時間開始計算。如果擷取到Object的Last-Modified時間距離目前時間超過30天，則提前刪除Object不會產生低頻儲存不足規定時間長度費用。

    • 歸檔類型最低儲存時間（60天）以Object儲存在OSS的Last Modified時間開始計算。如果擷取到Object的Last-Modified時間距離目前時間超過60天，則提前刪除Object不會產生Archive Storage不足規定時間長度費用。

    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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      返回樣本（當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/jpeg
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

      返回樣本（當Object為已封存的Append檔案時）

      HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Appendable
x-oss-storage-class: Standard
x-oss-sealed-time: Sat, 11 Oct 2025 06:41:42 GMT
Date: Wed, 31 Mar 2021 07:32:52 GMT
Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 100
Content-Type: text/plain
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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      返回樣本

      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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      返回樣本

      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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      返回樣本

      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/jpeg
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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      返回樣本

      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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      返回樣本

      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/jpeg
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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      返回樣本

      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/jpeg
Connection: keep-alive
Server: AliyunOSS

    SDK

    此介面所對應的各語言SDK如下：

    命令列工具ossutil

    HeadObject介面所對應的ossutil命令，請參見head-object。

    錯誤碼

    錯誤碼

    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不相等。