放置區塊清單

Put Block List 作業可透過指定組成 Blob 的區塊識別碼清單,將 Blob 寫入。 為了寫入 blob 的一部分,必須先將區塊成功寫入伺服器,然後才會在先前的 Put 區塊 作業中寫入伺服器。

您可以呼叫 Put Block List,只上傳已變更的區塊,然後同時認可新的及現有的區塊,以更新 Blob。 若要達成此目的,您可從認可的區塊清單或未認可的區塊清單中的區塊指定是否要認可此區塊,或認可最近上傳的區塊版本 (而不論其所屬的清單為何)。

要求

Put Block List 要求的建構如下。 建議使用 HTTPS。 以您的儲存體帳戶名稱取代 我的帳戶

PUT 方法要求 URI HTTP 版本
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1

模擬儲存體服務 URI

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

PUT 方法要求 URI HTTP 版本
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=blocklist HTTP/1.1

儲存體模擬器最多隻支援2個 GiB 的 blob 大小。

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

URI 參數

您可以在要求的 URI 中指定下列其他參數。

參數 描述
timeout 選擇性。 timeout 參數以秒為單位。 如需詳細資訊,請參閱 設定 Blob 服務作業的超時

要求標頭

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

要求標頭 描述
Authorization 必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊,請參閱授權 Azure 儲存體的要求
Datex-ms-date 必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊,請參閱授權 Azure 儲存體的要求
x-ms-version 所有授權要求都需要。 指定用於這個要求的作業版本。 如需詳細資訊,請參閱Azure 儲存體服務的版本控制
Content-Length 必要。 要求內容的長度 (以位元組為單位)。 此標頭是指區塊清單的內容長度,而不是 blob 本身的長度。
Content-MD5 選擇性。 要求內容的 MD5 雜湊。 在傳輸期間,此雜湊可用來驗證要求內容的完整性。 如果這兩個雜湊不相符,作業會失敗,並顯示錯誤碼 400 (不正確的要求)。

此標頭與要求內容相關聯,而不是與 blob 本身的內容相關聯。
x-ms-content-crc64 選擇性。 要求內容的 crc64 雜湊。 在傳輸期間,此雜湊可用來驗證要求內容的完整性。 如果這兩個雜湊不相符,作業會失敗,並顯示錯誤碼 400 (不正確的要求)。

此標頭與要求內容相關聯,而不是與 blob 本身的內容相關聯。

如果同時有 Content-type 和 crc64 標頭,要求將會失敗,並出現 400 (錯誤的要求) 。

Versions2019-02-02 或更新版本支援此標頭。
x-ms-blob-cache-control 選擇性。 設定 Blob 的快取控制。 如果指定,此屬性會儲存在 Blob 中,並在讀取要求時傳回。

如果要求中未指定此屬性,則會在要求成功時,從 Blob 中清除此屬性。
x-ms-blob-content-type 選擇性。 設定 Blob 的內容類型。 如果指定,此屬性會儲存在 Blob 中,並在讀取要求時傳回。

如果未指定內容類型,則會設為預設類型 application/octet-stream
x-ms-blob-content-encoding 選擇性。 設定 Blob 的內容編碼。 如果指定,此屬性會儲存在 Blob 中,並在讀取要求時傳回。

如果要求中未指定此屬性,則會在要求成功時,從 Blob 中清除此屬性。
x-ms-blob-content-language 選擇性。 設定 Blob 的內容語言。 如果指定,此屬性會儲存在 Blob 中,並在讀取要求時傳回。

在要求中未指定此屬性,則會在要求成功時,從 Blob 中清除此屬性。
x-ms-blob-content-md5 選擇性。 Blob 內容的 MD5 雜湊。 由於個別區塊的雜湊是在每個上傳時進行驗證,因此不會驗證此雜湊。

取得 Blob作業會在 CONTENT-TYPE-MD5 回應標頭中傳回此標頭的值。

如果要求中未指定此屬性,則會在要求成功時,從 Blob 中清除此屬性。
x-ms-meta-name:value 選擇性。 與 Blob 相關聯之使用者定義的名稱/值組。

從2009-09-19 版開始,中繼資料名稱必須遵守 c # 識別碼的命名規則。
x-ms-encryption-scope 選擇性。 表示用來加密 blob 的加密範圍。 此值必須符合用來加密正在認可之所有區塊的加密範圍。 2019-02-02 或更新版本中支援此標頭。
x-ms-tags 選擇性。 在 blob 上設定指定的查詢字串編碼標記。 如需其他資訊,請參閱備註。 在2019-12-12 版和更新版本中支援。
x-ms-lease-id:<ID> 如果 Blob 具有作用中租用,則為必要項目。 若要在具有作用中租用的 Blob 執行這項作業,請指定此標頭的有效租用識別碼。
x-ms-client-request-id 選擇性。 提供用戶端產生的不透明值,具有1個 KiB 字元限制,當啟用儲存體分析記錄時,記錄在分析記錄中。 強烈建議使用此標頭來將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊,請參閱關於儲存體分析記錄Azure 記錄:使用記錄檔追蹤儲存體要求
x-ms-blob-content-disposition 選擇性。 設定 Blob 的 Content-Disposition 標頭。 適用於 2013-08-15 和更新版本。

