放置頁面

Put Page 作業會將頁面範圍寫入分頁 Blob。

要求

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

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

模擬儲存體服務 URI

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

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

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

URI 參數

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

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

要求標頭

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

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

指定要以頁面寫入的位元組範圍。 您必須指定開始和結束範圍。 此標頭是由 HTTP/1.1 通訊協定規格所定義。

對於頁面更新作業,頁面範圍的大小最多可達 4 MiB。 若為頁面清除作業,頁面範圍最大可以是 Blob 完整大小的值。

由於頁面必須符合 512 個位元組的界限,因此起始位移必須是 512 的模數,而結束位移必須是 512 - 1 的模數。 有效的位元組範圍範例包括 0-511、512-1023 等。

Blob 服務只接受標頭的單一位元組範圍 Range ,且位元組範圍必須以下列格式指定: bytes=startByte-endByte

如果同時指定 Rangex-ms-range,服務會使用 x-ms-range 的值。 如需詳細資訊 ,請參閱指定 Blob 服務作業的範圍標頭
x-ms-range 需要 Rangex-ms-range

指定要以頁面寫入的位元組範圍。 您必須指定開始和結束範圍。 此標頭是由 HTTP/1.1 通訊協定規格所定義。

對於頁面更新作業,頁面範圍的大小最多可達 4 MiB。 若為頁面清除作業,頁面範圍最大可以是 Blob 完整大小的值。

由於頁面必須符合 512 個位元組的界限,因此起始位移必須是 512 的模數,而結束位移必須是 512 - 1 的模數。 有效的位元組範圍範例包括 0-511、512-1023 等。

Blob 服務只接受標頭的單一位元組範圍 x-ms-range ,且位元組範圍必須以下列格式指定: bytes=startByte-endByte

如果同時指定 Rangex-ms-range,服務會使用 x-ms-range 的值。 如需詳細資訊 ,請參閱指定 Blob 服務作業的範圍標頭
Content-Length 必要。 指定要求主體中所傳輸的位元組數目。 當 x-ms-page-write 標頭設為 clear 時,您必須將此標頭的值設為零。
Content-MD5 選擇性。 頁面內容的 MD5 雜湊。 在傳輸期間,此雜湊可用來驗證頁面的完整性。 指定此標頭,儲存體服務會比較已到達的內容雜湊與此標頭值。

請注意,此 MD5 雜湊不會隨 Blob 儲存。

如果這兩個雜湊不相符,作業會失敗,並顯示錯誤碼 400 (不正確的要求)。
x-ms-content-crc64 選擇性。 頁面內容的 CRC64 雜湊。 在傳輸期間,此雜湊可用來驗證頁面的完整性。 指定此標頭,儲存體服務會比較已到達的內容雜湊與此標頭值。

請注意,此 CRC64 雜湊不會與 Blob 一起儲存。

如果這兩個雜湊不相符,作業會失敗,並顯示錯誤碼 400 (不正確的要求)。

如果同時存在 Content-MD5 和 x-ms-content-crc64 標頭,則要求將會失敗,並出現 400 (不正確的要求) 。

2019-02-02 版或更新版本支援此標頭。
x-ms-page-write: {update | clear} 必要。 您可以指定下列其中一個選項:

- Update:將要求本文指定的位元組寫入指定的範圍。 RangeContent-Length 標頭必須相符,才能執行更新。
- Clear:清除指定的範圍,並釋放該範圍儲存空間。 若要清除範圍,請將 Content-Length 標頭設為零,並將 Range 標頭設為指定要清除之範圍的值 (最大可至 Blob 大小上限)。
x-ms-encryption-scope 選擇性。 指出用來加密要求內容的加密範圍。 2019-02-02 版或更新版本支援此標頭。
x-ms-lease-id:<ID> 如果 Blob 具有作用中租用,則為必要項目。 若要在具有作用中租用的 Blob 執行這項作業,請指定此標頭的有效租用識別碼。
x-ms-if-sequence-number-le: <num> 選擇性。 如果 Blob 的序號小於或等於指定值,要求會繼續,否則會失敗並顯示 SequenceNumberConditionNotMet 錯誤 (HTTP 狀態碼 412 - 先決條件失敗)。
x-ms-if-sequence-number-lt: <num> 選擇性。 如果 Blob 的序號小於指定值,要求會繼續,否則會失敗並顯示 SequenceNumberConditionNotMet 錯誤 (HTTP 狀態碼 412 - 先決條件失敗)。
x-ms-if-sequence-number-eq: <num> 選擇性。 如果 Blob 的序號等於指定值,要求會繼續,否則會失敗並顯示 SequenceNumberConditionNotMet 錯誤 (HTTP 狀態碼 412 - 先決條件失敗)。
If-Modified-Since 選擇性。 DateTime 值。 只有在指定日期/時間修改 Blob 時,才能指定此條件式標頭以寫入頁面。 如果未修改 Blob,Blob 服務會傳回狀態碼 412 (先決條件失敗)。
If-Unmodified-Since 選擇性。 DateTime 值。 只有在未指定日期/時間修改 Blob 時,才能指定此條件式標頭以寫入頁面。 如果已修改 Blob,Blob 服務會傳回狀態碼 412 (先決條件失敗)。
If-Match 選擇性。 ETag 值。 只有在其 ETag 值符合指定值時,才能指定此條件式標頭的 ETag 值寫入頁面。 如果兩值不相符,Blob 服務會傳回狀態碼 412 (先決條件失敗)。
If-None-Match 選擇性。 ETag 值。

