Put Page

Put Page 操作は、ページ BLOB にページ範囲を書き込みます。

Request

Put Page 要求の構成は次のとおりです。 HTTPS が推奨されます。 myaccount をストレージ アカウントの名前に置き換えます。

PUT メソッド要求の URI HTTP バージョン
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1

エミュレートされたストレージ サービスの URI

エミューレートされたストレージ サービスに対する要求では、エミュレーターのホスト名と BLOB Service ポートを 127.0.0.1:10000 と指定し、その後にエミューレートされたストレージ アカウント名を指定します。

PUT メソッド要求の URI HTTP バージョン
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=page HTTP/1.1

詳細については、「開発とテストにAzure Storage Emulatorを使用する」を参照してください。

URI パラメーター

次の追加パラメーターを要求の URI で指定できます。

パラメーター 説明
timeout 省略可能。 timeout パラメーターは、秒単位で表されます。 詳細については、「 Blob Service 操作のタイムアウトの設定」を参照してください

要求ヘッダー

必須要求ヘッダーと省略可能な要求ヘッダーを次の表に示します。

要求ヘッダー 説明
Authorization 必須。 承認スキーム、アカウント名、および署名を指定します。 詳細については、「Azure Storage要求を承認する」を参照してください。
Date または x-ms-date 必須。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage要求を承認する」を参照してください。
x-ms-version 承認されたすべての要求に必要です。 この要求に使用する操作のバージョンを指定します。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
Range Range または x-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 Service 操作の範囲ヘッダーの指定 」を参照してください。
x-ms-range Range または x-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 Service 操作の範囲ヘッダーの指定 」を参照してください。
Content-Length 必須。 要求本文で送信されるバイト数を指定します。 x-ms-page-write ヘッダーを clear に設定した場合は、このヘッダーの値を 0 に設定する必要があります。
Content-MD5 省略可能。 ページのコンテンツの MD5 ハッシュ。 このハッシュは転送時のページの整合性を確認するために使用します。 このヘッダーを指定すると、ストレージ サービスによって、到達したコンテンツのハッシュと、このヘッダー値が比較されます。

この MD5 ハッシュは BLOB と共に保存されません。

2 つのハッシュが一致しない場合、操作はステータス コード 400 (Bad Request) で失敗します。
x-ms-content-crc64 省略可能。 ページ コンテンツの CRC64 ハッシュ。 このハッシュは転送時のページの整合性を確認するために使用します。 このヘッダーを指定すると、ストレージ サービスによって、到達したコンテンツのハッシュと、このヘッダー値が比較されます。

この CRC64 ハッシュは BLOB と共に格納されないことに注意してください。

2 つのハッシュが一致しない場合、操作はステータス コード 400 (Bad Request) で失敗します。

Content-MD5 ヘッダーと x-ms-content-crc64 ヘッダーの両方が存在する場合、要求は 400 (無効な要求) で失敗します。

このヘッダーは、バージョン 2019-02-02 以降でサポートされています。
x-ms-page-write: {update | clear} 必須。 次のオプションのいずれかを指定できます。

- Update: 要求本文で指定されたバイトを指定された範囲に書き込みます。 更新を実行するには、Range ヘッダーと Content-Length ヘッダーが一致している必要があります。
- Clear: 指定した範囲をクリアし、その範囲のストレージで使用されている領域を解放します。 範囲をクリアするには、Content-Length ヘッダーを 0 に設定し、Range ヘッダーを、クリアする範囲を示す値 (最大値は BLOB の最大サイズ) に設定します。
x-ms-encryption-scope 省略可能。 要求の内容の暗号化に使用する暗号化スコープを示します。 このヘッダーは、バージョン 2019-02-02 以降でサポートされています。
x-ms-lease-id:<ID> BLOB にアクティブなリースが存在する場合は必須です。 アクティブなリースが存在する BLOB に対してこの操作を実行するには、このヘッダーに有効なリース ID を指定します。
x-ms-if-sequence-number-le: <num> 省略可能。 BLOB のシーケンス番号が指定した値以下である場合、要求が続行されます。それ以外の場合は、要求が SequenceNumberConditionNotMet エラー (HTTP ステータス コード 412 – Precondition Failed) で失敗します。
x-ms-if-sequence-number-lt: <num> 省略可能。 BLOB のシーケンス番号が指定した値未満である場合、要求が続行されます。それ以外の場合は、要求が SequenceNumberConditionNotMet エラー (HTTP ステータス コード 412 – Precondition Failed) で失敗します。
x-ms-if-sequence-number-eq: <num> 省略可能。 BLOB のシーケンス番号が指定した値と等しい場合、要求が続行されます。それ以外の場合は、要求が SequenceNumberConditionNotMet エラー (HTTP ステータス コード 412 – Precondition Failed) で失敗します。
If-Modified-Since 省略可能。 DateTime 値。 この条件ヘッダーを指定すると、BLOB が指定した日付/時刻以降に変更された場合にのみページが書き込まれます。 BLOB が変更されなかった場合、BLOB サービスはステータス コード 412 (Precondition Failed) を返します。
If-Unmodified-Since 省略可能。 DateTime 値。 この条件ヘッダーを指定すると、BLOB が指定した日付/時刻以降に変更されなかった場合にのみページが書き込まれます。 BLOB が変更されている場合、BLOB サービスはステータス コード 412 (Precondition Failed) を返します。
If-Match 省略可能。 ETag 値。 この条件ヘッダーの ETag 値を指定すると、BLOB の ETag 値が指定した値に一致する場合にのみページが書き込まれます。 値が一致しない場合、BLOB サービスはステータス コード 412 (Precondition Failed) を返します。
If-None-Match 省略可能。 ETag 値。

