取得 Blob 屬性

Get Blob Properties 作業會傳回 Blob 之所有使用者定義的中繼資料、標準 HTTP 屬性及系統屬性, 它不會傳回 Blob 的內容。

要求

您可以建構 Get Blob Properties 要求,如下所示。 建議您使用 HTTPS。 以儲存體帳戶的名稱取代 myaccount

HEAD 方法要求 URI HTTP 版本
https://myaccount.blob.core.windows.net/mycontainer/myblob

https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>

https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
HTTP/1.1

模擬儲存體服務 URI

當您對模擬儲存體服務提出要求時,請將模擬器主機名稱和Azure Blob 儲存體埠指定為 127.0.0.1:10000 ,後面接著模擬的儲存體帳戶名稱:

HEAD 方法要求 URI HTTP 版本
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob HTTP/1.1

如需詳細資訊,請參閱使用 Azure 儲存體模擬器進行開發和測試

URI 參數

您可以在要求 URI 上指定下列其他參數:

參數 描述
snapshot 選擇性。 快照集參數是不透明的 DateTime 值,當它存在時,會指定要擷取的 Blob 快照集。 如需使用 Blob 快照集的詳細資訊,請參閱 建立 Blob 的快照集。
versionid 選擇性。 版本 2019-12-12 和更新版本。 參數 versionid 是不透明的 DateTime 值,當它存在時,會指定要擷取的 Blob 版本。
timeout 選擇性。 timeout 參數以秒為單位。 如需詳細資訊,請參閱 設定 Blob 儲存體作業的逾時

要求標頭

下表描述必要的和選用的要求標頭。

要求標頭 描述
Authorization 必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊,請參閱授權對 Azure 儲存體提出要求
Datex-ms-date 必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊,請參閱授權對 Azure 儲存體提出要求
x-ms-version 所有已授權要求都需要。 匿名要求的選擇性。 指定用於這個要求的作業版本。 如需詳細資訊,請參閱 Azure 儲存體服務的版本
x-ms-lease-id: <ID> 選擇性。 如果指定此標頭,只有在符合下列兩個條件時, Get Blob Properties 才會執行作業:

- Blob 的租用目前為作用中。
- 要求中指定的租用識別碼符合 Blob 的租用識別碼。

如果不符合上述任一條件,要求就會失敗,且 Get Blob Properties 作業失敗,狀態碼為 412 (前置條件失敗) 。
x-ms-upn 選擇性。 版本 2020-06-12 和更新版本。 適用于已啟用階層命名空間的帳戶。 如果 中 x-ms-owner 傳回的使用者識別值 為 true,則會從 Azure Active Directory 物件識別碼轉換為使用者主體名稱。 如果值為 false,則會以 Azure Active Directory 物件識別碼的形式傳回這些值。 預設值為 false。 請注意,群組和應用程式物件識別碼不會轉譯,因為它們沒有唯一的易記名稱。
x-ms-client-request-id 選擇性。 提供用戶端產生的不透明值,其中包含 1 kibibyte (KiB) 字元限制,這會在啟用儲存體分析記錄時記錄在分析記錄中。 強烈建議您在將用戶端活動與伺服器收到的要求相互關聯時,請使用此標頭。 如需詳細資訊,請參閱關於 Azure 儲存體分析記錄Azure 記錄:使用記錄來追蹤儲存體要求

唯有在符合指定條件的情況下,此作業也支援使用條件式標頭,傳回 Blob 屬性和中繼資料。 如需詳細資訊,請參閱 指定 Blob 儲存體作業的條件式標頭

要求標頭 (客戶提供的加密金鑰)

從 2019-02-02 版開始,您可以在要求上指定下列標頭,以讀取使用客戶提供的金鑰加密的 Blob。 使用客戶提供的金鑰進行加密 (,而對應的標頭集) 是選擇性的。 如果 Blob 先前已使用客戶提供的金鑰加密,您必須在要求中包含這些標頭,才能順利完成讀取作業。