只有在其 ETag 值未符合指定值時,才能指定此條件式標頭的 ETag 值寫入頁面。 如果兩值完全相同,Blob 服務會傳回狀態碼 412 (先決條件失敗)。
x-ms-client-request-id 選擇性。 提供用戶端產生的不透明值,其中包含啟用儲存體分析記錄時,分析記錄中記錄的 1 KiB 字元限制。 強烈建議使用此標頭來將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊,請參閱關於儲存體分析記錄Azure 記錄:使用記錄來追蹤儲存體要求

唯有在符合指定條件的情況下,此作業也可支援使用條件式標頭以執行作業。 如需詳細資訊,請參閱指定 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

要求本文

要求主體包含頁面的內容。

範例要求:更新位元組範圍

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:  
x-ms-page-write: update  
x-ms-date: Fri, 16 Sep 2011 22:15:50 GMT  
x-ms-version: 2011-08-18  
x-ms-range: bytes=0-65535  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 65536  
  

範例要求:清除位元組範圍

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:  
Range: bytes=1024-2048  
x-ms-page-write: clear  
x-ms-date: Sun, 25 Sep 2011 23:37:35 GMT  
x-ms-version: 2011-08-18  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
  

回應

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

狀態碼

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

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

回應標頭

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

語法 描述
ETag Blob 的 ETag。 如果要求版本為 2011-08-18 或更新版本,ETag 值會加上引號。 您可以針對 If-MatchIf-None-Match 要求標頭指定 ETag 的值,以使用 ETag 執行條件式 Put Page 作業。
Last-Modified 上次修改 Blob 的時間與日期。 日期格式會依照 RFC 1123。 如需詳細資訊,請參閱 標頭中Date-Time值的表示

Blob 上的任何寫入作業 (包括 Blob 的中繼資料或屬性更新) 都會變更 Blob 的上次修改時間。
Content-MD5 傳回此標頭,以供用戶端檢查訊息內容完整性。 Blob 服務會計算此標頭的值,此值與要求標頭中指定的值不一定相同。 針對 2019-02-02 版或更新版本,只有在要求具有此標頭時,才會傳回此標頭。
x-ms-content-crc64 針對 2019-02-02 版或更新版本,會傳回此標頭,讓用戶端可以檢查訊息內容完整性。 Blob 服務會計算此標頭的值,此值與要求標頭中指定的值不一定相同。

當要求中沒有標頭時 Content-MD5 ,會傳回此標頭。
x-ms-blob-sequence-number 分頁 Blob 目前的序號。
x-ms-request-id 此標頭可唯一識別提出的要求,而且可用來進行要求的疑難排解。 如需詳細資訊,請參閱 針對 API 作業進行疑難排解
x-ms-version 指出用於執行要求的 Blob 服務版本。 對 2009-09-19 及更新版本提出要求會傳回此標頭。
Date 服務產生的 UTC 日期/時間值,可指出啟動回應的時間。
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-client-request-id 此標頭可用來針對要求和對應的回應進行疑難排解。 如果此標頭存在於要求中,且此值最多為 1024 個可見的 ASCII 字元,則此標頭的值等於標頭的值 x-ms-client-request-idx-ms-client-request-id如果要求中沒有標頭,此標頭將不會出現在回應中。

回應本文

無。

範例回應

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Sun, 25 Sep 2011 12:13:31 GMT  
x-ms-version: 2011-08-18  
x-ms-blob-sequence-number: 0  
Content-Length: 0  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
  

授權

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

備註

Put Page 作業會將頁面範圍寫入分頁 Blob。 您只能對現有的分頁 Blob 呼叫這項作業。 您無法呼叫這項作業以建立新的分頁 Blob,也無法對區塊 Blob 呼叫這項作業。 使用目前不存在的 Blob 名稱呼叫 Put Page 會傳回 BlobNotFound 錯誤 (HTTP 狀態碼 404 - 找不到)。

若要建立新的分頁 Blob,請呼叫 Put Blob ,並指定要建立為分頁 Blob 的 Blob 類型。 分頁 Blob 的大小上限為 8 TiB。