Content-Disposition 標頭欄位會傳遞如何處理回應裝載的其他資訊,也可用來附加其他中繼資料。 例如,如果設為 attachment,它會指出使用者代理程式不該顯示回應,而會顯示 [另存新檔] 對話方塊。

來自「 取得 blob 」和「 取得 blob 屬性 」作業的回應包含內容配置標頭。
x-ms-access-tier 選擇性。 2018-11-09 版和更新版本。 指出要在 blob 上設定的層級。 針對區塊 blob,blob 儲存體或一般用途 v2 帳戶僅支援2018-11-09 版和更新版本。 區塊 blob 層的有效值為 Hot / Cool / Archive 。 如需區塊 blob 階層處理的詳細資訊,請參閱經常性存取、非經常性存取 和封存儲存層
x-ms-immutability-policy-until-date 2020-06-12 版和更新版本。 指定要在 blob 上設定的「保留到」日期。 這是可保護 blob 不受修改或刪除的日期。 遵循 RFC1123 格式。
x-ms-immutability-policy-mode 2020-06-12 版和更新版本。 指定要在 blob 上設定的永久性原則模式。 有效的值為 unlocked / lockedunlocked 指出使用者可以藉由增加或減少保留期限,來變更原則。 locked 表示禁止這些動作。
x-ms-legal-hold 2020-06-12 版和更新版本。 指定要在 blob 上設定的合法保存,有效的值為 true/false

唯有在符合指定條件的情況下,此作業也可支援使用條件式標頭以認可區塊清單。 如需詳細資訊,請參閱指定 Blob 服務作業的條件式標頭

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

從2019-02-02 版開始,您可以在要求上指定下列標頭,以使用客戶提供的金鑰來加密 blob。 使用客戶提供的金鑰進行加密 (以及對應的標頭集合) 是選擇性的。

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

要求本文

在要求主體中,您可以指定 Blob 服務應該針對要求區塊檢查哪些區塊清單。 如此一來,您就可以藉由插入、取代或刪除個別區塊來更新現有的 blob,而不是將整個 blob。 在您上傳已變更的一個或多個區塊之後,您可以透過同時認可新區塊及想保留的現有區塊,認可新版本的 Blob。

若要更新 Blob,您可以指定服務在認可的區塊清單或未認可的區塊清單中尋找區塊識別碼,或先後在未認可及認可的區塊清單中尋找區塊識別碼。 請如下所示,在要求主體的適當 XML 項目中指定區塊識別碼,以表示所要使用的方法:

  • Committed 項目中指定區塊識別碼,表示 Blob 服務只應在認可的區塊清單中搜尋具名區塊。 如果在認可的區塊清單中找不到此區塊,此區塊不會當做 Blob 的一部分寫入,且 Blob 服務會傳回狀態碼 400 (不正確的要求)。

  • Uncommitted 項目中指定區塊識別碼,表示 Blob 服務只應在未認可的區塊清單中搜尋具名區塊。 如果在未認可的區塊清單中找不到此區塊,此區塊不會當做 Blob 的一部分寫入,且 Blob 服務會傳回狀態碼 400 (不正確的要求)。

  • Latest 項目中指定區塊識別碼,表示 Blob 服務應先搜尋未認可的區塊清單。 如果在未認可的清單中找到此區塊,此區塊會是最新版本,且應該寫入 Blob。 如果在未認可的清單找不到此區塊,則服務應該在認可的區塊清單中搜尋具名區塊,並將找到的區塊寫入 Blob。

本版 Put Block List 的要求主體使用下列 XML 格式:

<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Committed>first-base64-encoded-block-id</Committed>  
  <Uncommitted>second-base64-encoded-block-id</Uncommitted>  
  <Latest>third-base64-encoded-block-id</Latest>  
  ...  
</BlockList>  
  

範例要求

若要示範 Put Block List,請假設您已上傳三個目前想認可的區塊。 下列範例會透過指定列示的每個區塊所應使用的最新版本,認可新的 Blob。 您不需要確定是否已認可這些區塊。

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1  
  
Request Headers:  
x-ms-date: Wed, 31 Aug 2011 00:17:43 GMT  
x-ms-version: 2011-08-18  
Content-Type: text/plain; charset=UTF-8  
Authorization: SharedKey myaccount:DJ5QZSVONZ64vAhnN/wxcU+Pt5HQSLAiLITlAU76Lx8=  
Content-Length: 133  
  