この条件ヘッダーの ETag 値を指定すると、BLOB の ETag 値が指定した値に一致しない場合にのみページが書き込まれます。 値が一致する場合、BLOB Service はステータス コード 412 (Precondition Failed) を返します。
x-ms-client-request-id 省略可能。 ストレージ分析ログが有効になっているときに分析ログに記録される 1 KiB 文字制限を持つ、クライアントによって生成された不透明な値を提供します。 クライアント側のアクティビティをサーバーが受信した要求と関連付けるには、このヘッダーを使用することが強く推奨されます。 詳細については、「Storage AnalyticsログAzure ログ: ログを使用したStorage要求の追跡」を参照してください。

この操作では、条件ヘッダーを使用して、指定した条件を満たした場合にのみ操作を実行することもできます。 詳細については、「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=  
  

Response

応答には、HTTP 状態コードおよび一連の応答ヘッダーが含まれています。

状態コード

操作が正常に終了すると、状態コード 201 (Created) が返されます。

状態コードの詳細については、「 状態とエラー コード」を参照してください。

レスポンス ヘッダー

この操作の応答には、次のヘッダーが含まれています。 応答に追加の標準 HTTP ヘッダーが含まれる場合もあります。 すべての標準ヘッダーは 、HTTP/1.1 プロトコル仕様に準拠しています。

構文 説明
ETag BLOB の ETag。 要求バージョンが 2011-08-18 またはそれ以降である場合、ETag 値は引用符で囲まれます。 If-Match 要求ヘッダーまたは If-None-Match 要求ヘッダーに 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 以降。 このヘッダーの値は、指定したアルゴリズムを true 使用して要求の内容が正常に暗号化された場合に設定されます false 。それ以外の場合は、このヘッダーの値が設定されます。
x-ms-encryption-key-sha256 バージョン 2019-02-02 以降。 このヘッダーは、要求で顧客が指定したキーを暗号化に使用した場合に返されるため、クライアントは、指定されたキーを使用して要求の内容が正常に暗号化されていることを確認できます。
x-ms-encryption-scope バージョン 2019-02-02 以降。 このヘッダーは、要求が暗号化スコープを使用した場合に返されるため、クライアントは、暗号化スコープを使用して要求の内容が正常に暗号化されていることを確認できます。
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:  
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 - Not Found) が返されます。

新しいページ BLOB を作成するには、 Put Blob を 呼び出し、ページ BLOB として作成する BLOB の種類を指定します。 ページ BLOB のサイズは最大 8 TiB です。

BLOB にアクティブなリースが存在する場合、クライアントがページを書き込むには、要求に有効なリース ID を指定する必要があります。

ページの更新操作

Update オプションを指定して Put Page を呼び出すと、指定したページ BLOB に対してインプレース書き込みが実行されます。 指定したページのコンテンツが更新で上書きされます。

重要

Put Page の実行中にサーバーがタイムアウトするか、接続が切断された場合、ページは更新される場合と更新されない場合があります。 したがって、成功を示す応答を受け取るまで更新を再試行し続ける必要があります。

更新操作に対して Put Page 送信されるページの各範囲は、最大 4 MiB のサイズにすることができます。 ページ範囲の開始値と終了値は、512 バイトの境界に合わせて指定する必要があります。 4 MB を超えるページ範囲をアップロードしようとすると、サービスはステータス コード 413 (Request Entity Too Large) を返します。

ページのクリア操作

Clear オプションを指定して Put Page を呼び出すと、指定したページに使用されていたストレージ領域が解放されます。 クリアされたページは、ページ BLOB の一部として追跡されなくなります。