要求標頭 描述
x-ms-encryption-key 必要。 Base64 編碼的 AES-256 加密金鑰。
x-ms-encryption-key-sha256 選擇性。 加密金鑰的 Base64 編碼 SHA256 雜湊。
x-ms-encryption-algorithm: AES256 必要。 指定要用於加密的演算法。 此標頭的值必須設定為 AES256

要求本文

無。

回應

回應包括 HTTP 狀態碼和一組回應標頭。

狀態碼

成功的作業會傳回狀態碼 200 (OK)。

如需狀態碼的詳細資訊,請參閱 狀態和錯誤碼

回應標頭

此作業的回應包含下表中的標頭。 回應也可能包括其他標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協定規格

回應標頭 描述
Last-Modified 上次修改 Blob 的日期/時間。 日期格式會依照 RFC 1123。 如需詳細資訊,請參閱 在標頭中代表日期/時間值

修改 Blob 的任何作業 (包括 Blob 更新的中繼資料或屬性),都會變更 Blob 上次修改的時間。
x-ms-creation-time 版本 2017-11-09 和更新版本。 建立 Blob 的日期/時間。 日期格式會依照 RFC 1123。 如需詳細資訊,請參閱 在標頭中代表日期/時間值
x-ms-meta-name:value 對應至與此 Blob 相關聯的使用者定義中繼資料的一組名稱/值組。
x-ms-tag-count 版本 2019-12-12 和更新版本。 如果 Blob 有任何標記,則傳回儲存在 Blob 上的標記數目。 如果沒有 Blob 上的標記,則不會傳回此標頭。
x-ms-blob-type:<BlockBlob\|PageBlob\|AppendBlob> Blob 類型。
x-ms-copy-completion-time:<datetime> 版本 2012-02-12 和更新版本。 上次嘗試之 Copy Blob 作業 (此 Blob 為目的地 Blob) 的完成時間。 此值可指定完成、中止或複製嘗試失敗的時間。 如果複本擱置中、此 Blob 從未成為作業中的 Copy Blob 目的地,或在使用 Set Blob PropertiesPut BlobPut Block List 的結束 Copy Blob 作業之後修改此 Blob,則不會顯示這個標頭。
x-ms-copy-status-description: <error string> 版本 2012-02-12 和更新版本。 只有在 為 failedpendingx-ms-copy-status 才會出現。 描述嚴重或非嚴重複製作業失敗的原因。 如果此 Blob 從未成為作業中的 Copy Blob 目的地,或是此 Blob 在使用 、 Put BlobPut Block List 的結束 Copy Blob 作業 Set Blob Properties 之後修改,則不會顯示這個標頭。
x-ms-copy-id: <id> 版本 2012-02-12 和更新版本。 上次嘗試 Copy Blob 作業的字串識別碼,其中此 Blob 是目的地 Blob。 如果此 Blob 從未成為作業中的 Copy Blob 目的地,或是此 Blob 在使用 、 Put BlobPut Block List 的結束 Copy Blob 作業 Set Blob Properties 之後修改,則不會顯示這個標頭。
x-ms-copy-progress: <bytes copied/bytes total> 版本 2012-02-12 和更新版本。 包含上次嘗試 Copy Blob 作業中來源中複製的位元組數目和總位元組數,其中此 Blob 是目的地 Blob。 可以從 0 到 Content-Length 複製的位元組顯示。 如果此 Blob 從未成為作業中的 Copy Blob 目的地,或是此 Blob 在使用 、 Put BlobPut Block List 的結束 Copy Blob 作業 Set Blob Properties 之後修改,則不會顯示這個標頭。
x-ms-copy-source: url 版本 2012-02-12 和更新版本。 長度上限為 2 KiB 的 URL,指定上次嘗試 Copy Blob 作業中使用的來源 Blob,其中此 Blob 是目的地 Blob。 如果此 Blob 從未成為作業中的 Copy Blob 目的地,或是此 Blob 在使用 、 Put BlobPut Block List 的結束 Copy Blob 作業 Set Blob Properties 之後修改,則不會顯示這個標頭。
x-ms-copy-status: <pending \| success \| aborted \| failed> 版本 2012-02-12 和更新版本。 x-ms-copy-id 所識別的複製作業狀態,這些值如下:

