Put Page From URL操作では、ページの範囲がページ BLOB に書き込まれ、URL から内容が読み取られます。 この 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 ヘッダーの 1 バイト範囲のみを受け入れ、バイト範囲は 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 ヘッダーの 1 バイト範囲のみを受け入れ、バイト範囲は 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への要求を承認する」を参照してください。 スキームベアラーのみが Microsoft Entra でサポートされています。 このヘッダーは、バージョン 2020-10-02 以降でサポートされています。 |
x-ms-source-range |
指定した範囲内のソース URL 内の BLOB のバイトをアップロードします。 範囲の開始と終了の両方を指定する必要があります。 このヘッダーは、HTTP/1.1 プロトコル仕様によって定義されます。 ページ範囲のサイズは最大 4 MiB です。 BLOB サービスは、 x-ms-source-range ヘッダーの 1 バイト範囲のみを受け入れ、バイト範囲は bytes=startByte-endByte の形式で指定する必要があります。詳細については 、「BLOB サービス操作の範囲ヘッダーの指定 」を参照してください。 |
x-ms-source-content-md5 |
任意。 URI からのページコンテンツの MD5 ハッシュ。 このハッシュは、URI からのデータの転送中にページの整合性を確認するために使用されます。 このヘッダーを指定すると、ストレージ サービスは、コピー元から到着したコンテンツのハッシュとこのヘッダー値を比較します。 注: この MD5 ハッシュは BLOB と共に保存されません。 2 つのハッシュが一致しない場合、操作はエラー コード 400 (Bad Request) で失敗します。 |
x-ms-source-content-crc64 |
任意。 URI からのページ コンテンツの CRC64 ハッシュ。 このハッシュは、URI からのデータの転送中にページの整合性を確認するために使用されます。 このヘッダーを指定すると、ストレージ サービスは、コピー元から到着したコンテンツのハッシュとこのヘッダー値を比較します。 注: この CRC64 ハッシュは BLOB と共に保存されません。 2 つのハッシュが一致しない場合、操作はエラー コード 400 (Bad Request) で失敗します。 x-ms-source-content-md5 ヘッダーと x-ms-source-content-crc64 ヘッダーの両方が存在する場合、要求は 400 (Bad Request) で失敗します。このヘッダーは、バージョン 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 値。 この条件付きヘッダーの ETag 値を指定すると、BLOB の ETag 値が指定した値と一致しない場合にのみページが書き込まれます。 値が同じ場合、BLOB サービスは状態コード 412 (前提条件に失敗) を返します。 |
x-ms-encryption-scope |
任意。 ソース コンテンツの暗号化に使用する暗号化スコープを示します。 このヘッダーは、バージョン 2019-02-02 以降でサポートされています。 |
x-ms-client-request-id |
任意。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を持つクライアント生成の不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティと、サーバーが受信する要求を関連付けすることを強くお勧めします。 詳細については、「Monitor Azure Blob Storage」を参照してください。 |
x-ms-file-request-intent |
x-ms-copy-sourceヘッダーが Azure ファイルの URL で、x-ms-copy-source-authorizationヘッダーが OAuth トークンを指定している場合は必須です。 許容される値は backupです。 このヘッダーは、Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action または Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action が、x-ms-copy-source-authorization ヘッダーを使用して承認された ID に割り当てられた RBAC ポリシーに含まれている場合に付与されるように指定します。 バージョン 2025-07-05 以降で使用できます。 |
この操作では、指定した条件が満たされた場合にのみ、条件付きヘッダーを使用して操作を実行することもできます。 詳細については、「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
[応答]
応答には、HTTP 状態コードと一連の応答ヘッダーが含まれます。
状態コード
操作が成功すると、状態コード 201 (Created) が返されます。
状態コードの詳細については、「状態コードとエラー コードを参照してください。
応答ヘッダー
この操作の応答には、次のヘッダーが含まれます。 応答には、追加の標準 HTTP ヘッダーも含まれる場合があります。 すべての標準ヘッダーは、HTTP/1.1 プロトコル仕様に準拠しています。
| 構文 | 説明 |
|---|---|
ETag |
BLOB の ETag。 要求バージョンが 2011-08-18 以降の場合、ETag 値は引用符で囲まれます。 ETag を使用して、Put Page From URL または If-Match 要求ヘッダーにその値を指定することで、条件付きIf-None-Match操作を実行できます。 |
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 以降。 このヘッダーの値は、指定されたアルゴリズムを使用して要求の内容が正常に暗号化された場合は true に設定され、それ以外の場合は false に設定されます。 |
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 操作を承認できます。
Von Bedeutung
Microsoft では、マネージド ID で Microsoft Entra ID を使用して、Azure Storage への要求を承認することをお勧めします。 Microsoft Entra ID は、共有キーの承認と比較して優れたセキュリティと使いやすさを提供します。
Azure Storage では、Microsoft Entra ID を使用して BLOB データへの要求を認可できます。 Microsoft Entra ID を使用すると、Azure ロールベースのアクセス制御 (Azure RBAC) を使用して、セキュリティ プリンシパルにアクセス許可を付与できます。 セキュリティ プリンシパルには、ユーザー、グループ、アプリケーション サービス プリンシパル、または Azure マネージド ID を指定できます。 セキュリティ プリンシパルは、Microsoft Entra ID によって認証され、OAuth 2.0 トークンを返します。 その後、そのトークンを、Blob service に対する要求を認可するために使用できます。
Microsoft Entra ID を使用した承認の詳細については、「Microsoft Entra IDを使用して BLOB へのアクセスを承認する」を参照してください。
権限
Microsoft Entra ユーザー、グループ、マネージド ID、またはサービス プリンシパルが 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 以降では、コピー操作のソースに対して Microsoft Entra 承認がサポートされています。
新しいページ BLOB を作成するには、 Put Blob を呼び出し、ページ BLOB として作成する BLOB の種類を指定します。 ページ BLOB のサイズは最大 8 TiB です。
BLOB にアクティブなリースがある場合、クライアントはページを書き込むための要求で有効なリース ID を指定する必要があります。
ページ更新操作
Put Page From URLを呼び出すと、指定したページ BLOB に対してインプレース書き込みが実行されます。 指定したページ内のすべてのコンテンツは、更新で上書きされます。
Von Bedeutung
Put Page From URL中にサーバーがタイムアウトになったり、接続が閉じられたりした場合は、ページが更新されている場合と更新されていない可能性があります。 したがって、成功を示す応答を受け取るまで、更新を再試行し続ける必要があります。
更新操作のために Put Page From URL で送信されるページの各範囲のサイズは、最大 4 MiB です。 ページの開始範囲と終了範囲は、512 バイト境界に揃える必要があります。 4 MiB を超えるページの範囲をアップロードしようとすると、サービスはステータス コード 413 (要求エンティティが大きすぎる) を返します。
同時実行の問題を管理する
BLOB サービスは、重複するページへの同時書き込みを順番に処理します。 つまり、サービスによって処理される最後のページによって BLOB のコンテンツが決まります。 したがって、BLOB のコンテンツの整合性を確保するには、クライアントは、次の 1 つ以上の方法を使用して、重複するページへの書き込みを処理する必要があります。
Last-Modifiedへの成功した呼び出しごとに、Put Page From URL応答ヘッダーの値を確認できます。 BLOB サービスから返される応答の順序は、必ずしもサービスによって実行された順序に対応しているわけではありません。 ただし、Last-Modifiedの値は、常にサービスが要求を処理した順序を示します。オプティミスティック コンカレンシーを使用して、BLOB の ETag または最終変更時刻に基づいて条件付きで更新を実行できます。 このアプローチは、同時書き込みの数が比較的少ない場合に適しています。 この目的には、条件付き要求ヘッダー
If-Match、If-None-Match、If-Modified-Since、If-Unmodified-Sinceを使用します。Lease Blob を呼び出して、BLOB を他の書き込みに対して 1 分間 (リースが更新された場合はそれより長い期間) ロックできます。
BLOB のシーケンス番号を使用すると、応答がなかった要求を再試行しても同時更新が発生しないようにすることができます。 このアプローチは、ページ書き込みに高いスループットを必要とするクライアントに最適です。 これについては、次のセクションで詳しく説明します。
ページ BLOB シーケンス番号を使用して要求を再試行する
Put Page From URL の呼び出しがタイムアウトしたり、応答が返されなくなったりした場合、要求が成功したかどうかを確実に知る方法はありません。 そのため、要求を再試行する必要がありますが、Azure ストレージ サービスの分散性により、再試行された要求が成功した後に元の要求が処理される可能性があります。 遅延した元の要求は、他の更新を上書きし、予期しない結果をもたらす可能性があります。 次のシーケンスは、これがどのように発生するかを示しています。
ページ 0 に値 "X" を書き込む
Put Page From URL要求がタイムアウトするか、応答を返しません。ページ 0 に値 "X" を書き込む要求が再試行されましたが、成功します。
ページ 0 に値 "Y" を書き込む要求は成功します。
元の要求は成功し、値 "X" がページ 0 に書き込まれます。
ページ 0 を読み取ると、クライアントはこの時点で値 "Y" を期待していたときに、値 "X" が返されます。
この種の競合は、元の要求が 100 から 499 または 503 (Server Busy) の状態コードを返さない場合に発生する可能性があります。 これらのステータス・コードのいずれかが返された場合は、リクエストが成功したか失敗したかを確認できます。 ただし、サービスがこの範囲外の状態コードを返した場合、元の要求の状態を知る方法はありません。
この種の競合を防ぐには、ページ BLOB のシーケンス番号を使用して、要求を再試行したときに元の要求が成功しないようにします。 これを行うには、元の要求を再試行する前にシーケンス番号をインクリメントする必要があります。 その後、条件付きシーケンス番号ヘッダーを使用して、シーケンス番号が予想されるシーケンス番号と一致しない場合にリクエストが失敗することを確認できます。 次のシーケンスは、このアプローチを示しています。
クライアントは 、Put Blob を使用してページ BLOB を作成し、そのシーケンス番号を 0 に設定します。
値 "X" をページ 0 に書き込む
Put Page From URL要求で、if-sequence-number-ltヘッダーが1に設定された場合、タイムアウトするか、応答を返しません。クライアントは Set Blob Properties を呼び出して、シーケンス番号を 1 に更新します。
if-sequence-number-ltを2に設定して値 "X" をページ 0 に書き込む要求を再試行すると、成功します。if-sequence-number-ltを2に設定して、値 "Y" をページ 0 に書き込む要求は成功します。元の要求は最終的に処理されますが、シーケンス番号が 1 未満である必要がある (つまり、
if-sequence-num-ltヘッダーが1に設定されている) という条件が指定されているため、失敗します。 エラーは SequenceNumberConditionNotMet (HTTP 状態コード 412 – 前提条件に失敗しました) です。ページ 0 を読み取ると、期待値 "Y" が返されます。
こちらも参照ください
Azure Storage への要求を承認する
状態コードとエラー コード
BLOB サービス操作のタイムアウトを設定する