放置 Blob

作業 Put Blob 會建立新的區塊、分頁或附加 Blob,或更新現有區塊 Blob 的內容。

更新現有的區塊 Blob 會覆寫 Blob 中所有的現有中繼資料。 Put Blob不支援部分更新;現有 Blob 的內容會以新 Blob 的內容覆寫。 若要執行區塊 Blob 內容的部分更新,請使用 Put Block List 作業。

請注意,您只能在 2015-02-21 版和更新版本中建立附加 Blob。

呼叫 Put Blob 以建立分頁 Blob 或附加 Blob 只會初始化 Blob。 若要將內容新增至分頁 Blob,請呼叫 Put Page 作業。 若要將內容新增至附加 Blob,請呼叫 Append Block 作業。

要求

Put Blob 要求的建構如下。 建議使用 HTTPS。 以儲存體帳戶的名稱取代 myaccount

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

模擬儲存體服務 URI

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

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

請注意,儲存體模擬器只支援最多 2 GiB 的 Blob 大小。

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

URI 參數

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

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

要求標頭 (所有 Blob 類型)

下表描述所有 Blob 類型的必要和選擇性要求標頭。

要求標頭 描述
Authorization 必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊,請參閱授權要求Azure 儲存體
Datex-ms-date 必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊,請參閱授權要求Azure 儲存體
x-ms-version 所有授權要求都需要。 指定用於這個要求的作業版本。 如需詳細資訊,請參閱Azure 儲存體 服務的版本設定
Content-Length 必要。 要求的長度。

對於分頁 Blob 或附加 Blob,此標頭的值必須設定為零,因為 Put Blob 僅用於初始化 Blob。 若要將內容寫入現有的分頁 Blob,請呼叫 Put Page。 若要將內容寫入附加 Blob,請呼叫 Append Block
Content-Type 選擇性。 Blob 的 MIME 內容類型。 預設類型為 application/octet-stream
Content-Encoding 選擇性。 指定已套用至 Blob 的內容編碼。 當 取得 Blob 作業在 Blob 資源上執行時,這個值會傳回給用戶端。 用戶端可以使用此傳回的值解碼 Blob 內容。
Content-Language 選擇性。 指定此資源所使用的自然語言。
Content-MD5 選擇性。 Blob 內容的 MD5 雜湊。 在傳輸期間,此雜湊可用來驗證 Blob 的完整性。 指定此標頭時,儲存體服務會根據傳送的雜湊檢查到達時的雜湊。 如果這兩個雜湊不相符,作業會失敗,並顯示錯誤碼 400 (不正確的要求)。

如果在 2012-02-12 版及更新版本中省略,Blob 服務會產生 MD5 雜湊。

取得 Blob取得 Blob 屬性列出 Blob的結果包括 MD5 雜湊。
x-ms-content-crc64 選擇性。 Blob 內容的 CRC64 雜湊。 在傳輸期間,此雜湊可用來驗證 Blob 的完整性。 指定此標頭時,儲存體服務會根據傳送的雜湊檢查到達時的雜湊。 如果這兩個雜湊不相符,作業會失敗,並顯示錯誤碼 400 (不正確的要求)。 02-02-2019 版或更新版本支援此標頭。

如果同時存在 Content-MD5 和 x-ms-content-crc64 標頭,則要求將會失敗,並出現 400 (不正確的要求) 。
Cache-Control 選擇性。 Blob 服務儲存此值,但未使用或修改此值。
x-ms-blob-content-type 選擇性。 設定 Blob 的內容類型。
x-ms-blob-content-encoding 選擇性。 設定 Blob 的內容編碼。
x-ms-blob-content-language 選擇性。 設定 Blob 的內容語言。
x-ms-blob-content-md5 選擇性。 設定 Blob 的 MD5 雜湊。
x-ms-blob-cache-control 選擇性。 設定 Blob 的快取控制。
x-ms-blob-type: <BlockBlob | PageBlob | AppendBlob> 必要。 指定要建立的 Blob 類型:區塊 Blob、分頁 Blob 或附加 Blob。 只有 2015-02-21 版和更新版本才支援建立附加 Blob。
x-ms-meta-name:value 選擇性。 與 Blob 相關聯的名稱/值組,可做為中繼資料。