- success:複製成功完成。
- pending:複製正在進行中。 檢查 x-ms-copy-status-description 是否有間歇性、不嚴重的錯誤妨礙複製進度,但未造成失敗。
- aborted:複製已由 結束 Abort Copy Blob
- failed:複製失敗。 請參閱 x-ms-copy-status-description,以取得失敗的詳細資料。

如果此 Blob 從未成為作業中的 Copy Blob 目的地,或是此 Blob 在使用 、 Put BlobPut Block List 完成 Copy Blob 的作業 Set Blob Properties 之後修改,則不會顯示這個標頭。
x-ms-incremental-copy: true 版本 2016-05-31 和更新版本。 如果 Blob 是累加複製 Blob,則包含在內。
x-ms-copy-destination-snapshot:<datetime> 版本 2016-05-31 和更新版本。 如果 Blob 是累加複製 Blob 或累加複製快照集,如果 x-ms-copy-status 成功,則包含此快照集。 此 Blob 上次成功增量複製快照集的快照集時間。
x-ms-lease-duration: <infinite \| fixed> 租用 Blob 時,指定租用期為無限或固定時間。 包含于使用 2012-02-12 版和更新版本的要求。
x-ms-lease-state: <available \| leased \| expired \| breaking \| broken> Blob 的租用狀態。 包含于使用 2012-02-12 版和更新版本的要求。
x-ms-lease-status:<locked\| unlocked> Blob 的租用狀態。
Content-Length Blob 大小 (以位元組為單位)。 對於分頁 Blob,此標頭會傳回與 Blob 一起儲存的 x-ms-blob-content-length 標頭值。
Content-Type 為 Blob 指定的內容類型。 如果未指定內容類型,則預設內容類型為 application/octet-stream
Etag ETag 包含的值可讓您依條件執行作業。 如需詳細資訊,請參閱 指定 Blob 儲存體作業的條件式標頭。 如果要求版本是 2011-08-18 或更新版本,ETag 值會以引號括住。
Content-MD5 如果為 Blob 設定了 Content-MD5 標頭,則會傳回此回應標頭,以便用戶端檢查訊息內容完整性。

在 2012-02-12 版和更新版本中, Put Blob 即使 Put Blob 要求不包含 MD5 標頭,也會設定區塊 Blob 的 MD5 值。
Content-Encoding 如果之前為 Blob 設定了 Content-Encoding 要求標頭,則會傳回此標頭的值。
Content-Language 如果之前為 Blob 設定了 Content-Language 要求標頭,則會傳回此標頭的值。
Content-Disposition 如果之前為 Blob 設定了 Content-Disposition 要求標頭,對 2013-08-15 及更新版本提出的要求,則會傳回此標頭的值。

Content-Disposition 回應標頭欄位會傳遞如何處理回應裝載的其他資訊,也可用來附加其他中繼資料。 例如,如果標頭設定 attachment 為 ,則表示使用者代理程式不應該顯示回應,而是顯示 [另存新檔] 對話方塊。
Cache-Control 如果之前為 Blob 設定了 Cache-Control 要求標頭,則會傳回此標頭的值。
x-ms-blob-sequence-number 分頁 Blob 目前的序號。

此標頭不會針對區塊 Blob 或附加 Blob 傳回。

此標頭不會針對區塊 Blob 傳回。
x-ms-request-id 此標頭可唯一識別所做的要求,而且您可以使用它來針對要求進行疑難排解。 如需詳細資訊,請參閱 針對 API 作業進行疑難排解
x-ms-version 指出用來執行要求的 Blob 儲存體版本。 針對針對 2009-09-19 版和更新版本提出的要求,會傳回此標頭。

