匯出 (0) 列印
全部展開

放置分頁

更新日期: 2014年1月

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

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

 

  PUT 方法要求 URI HTTP 版本

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page

HTTP/1.1

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

 

  PUT 方法要求 URI HTTP 版本

http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=page

HTTP/1.1

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

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

 

參數 描述

timeout

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

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

 

要求標頭 描述

Authorization

必要項。指定驗證配置、帳戶名稱及簽章。如需詳細資訊,請參閱Azure 儲存體服務的驗證

Datex-ms-date

必要項。指定要求的國際標準時間 (UTC)。如需詳細資訊,請參閱Azure 儲存體服務的驗證

x-ms-version

所有已驗證要求的必要項。指定用於這個要求的作業版本。如需詳細資訊,請參閱Azure 儲存體服務的版本設定

Range

需要 Rangex-ms-range

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

若為頁面更新作業,頁面範圍的大小上限為 4 MB。若為頁面清除作業,頁面範圍最大可以是 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 MB。若為頁面清除作業,頁面範圍最大可以是 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 雜湊。在傳輸期間,此雜湊可用來驗證頁面的完整性。指定此標頭時,儲存體服務會比較已到達的內容雜湊與傳送的標頭值。如果這兩個雜湊不相符,作業會失敗,並顯示錯誤碼 400 (不正確的要求)。

Content-MD5 標頭設為 x-ms-page-write 時,不允許使用 clear 標頭。如果在要求中包含此標頭,Blob 服務會傳回狀態碼 400 (不正確的要求)。

x-ms-page-write: {update | clear}

必要項。您可以指定下列其中一個選項:

  • Update:將要求主體所指定的位元組寫入指定的範圍。RangeContent-Length 標頭必須相符,才能執行更新。

  • Clear:清除指定的範圍,並釋放該範圍所使用的儲存空間。若要清除範圍,請將 Content-Length 標頭設為零,並將 Range 標頭設為指定要清除之範圍的值 (最大可至 Blob 大小上限)。

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 KB 的字元限制),當儲存體分析記錄為啟用狀態時,此值會記錄在分析記錄檔中。如果是和伺服器所接收的要求相關的用戶端活動,則強烈建議您使用此標頭。如需詳細資訊,請參閱關於儲存體分析記錄Windows Azure 記錄:使用記錄檔追蹤儲存體需求

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

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


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。如需詳細資訊,請參閱標頭中的日期/時間值表示方式

Blob 上的任何寫入作業 (包括 Blob 的中繼資料或屬性更新) 都會變更 Blob 的上次修改時間。

Content-MD5

傳回此標頭,以供用戶端檢查訊息內容完整性。Blob 服務會計算此標頭的值,此值與要求標頭中指定的值不一定相同。

x-ms-blob-sequence-number

分頁 Blob 目前的序號。

x-ms-request-id

此標頭可唯一識別提出的要求,而且可用來進行要求的疑難排解。如需詳細資訊,請參閱對應用程式開發介面作業進行疑難排解

x-ms-version

指出用於執行要求的 Blob 服務版本。對 2009-09-19 及更新版本提出要求會傳回此標頭。

Date

服務產生的 UTC 日期/時間值,可指出啟動回應的時間。

無。

Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
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,請呼叫 放置 Blob,並指定 Blob 的類型以建立為分頁 Blob。分頁 Blob 的大小上限為 1 TB。

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

頁面更新作業

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

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

使用 Put Page 針對更新作業所提交之每個頁面範圍的大小上限為 4 MB。頁面的開始和結束範圍必須符合 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 序號重試要求

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

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

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

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

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

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

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

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

  1. 用戶端使用 放置 Blob 建立分頁 Blob,並將其序號設為 0。

  2. 將值 "X" 寫入頁面 0 的 Put Page 要求 (其 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"。

顯示:
© 2015 Microsoft