請注意,從 2009-09-19 版開始,中繼資料名稱必須遵守 C# 識別碼的命名規則。
x-ms-encryption-scope 選擇性。 指出用來加密要求內容的加密範圍。 2019-02-02 版或更新版本支援此標頭。
x-ms-tags 選擇性。 在 Blob 上設定指定的查詢字串編碼標記。 如需詳細資訊,請參閱。 2019-12-12 版和更新版本支援。
x-ms-lease-id:<ID> 如果 Blob 具有作用中租用,則為必要項目。 若要在具有作用中租用的 Blob 執行這項作業,請指定此標頭的有效租用識別碼。
x-ms-blob-content-disposition 選擇性。 設定 Blob 的 Content-Disposition 標頭。 適用於 2013-08-15 和更新版本。

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

取得 Blob 和取得 Blob屬性 作業的回應包括 content-disposition 標頭。
Origin 選擇性。 指定發出要求的來源。 此標頭的顯示會導致在回應上跨原始資源共用標頭。 如需詳細資訊,請參閱儲存體服務的 CORS 支援
x-ms-client-request-id 選擇性。 提供用戶端產生的不透明值,其中包含啟用儲存體分析記錄時,記錄在分析記錄中的 1 KiB 字元限制。 強烈建議使用此標頭來將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊,請參閱關於儲存體分析記錄Azure 記錄:使用記錄來追蹤儲存體要求
x-ms-access-tier 選擇性。 指出要設定在 Blob 上的層。 針對進階儲存體帳戶上的分頁 Blob,僅適用于 2017-04-17 版和更新版本。 如需分頁 Blob 支援層的完整清單,請查看VM 的高效能進階儲存體和受控磁片。 針對區塊 Blob,只有 2018-11-09 版和更新版本才支援 Blob 儲存體或一般用途 v2 帳戶。 區塊 Blob 層 Hot//CoolArchive 的有效值為 。 如需區塊 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。 如需詳細資訊,請參閱指定 Blob 服務作業的條件式標頭

要求標頭 (僅限分頁 Blob)

下表描述的要求標頭只適用於分頁 Blob 上的作業。

要求標頭 描述
x-ms-blob-content-length: bytes 分頁 Blob 需要此項。 此標頭會指定分頁 Blob 的大小上限,最多 8 TiB。 分頁 Blob 大小必須符合 512 個位元組的界限。

如果針對區塊 Blob 或附加 Blob 指定此標頭,Blob 服務會傳回狀態碼 400 (不正確的要求) 。
x-ms-blob-sequence-number: <num> 選擇性。 只能針對分頁 Blob 設定。 序號是使用者控制的值,可用來追蹤要求。 序號的值必須介於 0 到 2^63 - 1 之間。預設值為 0。
x-ms-access-tier 版本 2017-04-17 和更新版本。 僅適用于進階儲存體帳戶上的分頁 Blob。 指定要在 Blob 上設定的層。 如需支援層的完整清單,請查看VM 的高效能進階儲存體和受控磁片
x-ms-client-request-id 此標頭可用來針對要求和對應的回應進行疑難排解。 如果此標頭存在於要求中,且值最多為 1024 個可見的 ASCII 字元,則此標頭 x-ms-client-request-id 的值等於標頭的值。 x-ms-client-request-id如果要求中沒有標頭,則此標頭不會出現在回應中。

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

從 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 的要求:

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblockblob HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
Content-Type: text/plain; charset=UTF-8  
x-ms-blob-content-disposition: attachment; filename="fname.ext"  
x-ms-blob-type: BlockBlob  
x-ms-meta-m1: v1  
x-ms-meta-m2: v2  
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=  
Content-Length: 11  
  
Request Body:  
hello world