Request Body:  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Latest>AAAAAA==</Latest>  
  <Latest>AQAAAA==</Latest>  
  <Latest>AZAAAA==</Latest>  
</BlockList>  
  

接下來,假設您想更新 Blob。 新的 Blob 將具有下列變更:

  • 識別碼為 ANAAAA== 的新區塊。 必須先使用 Put 區塊 的呼叫來上傳此區塊,並且會出現在未認可的區塊清單中,直到呼叫為止 Put Block List

  • 識別碼為 AZAAAA== 之區塊的更新版本。 必須先使用 Put 區塊 的呼叫來上傳此區塊,並且會出現在未認可的區塊清單中,直到呼叫為止 Put Block List

  • 移除識別碼為 AAAAAA== 的區塊。 如果 Put Block List 的下一個呼叫未包含此區塊,則表示此區塊會有效地從 Blob 中移除。

下列範例示範如何呼叫 Put Block List 以更新 Blob:

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1  
  
Request Headers:  
x-ms-date: Wed, 31 Aug 2009 00:17:43 GMT  
x-ms-version: 2011-08-18  
Content-Type: text/plain; charset=UTF-8  
Authorization: SharedKey myaccount:DJ5QZSVONZ64vAhnN/wxcU+Pt5HQSLAiLITlAU76Lx8=  
Content-Length: 133  
  
Request Body:  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Uncommitted>ANAAAA==</Uncommitted>  
  <Committed>AQAAAA==</Committed>  
  <Uncommitted>AZAAAA==</Uncommitted>  
</BlockList>  
  

回應

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

狀態碼

成功的作業會傳回狀態碼「201 (已建立)」。

如需狀態碼的相關資訊,請參閱 狀態和錯誤碼

回應標頭

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

回應 說明
ETag 實體標記包含用戶端使用 GET/PUT 要求標頭執行條件式 If-Match 作業所使用的值。 如果要求版本為 2011-08-18 或更新版本,ETag 值會加上引號。
Last-Modified 上次修改 Blob 的日期/時間。 日期格式會依照 RFC 1123。 如需詳細資訊,請參閱 標頭中 Date-Time 值的表示

修改 Blob 的任何作業 (包括 Blob 更新的中繼資料或屬性),都會變更 Blob 上次修改的時間。
Content-MD5 傳回此標頭,以供用戶端檢查訊息內容完整性。 此標頭是指要求的內容,在本例中是指區塊的清單,而不是 Blob 本身的內容。 若為 versions2019-02-02 或更新版本,只有在要求具有此標頭時,才會傳回此標頭。
x-ms-content-crc64 若為2019-02-02 版和更新版本,則會傳回此標頭,讓用戶端可以檢查訊息內容完整性。 此標頭是指要求的內容,在本例中是指區塊的清單,而不是 Blob 本身的內容。

Content-md5要求中不存在標頭時,會傳回此標頭。
x-ms-request-id 此標頭可唯一識別提出的要求,而且可用來進行要求的疑難排解。 如需詳細資訊,請參閱 疑難排解 API 作業
x-ms-version 指出用於執行要求的 Blob 服務版本。 對 2009-09-19 及更新版本提出要求會傳回此標頭。
Date 服務產生的 UTC 日期/時間值,可指出啟動回應的時間。
x-ms-request-server-encrypted: true/false 2015-12-11 版或更新版本。 true如果使用指定的演算法成功加密要求的內容,則此標頭的值會設為,否則為 false
x-ms-encryption-key-sha256 2019-02-02 版或更新版本。 如果要求使用客戶提供的金鑰進行加密,則會傳回此標頭,讓用戶端可以使用提供的金鑰來確保要求的內容已成功加密。
x-ms-encryption-scope 2019-02-02 版或更新版本。 如果要求使用加密範圍,則會傳回此標頭,因此用戶端可以使用加密範圍來確定要求的內容已成功加密。
x-ms-version-id: <DateTime> 2019-12-12 版和更新版本。 此標頭會傳回可 DateTime 唯一識別 blob 的不透明值。 此標頭的值會指出 blob 的版本,並可在後續要求中用來存取 blob。
x-ms-client-request-id 此標頭可用於疑難排解要求和對應的回應。 x-ms-client-request-id如果要求中有標頭的值,且值最多1024個可見的 ASCII 字元,則此標頭的值會等於標頭的值。 如果 x-ms-client-request-id 標頭不存在於要求中,則回應中不會出現此標頭。

範例回應

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 00:17:44 GMT  
ETag: “0x8CB172A360EC34B”  
Last-Modified: Sun, 25 Sep 2011 00:17:43 GMT  
x-ms-version: 2011-08-18  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-version-id: <DateTime>  

授權