如果容器已使用 Blob 儲存體 2009-09-19 版標示為公開存取,則匿名要求也會傳回此標頭。
Date 服務所產生的 UTC 日期/時間值,指出起始回應的時間。
Accept-Ranges: bytes 表示服務支援部分 Blob 內容的要求。 包含于使用 2013-08-15 版和更新版本提出的要求。
x-ms-blob-committed-block-count Blob 中存在已認可的區塊數目。 此標頭只會針對附加 Blob 傳回。
x-ms-server-encrypted: true/false 版本 2015-12-11 和更新版本。 如果 Blob 資料和應用程式中繼資料使用指定的演算法完全加密,這個標頭的值會設定 true 為 。 否則,當 Blob 未加密時,此值會設定為 false (,或者只有 blob/應用程式中繼資料的部分會加密) 。
x-ms-encryption-key-sha256 版本 2019-02-02 和更新版本。 如果 Blob 是以客戶提供的金鑰加密,則會傳回此標頭。
x-ms-encryption-scope 版本 2019-02-02 和更新版本。 如果 Blob 是以加密範圍加密,則會傳回此標頭。
x-ms-access-tier 版本 2017-04-17 和更新版本。 Blob 儲存體或一般用途 v2 帳戶中區塊 Blob 的進階儲存體帳戶或區塊 Blob 層上的分頁 Blob 層。 如需允許的進階分頁 Blob 層清單,請參閱VM 的高效能進階儲存體和受控磁片。 對於 Blob 儲存體或一般用途 v2 帳戶,有效值為 HotArchive//Cool/Cold 。 請注意, Cold 層目前處於預覽狀態,且支援版本 2021-12-02 和更新版本。 如需標準 Blob 帳戶區塊 Blob 層級階層式詳細資訊 ,請參閱經常性存取、非經常性存取和封存儲存層
x-ms-access-tier-inferred: true 版本 2017-04-17 和更新版本。 僅適用于進階儲存體帳戶上的分頁 Blob。 如果存取層未在 Blob 上明確設定,則會根據其內容長度推斷該層,並以 值 true 傳回此標頭。 對於 Blob 儲存體上的區塊 Blob 或一般用途 v2 帳戶,如果 Blob 沒有設定存取層,您可以從儲存體帳戶屬性推斷該層。 只有在推斷區塊 Blob 層時,才會設定此標頭。
x-ms-archive-status 版本 2017-04-17 和更新版本。 對於 Blob 儲存體或一般用途 v2 帳戶,有效值為 rehydrate-pending-to-hot/rehydrate-pending-to-cool 。 如果 Blob 已解除凍結且不完整,則會傳回此標頭,這兩者都表示解除凍結為擱置中,並顯示目的地層。 如需標準 Blob 帳戶區塊 Blob 層級階層處理的詳細資訊,請參閱 經常性存取、非經常性存取和封存儲存層
x-ms-access-tier-change-time 版本 2017-04-17 和更新版本。 指出上次在 物件上變更階層的時間。 只有在已設定區塊 Blob 上的層時,才會傳回此標頭。 日期格式會依照 RFC 1123。 如需詳細資訊,請參閱 代表標頭中的日期/時間值。 如需標準 Blob 帳戶區塊 Blob 層級階層處理的詳細資訊,請參閱 經常性存取、非經常性存取和封存儲存層
x-ms-client-request-id 可用來針對要求及其對應的回應進行疑難排解。 如果標頭存在於要求中,這個標頭的值等於標頭的值 x-ms-client-request-id ,而且此值最多為 1,024 個可見的 ASCII 字元。 x-ms-client-request-id如果要求中沒有標頭,則回應中沒有此標頭。
x-ms-rehydrate-priority 版本 2019-12-12 和更新版本。 如果物件處於解除凍結擱置狀態,則會以解除凍結的優先順序傳回此標頭。 有效值為 High/Standard 。 如需標準 Blob 帳戶區塊 Blob 層級階層處理的詳細資訊 ,請參閱經常性存取、非經常性存取和封存儲存層
x-ms-or-{policy-id}_{rule-id} 版本 2019-12-12 和更新版本,僅針對區塊 Blob 傳回。 policy-id 是 GUID 值,表示儲存體帳戶上物件複寫原則的識別碼。 rule-id 是 GUID 值,表示 Blob 容器上原則規則的識別碼。 如果帳戶已啟用 ObjectReplication ,則此標頭的值代表具有指定原則和規則識別碼的 Blob 複寫狀態,可以是 completefailed
x-ms-or-policy-id 版本 2019-12-12 和更新版本,僅針對區塊 Blob 傳回。 如果帳戶已啟用 ObjectReplication ,則此標頭的值代表控管複寫的原則。
x-ms-last-access-time 版本 2020-02-10 和更新版本。 指出根據儲存體帳戶上次存取時間追蹤原則來存取 Blob 資料的時間。 如果儲存體帳戶沒有上次存取時間追蹤原則,或原則已停用,則不會傳回標頭。 如需設定儲存體帳戶上次存取時間追蹤原則的相關資訊,請參閱 Blob 儲存體 API
x-ms-blob-sealed 版本 2019-12-12 和更新版本,僅針對附加 Blob 傳回。 如果附加 Blob 已密封,此值會 是 true。 如需詳細資訊,請參閱 附加 Blob 密封
x-ms-immutability-policy-until-date 版本 2020-06-12 和更新版本。 指定 Blob 上設定的「保留期限」日期。 這是 Blob 可以受到保護而無法修改或刪除的日期。 只有在 Blob 上設定不變性原則時,才會傳回 。 此標頭的值是 RFC1123 格式。
x-ms-immutability-policy-mode: unlocked/locked 版本 2020-06-12 和更新版本。 如果 Blob 上設定不變性原則,則會傳回不變性原則模式。 unlocked/locked 值為 。 unlocked 表示使用者可能會藉由增加或減少保留期限來變更原則。 locked 表示禁止這些動作。
x-ms-legal-hold: true/false 版本 2020-06-12 和更新版本。 如果沒有 Blob 合法保留,則不會傳回此標頭。 如果 Blob 包含法務保存,且其值為 true ,則此標頭的值會設定為 true。 否則,如果 Blob 包含法務保存和其值 false,則此值會設定為 false。
x-ms-owner 版本 2020-06-12 和更新版本。 僅適用于已啟用階層命名空間的帳戶。 傳回檔案或目錄的擁有者使用者。
x-ms-group 版本 2020-06-12 和更新版本。 僅適用于已啟用階層命名空間的帳戶。 傳回檔案或目錄的擁有者群組。
x-ms-permissions 版本 2020-06-12 和更新版本。 僅適用于已啟用階層命名空間的帳戶。 傳回針對檔案或目錄上的使用者群組和其他設定的許可權。 每個個別許可權都是 [r,w,x,-] {3} 格式。
x-ms-resource-type 版本 2020-10-02 和更新版本。 僅適用于已啟用階層命名空間的帳戶。 傳回路徑的資源類型,可以是 filedirectory
x-ms-expiry-time 版本 2020-02-10 和更新版本。 僅適用于已啟用階層命名空間的帳戶。 傳回在 Blob 上設定的到期時間。 只會針對已設定到期時間的檔案傳回 。