此範例要求建立分頁 Blob,並將其大小上限指定為 1024 位元組。 請注意,您必須呼叫 Put Page ,才能將內容新增至分頁 Blob:

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/mypageblob HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
Content-Type: text/plain; charset=UTF-8  
x-ms-blob-type: PageBlob  
x-ms-blob-content-length: 1024  
x-ms-blob-sequence-number: 0  
Authorization: SharedKey   
Origin: http://contoso.com  
Vary: Origin  
myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=  
Content-Length: 0  

此範例要求會建立附加 Blob。 請注意,您必須呼叫 Append Block ,才能將內容新增至附加 Blob:

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myappendblob HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
Content-Type: text/plain; charset=UTF-8  
x-ms-blob-type: AppendBlob  
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=  
Origin: http://contoso.com  
Vary: Origin  
Content-Length: 0  

回應

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

狀態碼

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

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

回應標頭

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

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

Blob 上的任何寫入作業 (包括 Blob 的中繼資料或屬性更新) 都會變更 Blob 的上次修改時間。
Content-MD5 區塊 Blob 會傳回此標頭,以供用戶端檢查訊息內容的完整性。 傳回的 Content-MD5 值會由 Blob 服務進行計算。 在 2012-02-12 版及更新版本中,即使要求未包含 Content-MD5x-ms-blob-content-md5 標頭,也會傳回此標頭。
x-ms-content-crc64 區塊 Blob 會傳回此標頭,以供用戶端檢查訊息內容的完整性。 傳回的 x-ms-content-crc64 值會由 Blob 服務進行計算。 從 2019-02-02 版開始,一律會傳回此標頭。
x-ms-request-id 此標頭可唯一識別提出的要求,而且可用來進行要求的疑難排解。 如需詳細資訊,請參閱 針對 API 作業進行疑難排解
x-ms-version 指出用於執行要求的 Blob 服務版本。 對 2009-09-19 及更新版本提出要求會傳回此標頭。
Date 服務產生的 UTC 日期/時間值,可指出啟動回應的時間。
Access-Control-Allow-Origin 如果要求包含 Origin 標頭,並啟用 CORS 及比對規則,則傳回此標頭。 此標頭會在相符時傳回原始要求標頭的值。
Access-Control-Expose-Headers 如果要求包含 Origin 標頭,並啟用 CORS 及比對規則,則傳回此標頭。 傳回向要求的用戶端或簽發者公開的回應標頭清單。
Access-Control-Allow-Credentials 如果要求包含 Origin 標頭,並啟用 CORS 及不允許所有來源的比對規則,則傳回此標頭。 這個標頭會設定為 true。
x-ms-request-server-encrypted: true/false 版本 2015-12-11 或更新版本。 如果要求的內容使用指定的演算法成功加密,則此標頭的值會設定為 truefalse 否則為 。
x-ms-encryption-key-sha256 版本 2019-02-02 或更新版本。 如果要求使用客戶提供的金鑰進行加密,則會傳回此標頭,因此用戶端可以使用提供的金鑰成功加密要求的內容。
x-ms-encryption-scope 版本 2019-02-02 或更新版本。 如果要求使用加密範圍,則會傳回此標頭,因此用戶端可確保使用加密範圍成功加密要求的內容。
x-ms-version-id: <DateTime> 版本 2019-12-12 和更新版本。 此標頭會傳回可唯一識別 Blob 的不透明 DateTime 值。 此標頭的值表示 Blob 的版本,而且可用於後續要求來存取 Blob。

回應本文

無。

範例回應

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==  
x-ms-content-crc64: 77uWZTolTHU
Date: <date>  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: <date>  
Access-Control-Allow-Origin: http://contoso.com  
Access-Control-Expose-Headers: Content-MD5  
Access-Control-Allow-Credentials: True  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-version-id: <DateTime>  

授權

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

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

備註

當您建立 Blob 時,您必須指定它是否為區塊 Blob、附加 Blob 或分頁 Blob,方法是指定 標頭的值 x-ms-blob-type 。 一旦建立 Blob,便無法變更 Blob 的類型,如需變更,您必須刪除並重新建立 Blob。

