該 Get Blob Layout 作返回 blob 的所有使用者定義的元數據、標準 HTTP 屬性和系統屬性。 此外,也可以選擇性地回傳該 blob 的佈局。 blob 的佈局是 blob 的子資源,包含 blob 中所有範圍的分解,並有一個端點(地址)可讀取該範圍,提供如何最佳平行化讀取的提示。
利用此 API,您可以透過以下兩個步驟來優化下載操作:
-
佈局發現:呼叫
Get Blob Layout取得 blob 的屬性並發現其資料分布。 -
平行取得 Blob:平行呼叫
Get Blob你感興趣的所有 blob 範圍,利用 blob 佈局回傳的端點將這些請求導向最佳位置。
Request
您可以建構 Get Blob Layout 要求,如下所示。 建議您使用 HTTPS。 將 我的帳號 替換成你的儲存帳號名稱:
| GET 方法請求 URI | HTTP 版本 |
|---|---|
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=layouthttps://myaccount.blob.core.windows.net/mycontainer/myblob?comp=layout&snapshot=<DateTime> https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=layout&versionid=<DateTime>https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=layout&versionid=<DateTime>&marker=<ContinuationToken>&maxresults=1000 |
HTTP/1.0 HTTP/1.1 |
URI 參數
您可以在要求 URI 上指定下列其他參數:
| Parameter | Description |
|---|---|
snapshot |
Optional. 快照參數是一個不透明 DateTime 的值,如果存在,則指定要檢索的 blob 快照。 欲了解更多關於使用 blob 快照的資訊,請參見 「建立 blob 快照」。 |
versionid |
Optional. 該 versionid 參數是一個不透明 DateTime 的值,如果存在,則指定要檢索的 blob 的版本。 |
marker |
Optional. 一個由先前 Get Blob Layout 請求回傳的延續標記。 利用這個標記來取得下一組範圍。 當回應未包含所有區域或指定範圍時,標記用於恢復分頁。 若使用標記, If-Match 則必須包含標頭與前一請求的 Etag 一同。 欲了解更多如何使用If-Match標頭的資訊,請參閱「指定 Blob 儲存體 操作的條件標頭」。 此外,若先前請求包含 Range or x-ms-range 標頭,該請求也必須包含相同的標頭。 如果上一次請求沒有包含範圍標頭,這個請求也必須不包含範圍標頭。 |
maxresults |
Optional. 回應中回傳的最大範圍數。 API 永遠不會回傳超過 由 maxresults所指定的值的範圍。 |
timeout |
Optional.
timeout 參數是以秒為單位來表示。 有關詳細資訊,請參閱 為 Blob 儲存作設置超時。 |
請求標頭
下表描述必要和選擇性的要求標頭。
| 請求標頭 | Description |
|---|---|
Authorization |
Required. 指定授權配置、帳戶名稱和簽章。 如需詳細資訊,請參閱 授權對 Azure 記憶體的要求。 |
Date 或 x-ms-date |
Required. 指定要求的國際標準時間(UTC)。 如需詳細資訊,請參閱 授權對 Azure 記憶體的要求。 |
x-ms-version |
Required. 指定要用於此要求的作業版本。 Get Blob Layout 僅支援 2026-02-06 版本或更新版本。 如需詳細資訊,請參閱 Azure 儲存體服務的版本。 |
Range 或 x-ms-range |
Optional. 只回傳指定範圍的元資料。 若 Range 同時指定 和 x-ms-range ,服務使用 的 x-ms-range值。 若兩個範圍皆未指定,則會回傳整個 blob 的元資料。 欲了解更多資訊,請參閱 「指定 Blob 儲存體 操作的範圍標頭」。 |
x-ms-lease-id: <ID> |
Optional. 若指定此標頭,則僅在以下兩個條件皆符合時執行: - blob 的租約目前有效。 - 請求中指定的租約 ID 與 blob 的租約 ID 相符。 如果不滿足這些條件中的任何一個,則請求將失敗,並且 Get Blob Layout 作將失敗,狀態代碼為 412(先決條件失敗)。 |
x-ms-upn |
Optional. 適用於啟用階層命名空間的帳號。 若為真,回傳於 x-ms-owner、 x-ms-group、 x-ms-acl 及回應標頭中的使用者身份值將從 Microsoft Entra 物件 ID 轉換為使用者主體名稱。 如果值為 假,則會以 Microsoft Entra 物件 ID 回傳。 預設值為 false。 請注意,群組與應用程式物件 ID 不會被轉譯,因為它們沒有唯一的友善名稱。 |
x-ms-client-request-id |
Optional. 提供客戶產生的不透明值,字元限制為 1 KB(KiB),當啟用儲存分析日誌時,會記錄在分析日誌中。 我們強烈建議您在將客戶端活動與伺服器接收的請求做關聯時,使用此標頭。 欲了解更多資訊,請參閱 關於 Azure 儲存體分析 日誌。 |
此操作也支援使用條件標頭,僅在符合指定條件時回傳 blob 佈局與屬性。 欲了解更多資訊,請參閱 「指定 Blob 儲存體 操作的條件標頭」。 請注意, If-Match 當 URI 參數中使用 a marker 時,標頭是必須的。
請求標頭(客戶提供的加密金鑰)
你可以在讀取一個用客戶提供金鑰加密的 blob 時指定以下標頭。 使用客戶提供的金鑰(及相應標頭組)加密是可選的。 如果 blob 先前已用客戶提供的金鑰加密,您必須在請求中包含這些標頭,以確保操作能成功完成。
| 請求標頭 | Description |
|---|---|
x-ms-encryption-key |
Required. Base64編碼的AES-256加密金鑰。 |
x-ms-encryption-key-sha256 |
Optional. 加密金鑰的 Base64 編碼 SHA256 雜湊值。 |
x-ms-encryption-algorithm: AES256 |
Required. 指定用於加密的演算法。 此標頭的值必須設定為 AES256。 |
要求本文
None.
回應
回應包含 HTTP 狀態碼、一組回應標頭,以及可選的回應主體,包含以 XML 格式呈現的 blob 佈局。
狀態代碼
成功操作會回傳兩個狀態碼之一:
- 如果回應在正文中包含 blob 佈局,則使用 HTTP 200(OK)。
- HTTP 204(無內容)是指伺服器在回應主體中未回傳版面。 在此情況下,API 在功能上等價於
Get Blob Properties。
如您需狀態代碼的詳細資訊,請參閱 狀態和錯誤碼。
回應標頭
此作業的回應包含下列標頭。 回應也可能包含額外的標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協定規格,。
| 回應標頭 | Description |
|---|---|
Content-Type |
指定回應主體中回傳結果的格式。 價值是屍 application/xml 體是否被歸還。 |
Content-Length |
表示回應體的大小,若被回傳的話。 |
Last-Modified |
黏液最後一次修改的日期/時間。 日期格式遵循 RFC 1123。 如需詳細資訊,請參閱 代表標頭中的日期/時間值。 修改 blob 的任何作(包括更新 blob 的元資料或屬性)都會更改 blob 的上次修改時間。 |
x-ms-creation-time |
那個黏液被創造的日期/時間。 日期格式遵循 RFC 1123。 如需詳細資訊,請參閱 代表標頭中的日期/時間值。 |
x-ms-meta-name:value |
一組名稱-值對,對應於與此 blob 關聯的使用者定義元數據。 |
x-ms-tag-count |
如果 blob 有任何標記,則返回存儲在 blob 上的標記數。 如果 blob 上沒有標記,則不會返回此標頭。 |
ETag |
包含一個可以用來條件執行運算的值。 欲了解更多資訊,請參閱 「指定 Blob 儲存體 操作的條件標頭」。 ETag 值會以引號括住。 |
x-ms-copy-completion-time:<datetime> |
上次嘗試 Copy Blob 的作的結束時間,其中此 blob 是目標 blob。 這個值可以指定完成、中止或失敗複製嘗試的時間。 如果副本處於掛起狀態、此 blob 從未是作中的Copy Blob目標,或者如果此 blob 在使用 Copy Blob、 Set Blob Properties或 Put Blob的已結束Put Block List作後已修改,則不會顯示此標頭。 |
x-ms-copy-status-description: <error string> |
僅在 x-ms-copy-status 為 或 failed時pending出現。 描述嚴重或非嚴重複製作業失敗的原因。 如果此 blob 從未是作中的Copy Blob目標,或者此 blob 在使用 Copy Blob、 Set Blob Properties或的Put Blob結束Put Block List作後已修改,則不會顯示此標頭。 |
x-ms-copy-id: <id> |
上次嘗試 Copy Blob 的作的字元串標識符,其中此 blob 是目標 blob。 如果此 blob 從未是作中的Copy Blob目標,或者此 blob 在使用 Copy Blob、 Set Blob Properties或的Put Blob結束Put Block List作後已修改,則不會顯示此標頭。 |
x-ms-copy-progress: <bytes copied/bytes total> |
包含上次嘗試 Copy Blob 的作中複製的位元組數和源中的總位元組數,其中此 blob 是目標 blob。 可以顯示從 0 到 Content-Length 複製的位元組。 如果此 blob 從未是作中的Copy Blob目標,或者此 blob 在使用 Copy Blob、 Set Blob Properties或的Put Blob結束Put Block List作後已修改,則不會顯示此標頭。 |
x-ms-copy-source: url |
長度不超過 2 KiB 的 URL,用於指定上次嘗試 Copy Blob 作中使用的源 Blob,其中此 Blob 是目標 Blob。 如果此 blob 從未是作中的Copy Blob目標,或者此 blob 在使用 Copy Blob、 Set Blob Properties或的Put Blob結束Put Block List作後已修改,則不會顯示此標頭。 這個標頭中回傳的 URL 包含了在複製操作中對來源 blob 使用的所有請求參數。 若 URL 包含共享存取簽章(SAS)標記,則不會包含該簽章( sig 參數)。 |
x-ms-copy-status: <pending \| success \| aborted \| failed> |
由 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 在使用 Copy Blob、 Set Blob Properties或Put Blob的完成Put Block List作後已修改,則不會顯示此標頭。 |
x-ms-incremental-copy: true |
如果 blob 是增量副本 blob,則包括在內。 |
x-ms-copy-destination-snapshot:<datetime> |
如果 blob 是增量複製 blob 或增量副本快照,則包括在內,如果 x-ms-copy-status 是 success。 此 Blob 上次成功增量複製快照集的快照集時間。 |
x-ms-lease-duration: <infinite \| fixed> |
當 Blob 租用時,指定租用是無限期還是固定持續時間。 |
x-ms-lease-state: <available \| leased \| expired \| breaking \| broken> |
黏液的租約狀態。 |
x-ms-lease-status:<locked\| unlocked> |
blob 的租約狀態。 |
Cache-Control |
如果之前已為 blob 設置了請求標頭,則 Cache-Control 在此標頭中返回該值。 |
x-ms-request-id |
此標頭唯一標識發出的請求,您可以使用它對請求進行故障排除。 如需詳細資訊,請參閱 針對 API 作業進行疑難解答。 |
x-ms-version |
指示用於執行請求的 Blob 儲存版本。 |
Accept-Ranges: bytes |
表示服務支援部分 Blob 內容的要求。 |
x-ms-server-encrypted: true/false |
如果 blob 資料和應用程式元數據使用指定的演算法完全加密,則此標頭的值將設置為 true 。 否則,該值設定為 false (當 blob 未加密時,或者如果僅加密了部分 blob/應用程式元資料) 。 |
x-ms-encryption-key-sha256 |
若 blob 以客戶提供的金鑰加密,則會回傳此標頭。 |
x-ms-encryption-context |
如果設定了加密上下文屬性值,則會回傳該設定值。 僅在帳號啟用階層命名空間時有效。 |
x-ms-encryption-scope |
若 blob 有加密範圍,則會回傳此標頭。 |
x-ms-access-tier |
Blob 儲存體 或通用 v2 帳號中的區塊 blob 層級。 有效值為 Hot、 Cool、 Cold和 SmartArchive。 關於標準 blob 帳戶區塊層級分層的詳細資訊,請參見 Blob 儲存層級。 |
x-ms-smart-access-tier |
此標頭僅用於針對該 Smart 層塊的請求。 有效值為 Hot、Cool和 Cold。 關於標準 blob 帳號區塊、blob 層級分級的詳細資訊,請參見 Blob 儲存層級。 |
x-ms-archive-status |
對於 blob 儲存或一般用途的 v2 帳號,有效值為 rehydrate-pending-to-hot、 rehydrate-pending-to-cool、 rehydrate-pending-to-cold和 。 如果正在解除凍結 blob 且不完整,則返回此標頭,該標頭既指示解除凍結處於掛起狀態,又顯示目標層。 關於標準 blob 帳戶區塊層級分層的詳細資訊,請參見 Blob 儲存層級。 |
x-ms-access-tier-change-time |
指示上次更改物件上的層的時間。 僅當設置了塊 blob 上的層時,才會返回此標頭。 日期格式遵循 RFC 1123。 如需詳細資訊,請參閱 代表標頭中的日期/時間值。 如需更多關於標準 blob 帳戶區塊 blob 層級分層的資訊,請參見 Blob 儲存層級。 |
x-ms-rehydrate-priority |
如果對象處於解除凍結擱置狀態,則會以解除凍結的優先順序傳回此標頭。 合法值為 High/Standard。 關於標準 blob 帳號區塊、blob 層級分級的詳細資訊,請參見 Blob 儲存層級。 |
x-ms-or-{policy-id}_{rule-id} |
只在方塊塊時退回。
policy-id 是一個 GUID 值,表示儲存帳戶上物件複製策略的標識碼。
rule-id 是一個 GUID 值,表示 blob 容器上策略規則的標識碼。 如果帳戶已 ObjectReplication啟用,則此標頭的值表示具有給定策略和規則標識碼( complete 或 failed)的 blob 的複製狀態。 |
x-ms-or-policy-id |
只在方塊塊時退回。 如果帳戶是 ObjectReplication-enabled,則此標頭的值表示管理複製的策略。 |
x-ms-last-access-time |
根據儲存帳號的最後存取時間追蹤政策,顯示該 blob 資料最後一次被存取的時間。 如果存儲帳戶沒有上次訪問時間跟蹤策略,或者該策略已禁用,則不會返回標頭。 有關設置存儲帳戶的上次訪問時間跟蹤策略的資訊,請參閱 Blob 儲存 API。 |
x-ms-blob-sealed |
只在附加斑點時回傳。 如果追加 blob 已密封,則該值將為 true。 更多資訊請參見 附加斑點印章 |
x-ms-immutability-policy-until-date |
指定在 blob 上設置的「保留期至」日期。 這是該 blob 可被保護不被修改或刪除的日期。 只有當 blob 上設定了不可變性政策時才回傳。 此標頭的值RFC1123格式。 |
x-ms-immutability-policy-mode: unlocked/locked |
如果在 blob 上設置了不可變性策略,則返回不可變性策略模式。 值為 unlocked/locked。
unlocked 表示用戶可以通過增加或減少保留期限來更改策略。
locked 表示禁止這些行為。 |
x-ms-legal-hold: true/false |
如果 blob 沒有合法保留,則不會返回此標頭。 如果 blob 包含合法保留,並且其值為 true,則此標頭的值設置為 true。 否則,如果 blob 包含合法保留,並且其值為 false,則該值將設置為 false。 |
x-ms-owner |
僅限於啟用階層命名空間的帳號。 返回檔案或目錄的所有者使用者。 |
x-ms-group |
僅限於啟用階層命名空間的帳號。 返回檔案或目錄的所有者組。 |
x-ms-permissions |
僅限於啟用階層命名空間的帳號。 返回在檔或目錄上為 使用者、 組和其他 人 設置的許可權。 每個個別的授權都是格式化 [r,w,x,-]{3} 的。 |
x-ms-acl |
僅限於啟用階層命名空間的帳號。 回傳檔案或目錄中為 使用者、 群組 及 其他 使用者設定的存取與預設存取控制清單的合併清單。 每個存取控制項目(ACE)包含一個範圍、一個類型、一個使用者或群組識別碼,以及格式 [scope]:[type]:[id]:[permissions]為 的權限。
default範圍表示 ACE 屬於目錄的預設 ACL;否則 scope 是隱含的,ACE 則屬於存取 ACL。 每個個別的授權都是格式化 [r,w,x,-]{3} 的。 |
x-ms-resource-type |
僅適用於啟用了分層命名空間的帳戶。 回傳路徑的資源類型,可以是 file 或 directory。 |
x-ms-expiry-time |
僅適用於啟用了分層命名空間的帳戶。 返回在 blob 上設置的過期時間。 僅針對設置了過期時間的檔返回。 |
回應機構
當回應狀態碼為 HTTP 200(OK)時,回應主體包含 XML 格式的 blob 佈局。 回應格式如下:
<?xml version="1.0" encoding="utf-8"?>
<BlobLayout>
<Ranges>
<Range Start="0" End="1023" EndpointIndex="0" />
<Range Start="1024" End="4096" EndpointIndex="1" />
</Ranges>
<Endpoints>
<Endpoint Index="0" Value="host1:port" />
<Endpoint Index="1" Value="host2:port" />
</Endpoints>
<NextMarker>marker</NextMarker>
<MaxResults>2</MaxResults>
</BlobLayout>
XML 回應包含以下元素:
範圍:包含一系列範圍元素,每個元素指定 blob 中連續的位元組範圍及其對應的端點索引。
-
範圍:代表 blob 中連續的位元組範圍。
- Start:範圍(含)的起始位元組偏移量。
- 結束:範圍(含)的結尾位元組偏移量。
- EndpointIndex:Endpoints 列表中該範圍應讀取的端點索引。
-
範圍:代表 blob 中連續的位元組範圍。
端點:包含端點元素清單,每個元素指定服務端點。
-
端點:代表可讀取 blob 範圍的服務端點。
- 索引:此端點的索引,由範圍元素參考。
-
值:格式
hostname:port為 的 DNS 主機名稱及埠碼。 這就是你接下來應該讀取的服務端點。
-
端點:代表可讀取 blob 範圍的服務端點。
NextMarker:用於後續
Get Blob Layout請求以取得下一組範圍的延續權杖。 此元素僅在有額外範圍可取時存在。MaxResults:API 呼叫中請求的最大範圍數。
Authorization
在 Azure 記憶體中呼叫任何數據存取作業時,需要授權。 您可以授權 Get Blob Layout 作業,如下所示。
Important
Microsoft建議搭配受控識別使用 Microsoft Entra ID 來授權對 Azure 記憶體的要求。 相較於共用密鑰授權,Microsoft Entra ID 提供更高的安全性和易於使用性。
Azure 儲存體支援使用 Microsoft Entra ID 來授權對 Blob 資料的要求。 使用 Microsoft Entra 識別符,您可以使用 Azure 角色型存取控制 (Azure RBAC) 將權限授與安全性主體。 安全性主體可能是使用者、群組、應用程式服務主體或 Azure 受控識別。 安全性主體是由 Microsoft Entra ID 進行驗證,以傳回 OAuth 2.0 權杖。 權杖接著可以用來授權對 Blob 服務的要求。
若要深入瞭解使用 Microsoft Entra 識別符進行授權,請參閱 使用 Microsoft Entra ID授權 Blob 存取權。
Permissions
以下列出Microsoft Entra 使用者、群組、受控識別或服務主體呼叫 Get Blob Layout 作業所需的 RBAC 動作,以及包含此動作的最低特殊許可權內建 Azure RBAC 角色:
- Azure RBAC作:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
- 最低特權內置角色:存儲 Blob 數據讀取者
若要深入瞭解如何使用 Azure RBAC 指派角色,請參閱 指派 Azure 角色以存取 blob 資料。
備註
此 API 僅適用於 append 和 block blobs。
API 可能在 HTTP 200(OK)或 HTTP 204(無內容)中成功。 若回傳 HTTP 204,blob 無法提供佈局資訊,API 功能等同
Get Blob Properties於 。 若無法取得版面資訊,用戶端應使用標準Get Blob呼叫下載該 blob。如果有 layout 回傳,你可以利用每個 Range 提供的主機和埠,下載 Range 覆蓋的 blob 內容。 強烈建議對通話回傳的
Get Blob LayoutETag下載進行條件,以確保讀取的一致性。回應標頭
x-ms-blob-content-*指的是 blob 本身,而非 layout 子資源。 回應的 永遠Content-Typeapplication/xml是回應實體是否被回傳。API 接受
Rangeorx-ms-range標頭。 如果省略了範圍標頭,請求就是針對整個 blob。 API 永遠不會回傳超出 Range 標頭範圍的範圍。API 是分頁的。 API 可能回傳的範圍不足以涵蓋整個 blob,或對於範圍請求,回傳的範圍無法涵蓋整個請求範圍。 如果發生這種情況,API 會回傳
NextMarker一個,你應該用它來請求額外的範圍。 如果使用了標記,你也必須通過If-Match與產生標記請求中 ETag 相符的條件。 此外,若產生標記的請求包含Rangeorx-ms-range標頭,後續請求必須包含相同的標頭。 若產生標記的請求未包含範圍標頭,後續請求也必須不包含範圍標頭。你絕對不能假設回應中的端點清單與之前
Get Blob Layout任何請求給這個 blob 的端點清單相符。 即使請求使用標記器,端點清單也可能與產生標記的請求端點清單不符。每個範圍回傳的端點是 DNS 主機名稱與埠號,格式為
hostname:port。 這是應該讀取此範圍的服務端點。 你必須同時使用主機名稱和埠口,並在建構 HTTP 請求時使用。 主機名稱可能不包含帳號名稱,因此你必須在後續Get Blob對該端點的 API 呼叫中明確加入適當的Host標頭。即使膠點沒有被修改,膠塊的佈局也可能隨時間改變。 任何 blob 的佈局應該在五分鐘後或修改時重新整理。
也請參閱
授權對 Azure 儲存體的請求
狀態和錯誤碼
Blob 儲存體錯誤碼
設定 Blob 儲存體 操作的逾時Blob 服務概念指定 Blob 儲存體 操作的條件標頭