回應本文

無。

範例回應

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
x-ms-meta-Name: myblob.txt  
x-ms-meta-DateUploaded: <date>  
x-ms-blob-type: AppendBlob  
x-ms-lease-status: unlocked  
x-ms-lease-state: available  
Content-Length: 11  
Content-Type: text/plain; charset=UTF-8  
Date: <date>  
ETag: "0x8CAE97120C1FF22"  
Accept-Ranges: bytes  
x-ms-blob-committed–block-count: 1  
x-ms-version: 2015-02-21  
Last-Modified: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-copy-id: 36650d67-05c9-4a24-9a7d-a2213e53caf6  
x-ms-copy-source: <url>  
x-ms-copy-status: success  
x-ms-copy-progress: 11/11  
x-ms-copy-completion-time: <date>  
  

授權

如果將容器的存取控制清單 (ACL) 設為允許匿名存取 Blob,任何用戶端都可以呼叫這項作業。 如果容器是私人的,則此作業可由帳戶擁有者以及具有讀取 Blob 許可權的共用存取簽章的任何人執行。

備註

若要判斷作業是否已 Copy Blob 完成,請先檢查 x-ms-copy-id 以確定標頭值符合原始呼叫 Copy Blob 所提供的複製識別碼。 比對可確保另一個應用程式不會中止複製並啟動新的 Copy Blob 作業。 接下來,檢查 x-ms-copy-status: success 標頭。 但請注意,除了 、 Put PagePut Block 作業以外 Lease ,Blob 上的所有寫入作業都會從 Blob 中移除所有 x-ms-copy-* 屬性。 使用這些版本早于 2012-02-12 的作業也不會複製 Copy Blob 這些屬性。