下表描述服務版本所允許的最大區塊和 Blob 大小。

服務版本 區塊大小上限 (透過 Put Block) Blob 大小上限 (透過 Put Block List) 透過單一寫入作業的 Blob 大小上限 (透過 Put Blob)
2019-12-12 版和更新版本 4000 MiB 大約 190.7 TiB (4000 MiB X 50,000 個區塊) 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

如果您嘗試上傳大於該服務版本允許的大小上限或大於 8 TiB 的頁面 Blob 的區塊 Blob,則服務會傳回狀態碼 413 (要求實體太大) 。 Blob 服務也會在回應中傳回錯誤的相關資訊,包括 Blob 允許的位元組大小上限。

若要建立新的分頁 Blob,請先呼叫 Put Blob 並指定其大小上限,最多 8 TiB 來初始化 Blob。 建立分頁 Blob 時,請勿在要求主體中包含內容。 建立 Blob 之後,請呼叫 Put Page 將內容新增至 Blob 或加以修改。

若要建立新的附加 Blob,請呼叫 Put Blob 以建立內容長度為零位元組的 Blob。 建立附加 Blob 之後,請呼叫 Append Block 將內容新增至 Blob 的結尾。

如果呼叫 Put Blob 覆寫相同名稱的現有 Blob,則會保留與原始 Blob 相關聯的所有快照集。 若要移除相關聯的快照集,請先呼叫 刪除 Blob ,然後 Put Blob 重新建立 Blob。

Blob 具有透過標頭設定的自訂屬性,可用來儲存與標準 HTTP 標頭相關聯的值。 這些值接著可以藉由呼叫 Get Blob 屬性來讀取,或藉由呼叫 Set Blob Properties來修改。 下表列出自訂屬性標頭及對應的標準 HTTP 標頭:

HTTP 標頭 自訂 Blob 屬性標頭
Content-Type x-ms-blob-content-type
Content-Encoding x-ms-blob-content-encoding
Content-Language x-ms-blob-content-language
Content-MD5 x-ms-blob-content-md5
Cache-Control x-ms-blob-cache-control

在 Blob 中保存這些屬性值的設定語意如下:

  • 如果用戶端指定自訂屬性標頭 (以 x-ms-blob 前置詞指定),則會在 Blob 中儲存此值。

  • 如果用戶端指定標準 HTTP 標頭,而不是自訂屬性標頭,此值會儲存在與 Blob 相關聯的對應自訂屬性中,並在呼叫 Get Blob Properties 時傳回。 例如,如果用戶端在要求中設定 Content-Type 標頭,該值會儲存在 Blob 的 x-ms-blob-content-type 屬性中。

  • 如果用戶端在同一個要求中設定標準 HTTP 標頭及對應的屬性標頭,PUT 要求會使用為標準 HTTP 標頭所提供的值,而為自訂屬性標頭指定的值則會保存在 Blob 中,並由後續 GET 要求傳回。

如果在標頭中 x-ms-tags 提供標記,則必須進行查詢字串編碼。 標記索引鍵和值必須符合設定 Blob 標記中指定的命名和長度需求。 此外, x-ms-tags 標頭最多可以包含 2 kb 的標記。 如果需要更多標籤,請使用 設定 Blob 標籤 作業。

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

如果使用 Put Blob 作業覆寫作用中租用的現有 Blob,更新的 Blob 中會保存此租用,直到過期或釋放為止。

Put Blob每個 MiB 允許 10 分鐘完成作業。 如果作業平均每 MiB 花費超過 10 分鐘的時間,作業將會逾時。

如果未提供 x-ms-access-tier 標頭,覆寫封存的 Blob 將會失敗,且 hot/cool 覆寫 Blob 會繼承舊 Blob 中的層。

另請參閱

授權要求Azure 儲存體
狀態和錯誤碼
Blob 服務錯誤碼
設定 Blob 服務作業的逾時值