Put Page From URL
この操作により Put Page From URL 、URL からコンテンツが読み取られたページ BLOB にページの範囲が書き込まれます。 この API は、バージョン 2018-11-09 以降で使用できます。
要求
要求は Put Page From URL 次のように構築できます。 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 Storage の開発に Azurite エミュレーターを使用する方法に関するページを参照してください。
URI パラメーター
次の追加パラメーターを要求 URI に指定できます。
| パラメーター | 説明 |
|---|---|
timeout |
省略可能。 timeout パラメーターは、秒単位で表されます。 詳細については、「 BLOB サービス操作のタイムアウトを設定する」を参照してください。 |
要求ヘッダー
必須の要求ヘッダーと省略可能な要求ヘッダーを次の表に示します。
| 要求ヘッダー | 説明 |
|---|---|
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 です。 ページは 512 バイトの境界に揃える必要があるため、開始オフセットは 512 の剰余で、終了オフセットは 512 から 1 の剰余である必要があります。 有効なバイト範囲の例としては、0 から 511、512 から 1023 などがあります。 BLOB サービスでは、 Range ヘッダーの範囲としてシングル バイトの範囲だけを受け入れます。このバイト範囲は、bytes=startByte-endByte の形式で指定する必要があります。Range と x-ms-range の両方が指定されている場合、サービスは x-ms-range の値を使用します。 詳細については、「 BLOB サービス操作の範囲ヘッダーを指定する」を参照してください。 |
x-ms-range |
Range または x-ms-range が必須です。ページとして書き込むバイト範囲を指定します。 範囲の開始値と終了値の両方を指定する必要があります。 このヘッダーは、 HTTP/1.1 プロトコル仕様によって定義されます。 ページ範囲のサイズは最大 4 MiB です。 ページは 512 バイトの境界に揃える必要があるため、開始オフセットは 512 の剰余で、終了オフセットは 512 から 1 の剰余である必要があります。 有効なバイト範囲の例としては、0 から 511、512 から 1023 などがあります。 BLOB サービスでは、 x-ms-range ヘッダーの範囲としてシングル バイトの範囲だけを受け入れます。このバイト範囲は、bytes=startByte-endByte の形式で指定する必要があります。Range と x-ms-range の両方が指定されている場合、サービスは x-ms-range の値を使用します。 詳細については、「 BLOB サービス操作の範囲ヘッダーを指定する」を参照してください。 |
Content-Length |
必須。 要求本文で送信されるバイト数を指定します。 このヘッダーの値は 0 に設定する必要があります。 長さが 0 でない場合、状態コード 400 (Bad Request) で操作が失敗します。 |
x-ms-copy-source:name |
必須。 ソース BLOB の URL を指定します。 値には、BLOB を指定する最大 2 KiB の長さの URL を指定できます。 この値は要求 URI に含まれるため、URL でエンコードされる必要があります。 ソース BLOB はパブリックであるか、共有アクセス署名を介して承認されている必要があります。 ソース BLOB がパブリックの場合、操作を実行するために承認は必要ありません。 ソース オブジェクト URL の例を次に示します。 - https://myaccount.blob.core.windows.net/mycontainer/myblob- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime> |
x-ms-copy-source-authorization: <scheme> <signature> |
省略可能。 コピー ソースの承認スキームと署名を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。 Azure Active Directory では、スキーム ベアラーのみがサポートされています。 このヘッダーは、バージョン 2020-10-02 以降でサポートされています。 |
x-ms-source-range |
指定した範囲内のソース URL 内の BLOB のバイトをアップロードします。 範囲の開始値と終了値の両方を指定する必要があります。 このヘッダーは、 HTTP/1.1 プロトコル仕様によって定義されます。 ページ範囲のサイズは最大 4 MiB です。 BLOB サービスでは、 x-ms-source-range ヘッダーの範囲としてシングル バイトの範囲だけを受け入れます。このバイト範囲は、bytes=startByte-endByte の形式で指定する必要があります。詳細については、「 BLOB サービス操作の範囲ヘッダーを指定 する」を参照してください。 |
x-ms-source-content-md5 |
省略可能。 URI からのページ コンテンツの MD5 ハッシュ。 このハッシュは、URI からのデータの転送中にページの整合性を確認するために使用されます。 このヘッダーを指定すると、ストレージ サービスはコピーソースから到着したコンテンツのハッシュをこのヘッダー値と比較します。 注: この MD5 ハッシュは BLOB と共に格納されません。 2 つのハッシュが一致しない場合、操作はエラー コード 400 (無効な要求) で失敗します。 |
x-ms-source-content-crc64 |
省略可能。 URI からのページ コンテンツの CRC64 ハッシュ。 このハッシュは、URI からのデータの転送中にページの整合性を確認するために使用されます。 このヘッダーを指定すると、ストレージ サービスはコピーソースから到着したコンテンツのハッシュをこのヘッダー値と比較します。 注: この CRC64 ハッシュは BLOB と共に格納されません。 2 つのハッシュが一致しない場合、操作はエラー コード 400 (無効な要求) で失敗します。 ヘッダーと x-ms-source-content-crc64 ヘッダーの両方x-ms-source-content-md5が存在する場合、要求は 400 (無効な要求) で失敗します。このヘッダーは、バージョン 2019-02-02 以降でサポートされています。 |
x-ms-lease-id:<ID> |
BLOB にアクティブなリースが存在する場合は必須です。 アクティブなリースが存在する BLOB に対してこの操作を実行するには、このヘッダーに有効なリース ID を指定します。 |
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 (Precondition Failed) を返します。 |
If-Match |
省略可能。 ETag 値。 この条件ヘッダーの ETag 値を指定すると、BLOB の ETag 値が指定した値に一致する場合にのみページが書き込まれます。 値が一致しない場合、BLOB サービスは状態コード 412 (前提条件に失敗) を返します。 |
If-None-Match |
省略可能。 ETag 値。 BLOB の ETag 値が指定した値と一致しない場合にのみ、この条件付きヘッダーに ETag 値を指定してページを書き込みます。 値が一致する場合、BLOB Service はステータス コード 412 (Precondition Failed) を返します。 |
x-ms-encryption-scope |
省略可能。 ソース コンテンツの暗号化に使用する暗号化スコープを示します。 このヘッダーは、バージョン 2019-02-02 以降でサポートされています。 |
x-ms-client-request-id |
省略可能。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「Azure Blob 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-date: Fri, 16 Sep 2011 22:15:50 GMT
x-ms-version: 2018-11-09
x-ms-range: bytes=0-65535
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 0
Response
応答には、HTTP 状態コードおよび一連の応答ヘッダーが含まれています。
status code
操作が正常に終了すると、状態コード 201 (Created) が返されます。
状態コードの詳細については、「 状態とエラー コード」を参照してください。
応答ヘッダー
この操作の応答には、次のヘッダーが含まれています。 応答に追加の標準 HTTP ヘッダーが含まれる場合もあります。 すべての標準ヘッダーは 、HTTP/1.1 プロトコル仕様に準拠しています。
| 構文 | 説明 |
|---|---|
ETag |
BLOB の ETag。 要求バージョンが 2011-08-18 以降の場合、ETag 値は引用符で囲まれます。 If-Match 要求ヘッダーまたは If-None-Match 要求ヘッダーに ETag の値を指定すると、条件付き Put Page From URL 操作を実行できます。 |
Last-Modified |
BLOB が最後に変更された日時。 日付形式は RFC 1123 に従います。 詳細については、「 ヘッダーの日付/時刻値を表す」を参照してください。 BLOB の書き込み操作 (BLOB のメタデータまたはプロパティの更新など) を行うと、BLOB の最終更新時刻が変更されます。 |
Content-MD5 |
クライアントがメッセージ コンテンツの整合性をチェックできるように返されます。 このヘッダーの値は、BLOB サービスによって計算されます。 要求ヘッダーで指定された値と必ずしも同じとは限りません。 バージョン 2019-02-02 以降の場合、このヘッダーは要求にこのヘッダーがある場合にのみ返されます。 |
x-ms-content-crc64 |
バージョン 2019-02-02 以降の場合。 クライアントがメッセージ コンテンツの整合性をチェックできるように返されます。 このヘッダーの値は、BLOB サービスによって計算されます。 要求ヘッダーで指定された値と必ずしも同じとは限りません。 このヘッダーは、ヘッダーが要求に存在しない場合 x-ms-source-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 以降。 このヘッダーの値は、要求の内容が指定したアルゴリズムを使用して正常に暗号化された場合は に設定されますfalse。それ以外の場合は に設定trueされます。 |
x-ms-encryption-key-sha256 |
バージョン 2019-02-02 以降。 要求で顧客が指定したキーを暗号化に使用した場合に返されるため、クライアントは、指定されたキーを使用して要求の内容が正常に暗号化されていることを確認できます。 |
x-ms-encryption-scope |
バージョン 2019-02-02 以降。 要求が暗号化スコープを使用した場合に返されるため、クライアントは暗号化スコープを使用して要求の内容が正常に暗号化されていることを確認できます。 |
x-ms-client-request-id |
要求と対応する応答のトラブルシューティングに使用できます。 このヘッダーの値は、要求に存在し、その値に 1,024 文字以下の ASCII 文字が含まれている場合、ヘッダーの値 x-ms-client-request-id と等しくなります。 ヘッダーが 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 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
承認
Azure Storage でデータ アクセス操作を呼び出す場合は、承認が必要です。 以下で説明するように、操作を Put Page From URL 承認できます。
Azure Storage では、Microsoft Entra IDを使用して BLOB データへの要求を承認することがサポートされています。 Microsoft Entra IDでは、Azure ロールベースのアクセス制御 (Azure RBAC) を使用して、セキュリティ プリンシパルにアクセス許可を付与できます。 セキュリティ プリンシパルには、ユーザー、グループ、アプリケーション サービス プリンシパル、または Azure マネージド ID を指定できます。 セキュリティ プリンシパルは、OAuth 2.0 トークンを返すためにMicrosoft Entra IDによって認証されます。 その後、そのトークンを、Blob service に対する要求を認可するために使用できます。
Microsoft Entra IDを使用した承認の詳細については、「Microsoft Entra IDを使用して BLOB へのアクセスを承認する」を参照してください。
アクセス許可
次に、Microsoft Entraユーザー、グループ、またはサービス プリンシパルが操作を呼び出Put Page From URLすために必要な RBAC アクションと、このアクションを含む最小特権の組み込み Azure RBAC ロールを示します。
- Azure RBAC アクション:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- 最小特権の組み込みロール:ストレージ BLOB データ共同作成者
Azure RBAC を使用したロールの割り当ての詳細については、「 BLOB データにアクセスするための Azure ロールの割り当て」を参照してください。
注釈
Put Page From URL 操作は、ページ BLOB にページ範囲を書き込みます。 この操作は、既存のページ BLOB でのみ呼び出すことができます。 新しいページ BLOB を作成するために呼び出したり、ブロック BLOB で呼び出したりすることはできません。 現在存在しない BLOB 名を指定して を呼び出すと Put Page From URL 、BlobNotFound エラー (HTTP 状態コード 404 – Not Found) が返されます。
バージョン 2020-10-02 以降では、コピー操作のソースに対して Azure Active Directory 承認がサポートされています。
新しいページ BLOB を作成するには、 Put Blob を 呼び出し、ページ BLOB として作成する BLOB の種類を指定します。 ページ BLOB のサイズは最大 8 TiB です。
BLOB にアクティブなリースがある場合、クライアントはページを書き込む要求で有効なリース ID を指定する必要があります。
ページ更新操作
を呼び出すと Put Page From URL 、指定したページ BLOB に対してインプレース書き込みが実行されます。 指定したページのコンテンツが更新で上書きされます。
重要
サーバーがタイムアウトした場合、または の間に Put Page From URL接続が閉じている場合、ページが更新された可能性があります。 したがって、成功を示す応答を受け取るまで更新を再試行し続ける必要があります。
更新操作に対して で Put Page From URL 送信されるページの各範囲は、最大 4 MiB のサイズにすることができます。 ページ範囲の開始値と終了値は、512 バイトの境界に合わせて指定する必要があります。 4 MiB を超えるページ範囲をアップロードしようとすると、サービスは状態コード 413 (要求エンティティが大きすぎる) を返します。
コンカレンシーの問題を管理する
BLOB サービスは、重複するページへの同時書き込みを順番に処理します。 つまり、サービスによって処理される最後のページによって、BLOB のコンテンツが決まります。 したがってクライアントは、BLOB のコンテンツの整合性を維持するために、次の方法を 1 つ以上使用して重複するページへの書き込みを処理する必要があります。
Put Page From URLの呼び出しが成功するたびに、Last-Modified応答ヘッダーの値を確認します。 BLOB サービスから返される応答の順序は、サービスによって実行された順序と必ずしも一致するとは限りません。 しかし、Last-Modifiedの値は常に、サービスが要求を処理した順序を示します。オプティミスティック コンカレンシー制御を使用して、BLOB の ETag または最終更新時刻に基づく条件付き更新を実行します。 この方法は、同時書き込みの数が比較的少ない場合にうまく機能します。 この目的には、
If-Match、If-None-Match、If-Modified-Since、およびIf-Unmodified-Sinceの各条件要求ヘッダーを使用します。リース BLOB を呼び出して、1 分間、またはリースが更新された場合はそれ以上の間、他の書き込みに対して BLOB をロックできます。
BLOB のシーケンス番号を使用して、応答がなかった要求を再試行しても同時更新が発生しないようにすることができます。 この方法は、ページ書き込みで高いスループットを必要とするクライアントに最適です。 詳細については、次のセクションで説明します。
ページ BLOB シーケンス番号を使用して要求を再試行する
への Put Page From URL 呼び出しがタイムアウトした場合、または応答が返されない場合、要求が成功したかどうかを特定する方法はありません。 そのため、要求を再試行する必要がありますが、Azure ストレージ サービスの分散特性により、再試行された要求が成功した後に元の要求が処理される可能性があります。 遅れて処理された元の要求によって他の更新が上書きされ、予期しない結果が生じることがあります。 次のシーケンスは、これがどのように起こるかを示しています。
Put Page From URLページ 0 に値 "X" を書き込む要求がタイムアウトするか、応答を返しません。値 "X" をページ 0 に書き込む要求の再試行が成功する。
値 "Y" をページ 0 に書き込む要求が成功する。
元の要求が成功し、値 "X" がページ 0 に書き込まれる。
ページ 0 の読み取りで、クライアントがこの時点で予期した値 "Y" ではなく値 "X" が返される。
この種の競合は、元の要求が 100 から 499 または 503 (サーバービジー) の間で状態コードを返さない場合に発生する可能性があります。 これらのステータス コードのいずれかが返された場合は、要求が成功したか失敗したかを確実に知ることができます。 しかし、サービスがこの範囲外のステータス コードを返した場合は、元の要求の状態を知ることはできません。
この種の競合を防ぐために、ページ BLOB のシーケンス番号を使用して、要求を再試行しても、元の要求が後で成功しないことを確認できます。 これを行うには、元の要求を再試行する前にシーケンス番号を増やす必要があります。 その後、条件付きシーケンス番号ヘッダーを使用して、要求のシーケンス番号が予想されるシーケンス番号と一致しない場合に要求が失敗することを確認できます。 この方法は次のような順序で行われます。
クライアントは Put BLOB を使用してページ BLOB を 作成し、そのシーケンス番号を 0 に設定します。
Put Page From URLヘッダーがタイムアウトに設定されているか、応答が返されない、ページ 0if-sequence-number-ltに1値 "X" を書き込む要求。クライアントは Set Blob Properties を呼び出して、シーケンス番号を 1 に更新する。
成功に設定
2されたページ 0if-sequence-number-ltに値 "X" を書き込む再試行された要求。成功に設定
2されたページ 0if-sequence-number-ltに値 "Y" を書き込む要求。元の要求は最終的に処理されますが、シーケンス番号を 1 未満にする必要がある条件 (つまり、ヘッダーが に
1設定されている) を指定するため、if-sequence-num-lt失敗します。 エラーは SequenceNumberConditionNotMet (HTTP ステータス コード 412 – Precondition Failed)。ページ 0 の読み取りで、予期した値 "Y" が返される。
こちらもご覧ください
Azure Storage への要求を承認する
状態コードとエラー コード
BLOB サービス操作のタイムアウトを設定する