x-ms-copy-status-description 包含 Copy Blob 失敗的詳細資訊。 下表說明這些 x-ms-copy-status-description 值:

元件 描述
HTTP 狀態碼 指定失敗的標準 3 位數整數。
錯誤碼 關鍵字,描述 ErrorCode > 元素中 < Azure 所提供的錯誤。 <如果沒有出現 ErrorCode > 元素,則會使用與 HTTP 規格中 3 位數 HTTP 狀態碼相關聯的標準錯誤文字關鍵字。 如需詳細資訊,請參閱常見 REST API 錯誤碼
資訊 失敗的詳細描述,以引號括住。

x-ms-copy-status下表說明常見失敗案例的 和 x-ms-copy-status-description 值:

重要

下列錯誤描述可以變更而不發出警告,即使沒有版本變更,文字可能不完全相符。

狀況 x-ms-copy-status 值 x-ms-copy-status-description 值
複製作業已順利完成。 成功 empty
使用者在完成前已中止複製作業。 aborted empty
複製期間從來源 Blob 讀取時失敗,但將重試作業。 暫止 502 BadGateway「讀取來源時,發生可重試的錯誤。 將重試。 失敗時間: < 時間 > 」
寫入複製作業的目的地 Blob 發生失敗,但將重試作業。 暫止 500 InternalServerError「發生可重試的錯誤。 將重試。 失敗時間: < 時間 > 」
從複製作業的來源 Blob 在讀取時,發生無法復原的失敗。 失敗 404 ResourceNotFound「讀取來源時複製失敗」。注意:當服務報告此基礎錯誤時,它會在 ErrorCode > 元素中 < 傳 ResourceNotFound 回。 如果回應中沒有 < 出現 ErrorCode > 元素,則會顯示 HTTP 狀態的標準字串標記法,例如 NotFound
限制所有複製作業的逾時期限已過。 (目前,逾時期間為兩周。) 失敗 500 OperationCancelled「複製超過允許的最長時間。」
從來源讀取時,複製作業太常失敗,而且不符合成功嘗試的最小比率。 (此逾時可防止在失敗) 前兩周重試非常差的來源。 失敗 500 OperationCancelled「讀取來源時,複製失敗。」

x-ms-last-access-time 根據儲存體帳戶的上次存取時間追蹤原則,追蹤 Blob 資料存取的時間。 存取 Blob 的中繼資料不會變更其上次存取時間。

另請參閱

授權對 Azure 儲存體的要求
狀態和錯誤碼
Blob 儲存體錯誤碼