帳戶擁有者以及擁有共用存取簽章的任何人才能呼叫此作業,且簽章需有此 Blob 或其容器的寫入權限。

如果要求指定具有 x-ms-tags 要求標頭的標記,則呼叫端必須符合 設定 Blob 標記 作業的授權需求。

備註

Put Block List 作業會強制執行此順序,結合區塊以建立 Blob。

您可以在區塊清單中指定多次相同的區塊識別碼。 如果指定多次區塊識別碼,則會以區塊清單中每個出現位置的位元組範圍代表最終認可的 Blob。 如果區塊識別碼在清單中出現多次,則必須在相同的區塊清單中指定區塊識別碼的兩個執行個體。 換句話說,您必須在 Committed 項目、Uncommitted 項目或 Latest 項目中指定這兩個執行個體。

透過 Put Block List,您可以插入、更新或刪除個別區塊以修改現有的 Blob,而不需要再重新上傳整個 Blob。 您可以指定目前認可的區塊清單和未認可的區塊清單中的區塊識別碼,以建立新的 Blob 或更新現有 Blob 的內容。 如此一來,您就可以從未認可的區塊清單中指定一些新的區塊,並從認可的區塊清單中指定其餘的區塊,以更新 blob,這些區塊已經是現有 blob 的一部分。

如果在 Latest 項目中指定區塊識別碼,但認可及未認可的區塊清單中存在相同的區塊識別碼,Put Block List 會認可位於未認可的區塊清單中的區塊。 如果此區塊識別碼存在於認可的區塊清單中,但不存在於未認可的區塊清單中,則 Put Block List 會認可位於認可的區塊清單中的區塊。

區塊 blob 中的每個區塊都可以是不同的大小。 區塊 blob 最多可以包含50000認可的區塊。 可能與 blob 相關聯的未認可區塊數目上限為100000。 下表說明服務版本所允許的最大區塊和 blob 大小:

服務版本 區塊大小上限 (透過 Put Block) Blob 大小上限 (透過 Put Block List) 透過單一寫入作業的 Blob 大小上限 (透過 Put Blob)
2019-12-12 版和更新版本 4000 MiB 大約 190.7 TiB (4000 MiB X 50000 區塊) 5000 MiB (預覽)
2016-05-31 版至 2019-07-07 版 100 MiB 大約 4.75 TiB (100 MiB X 50,000 個區塊) 256 MiB
2016-05-31 之前的版本 4 MiB 大約 195 GiB (4 MiB X 50,000 個區塊) 64 MiB

當您呼叫 Put Block List 更新現有的 Blob 時,會覆寫 Blob 的現有屬性和中繼資料。 但是,任何現有的快照集會保留在 Blob 中。 您可以使用此條件式標頭,僅在符合指定條件時,才執行作業。

如果 Put Block List 作業因遺漏區塊而失敗,您必須上傳遺漏的區塊。

繼上次 Put Block 作業成功之後,如果一星期內沒有在 Blob 上成功呼叫 Put Block ListPut Block,任何未認可的區塊都會進行記憶體回收。 如果在 blob 上呼叫 Put Blob ,任何未認可的區塊都會進行垃圾收集。

如果標頭中有提供標記 x-ms-tags ,它們必須是查詢字串編碼。 標記索引鍵和值必須符合 Set Blob 標記中所指定的命名和長度需求。 此外, x-ms-tags 標頭可能包含大小最多為 2 KiB 的標記。 如果需要更多標記,請使用 設定 Blob 標記 作業。

如果 Blob 有作用中租用,用戶端必須在要求上指定有效的租用識別碼,才能認可區塊清單。 如果用戶端未指定租用識別碼,或是指定無效的租用識別碼,Blob 服務會傳回狀態碼 412 (先決條件失敗)。 如果用戶端指定租用識別碼,但是 Blob 沒有作用中租用,Blob 服務也會傳回狀態碼 412 (先決條件失敗)。 如果用戶端指定尚不存在的 Blob 租用識別碼,Blob 服務會針對根據 2013-08-15 及更新版本所提出的要求傳回狀態碼 412 (先決條件失敗),並針對舊版傳回狀態碼 201 (已建立)。

如果 Blob 有作用中租用,且您呼叫 Put Block List 更新 Blob,更新的 Blob 中會保留此租用。

Put Block List 只適用於區塊 Blob。 對分頁 Blob 呼叫 Put Block List 會導致狀態碼 400 (不正確的要求)。

hot / 如果未提供 x-ms 存取層標頭,覆寫封存的 blob 將會失敗,而且覆寫 cool blob 將會從舊 blob 繼承階層。

另請參閱

瞭解區塊 Blob、附加 Blob 和分頁 Blob
授權 Azure 儲存體的要求
狀態和錯誤碼
Blob 服務錯誤碼
設定 Blob 服務作業的逾時值