如果 Blob 有作用中租用,用戶端必須在要求上指定有效的租用識別碼,才能寫入頁面。

頁面更新作業

搭配 Update 選項呼叫 Put Page 可在指定的分頁 Blob 中執行就地寫入。 指定頁面中的所有內容都會以更新的內容覆寫。

重要

如果在 Put Page 期間伺服器逾時或連線已關閉,則不一定會更新。 因此,您應該繼續重試更新,直到收到表示成功的回應。

針對更新作業提交 Put Page 的每個頁面範圍,大小上限為 4 MiB。 頁面的開始和結束範圍必須符合 512 位元組的界限。 如果您嘗試上傳大於 4 MB 的頁面範圍,服務會傳回狀態碼 413 (要求的實體太大)。

頁面清除作業

搭配 Clear 選項呼叫 Put Page 會釋放指定頁面所使用的儲存空間。 已清除的頁面將不會再當做分頁 Blob 的一部分追蹤。

已清除的頁面由於已釋放其儲存體資源,因此不會再對儲存體帳戶收取費用。 如果分頁 Blob 具有快照集,則是唯一的例外狀況,當相同頁面不再做為來源 Blob 的一部分存在時,快照集中的頁面就會產生費用。

管理並行問題

Blob 服務會循序處理重疊頁面的並行寫入:服務所處理的最後一頁會決定 Blob 的內容。 因此,為了確保 Blob 內容的完整性,用戶端應該使用下列一或多種方法,處理重疊頁面的寫入:

  • 您可以檢查每次成功呼叫 Put PageLast-Modified 回應標頭值。 從 Blob 服務傳回回應的順序,不一定會對應至服務執行回應的順序。 但是,Last-Modified 的值一律會指出服務處理要求的順序。

  • 您可以使用開放式並行存取,根據 Blob 的 ETag 或上次修改時間有條件地執行更新。 此方法適用於並行寫入數目較低的情況。 使用條件式要求標頭 If-MatchIf-None-MatchIf-Modified-SinceIf-Unmodified-Since 可達成此目的。

  • 您可以呼叫 租用 Blob 來鎖定 Blob,以針對一分鐘期間的其他寫入鎖定 Blob,如果租用已更新,則為更長的時間。

  • 您可以使用 Blob 的序號,以確保在重試沒有回應的要求時,不會產生並行更新。 當用戶端需要提高頁面寫入的輸送量時,最適合使用此方法。 下一節將會進行詳細的說明。

使用分頁 Blob 序號重試要求

Put Page 的呼叫逾時或未傳回回應時,您無法確定要求是否成功。 因此,您必須重試要求,但是由於 Azure 儲存體服務的分散本質,原始要求可能在重試的要求成功之後處理。 延遲的原始要求可能會覆寫其他更新,而產生非預期的結果。 以下循序說明發生的情況:

  1. 將值 "X" 寫入頁面 0 的 Put Page 要求逾時或未傳回回應。

  2. 將值 "X" 寫入頁面 0 的重試要求成功。

  3. 將值 "Y" 寫入頁面 0 的要求成功。

  4. 原始要求成功,並將值 "X" 寫入頁面 0。

  5. 當用戶端預期值 "Y" 時,讀取頁面 0 卻傳回值 "X"。

當原始要求未傳回狀態碼 100-499 或 503 (伺服器忙碌) 時,可能發生這類衝突。 如果傳回上述狀態碼之一,則可以確定要求成功或失敗。 但是,如果服務傳回此範圍以外的狀態碼,則無法確定原始要求的狀態。

為了避免這類衝突,您可以使用分頁 Blob 的序號,以確保重試要求時,原始要求不會成功。 為了達成目的,您應該遞增序號,然後再重試原始要求。 然後,您可以使用條件式序號標頭,以確保序號不符合預期的序號時,要求會失敗。 以下循序說明此方法:

  1. 用戶端會建立 具有 Put Blob 的頁面 Blob ,並將其序號設定為 0。

  2. Put Page將值 「X」 寫入第 0 頁的要求, if-sequence-number-lt 標頭設定為 1 逾時或未傳迴響應。

  3. 用戶端呼叫 Set Blob Properties,並將序號更新為 1。

  4. 重試的要求,將值 「X」 寫入第 0 頁,且 if-sequence-number-lt 設定為 2 成功。

  5. 要求將值 「Y」 寫入頁面 0,且 if-sequence-number-lt 設定為 2 成功。

  6. 最終會處理原始要求,但失敗,因為它會指定序號必須小於 1 (的條件, if-sequence-num-lt 也就是標頭設定為 1) 。 錯誤為 SequenceNumberConditionNotMet (HTTP 狀態碼 412 - 先決條件失敗)。

  7. 讀取頁面 0 傳回預期值 "Y"。

另請參閱

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