クリアされたページのストレージ リソースは解放されているので、クリアされたページではストレージ アカウントに対する料金が発生しなくなります。 唯一の例外は、ページ BLOB の既存のスナップショットがある場合です。スナップショットのページと同じページがコピー元の BLOB の一部として存在しない場合、スナップショットのページで料金が発生します。

コンカレンシーの問題の管理

BLOB Service では、重複するページへの同時書き込みが順次に処理されます。最後に処理されるページによって BLOB のコンテンツが決まります。 したがってクライアントは、BLOB のコンテンツの整合性を維持するために、次の方法を 1 つ以上使用して重複するページへの書き込みを処理する必要があります。

  • Put Page の呼び出しが成功するたびに、Last-Modified 応答ヘッダーの値を確認します。 BLOB サービスから返される応答の順序は、サービスでの実行順序とは必ずしも一致しません。 しかし、Last-Modified の値は常に、サービスが要求を処理した順序を示します。

  • オプティミスティック コンカレンシー制御を使用して、BLOB の ETag または最終更新時刻に基づく条件付き更新を実行します。 この方法は、同時書き込みの数が比較的少ない場合にうまく機能します。 この目的には、If-MatchIf-None-MatchIf-Modified-Since、および If-Unmodified-Since の各条件要求ヘッダーを使用します。

  • リース BLOB を呼び出して、1 分間、またはリースが更新された場合にそれ以上の間、他の書き込みに対して BLOB をロックできます。

  • BLOB のシーケンス番号を使用して、応答のない要求を再試行する際に同時更新が発生しないようにします。 この方法は、ページ書き込みで高いスループットを必要とするクライアントに最適です。 詳細は次のセクションで説明します。

ページ BLOB のシーケンス番号を使用した要求の再試行

Put Page の呼び出しがタイムアウトした場合や、呼び出しからの応答がない場合、要求が成功したかどうかを確実に知る方法はありません。 したがって要求を再試行する必要がありますが、分散ストレージ サービスという Azure の性質上、再試行した要求の成功後に元の要求が処理されることもあり得ます。 遅れて処理された元の要求によって他の更新が上書きされ、予期しない結果が生じることがあります。 この状況は次のような順序で発生します。

  1. 値 "X" をページ 0 に書き込む Put Page 要求がタイムアウトするか、この要求から応答が返されない。

  2. 値 "X" をページ 0 に書き込む要求の再試行が成功する。

  3. 値 "Y" をページ 0 に書き込む要求が成功する。

  4. 元の要求が成功し、値 "X" がページ 0 に書き込まれる。

  5. ページ 0 の読み取りで、クライアントがこの時点で予期した値 "Y" ではなく値 "X" が返される。

この種の競合は、元の要求からステータス コード 100 ~ 499 または 503 (Server Busy) が返されない場合に発生する可能性があります。 これらのステータス コードのいずれかが返された場合は、要求が成功したか失敗したかを確実に知ることができます。 しかし、サービスがこの範囲外のステータス コードを返した場合は、元の要求の状態を知ることはできません。

この種の競合を回避するには、ページ BLOB のシーケンス番号を使用して、要求を再試行した場合に元の要求が後から成功しないようにします。 これを行うには、元の要求を再試行する前にシーケンス番号を増やす必要があります。 次に、条件シーケンス番号ヘッダーを使用して、シーケンス番号が予期されたシーケンス番号と一致しない場合に要求が失敗するようにします。 この方法は次のような順序で行われます。

  1. クライアントは 、Put BLOB を使用してページ BLOB を作成し、そのシーケンス番号を 0 に設定します。

  2. Put Pageヘッダーがタイムアウトに設定されているか、応答が返されない、ページ 0 if-sequence-number-lt に値 "X" を1書き込む要求。

  3. クライアントは Set Blob Properties を呼び出して、シーケンス番号を 1 に更新する。

  4. 成功に設定されたページ 0 if-sequence-number-lt に値 "X" を書き込む 2 再試行された要求。

  5. 成功に設定されたページ 0 if-sequence-number-lt に値 "Y" を書き込む 2 要求。

  6. 元の要求は最終的に処理されますが、シーケンス番号が 1 未満である必要がある条件 (つまり、ヘッダーが設定1されている) を指定するため、if-sequence-num-lt失敗します。 エラーは SequenceNumberConditionNotMet (HTTP ステータス コード 412 – Precondition Failed)。

  7. ページ 0 の読み取りで、予期した値 "Y" が返される。

参照

Azure Storageへの要求を承認する
ステータス コードとエラー コード
BLOB サービス操作のタイムアウトの設定