Incremental Copy Blob

  • [アーティクル]

この操作によりIncremental Copy Blob、ソース ページ BLOB のスナップショットがコピー先ページ BLOB にコピーされます。 先にコピーしたスナップショットとの差異のみが転送先に転送されます。 コピーされたスナップショットは、元のスナップショットの完全なコピーであり、通常どおりに読み取りまたはコピーできます。 この API は、REST バージョン 2016-05-31 以降でサポートされています。

要求

要求は Incremental Copy Blob 次のように構築できます。 HTTPS が推奨されます。 myaccount をストレージ アカウントの名前に、mycontainer をコンテナーの名前に、myblob をターゲット BLOB の名前に置き換えます。 値 が のincrementalcopyクエリ パラメーターはcomp、この要求が増分スナップショットを作成することを示します。

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

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

エミュレートされたストレージ サービスに対して要求を行う場合は、エミュレーターのホスト名とAzure Blob Storageサービス ポートを 127.0.0.1:10000 として指定し、その後にエミュレートされたストレージ アカウント名を指定します。 また、クエリ パラメーターを にincrementalcopy設定して、この要求がcomp増分コピー用であることを示します。

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

詳細については、「 Azure Storage のローカル開発に Azurite エミュレーターを使用する」を参照してください。

URI パラメーター

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

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

要求ヘッダー

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

要求ヘッダー 説明
Authorization 必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
Date または x-ms-date 必須。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
x-ms-version すべての承認された要求には必須、匿名要求の場合は省略可能です。 この要求に使用する操作のバージョンを指定します。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
If-Modified-Since 省略可能。 DateTime 値。 この条件ヘッダーを指定すると、コピー先 BLOB が指定した日付/時刻以降に変更された場合にのみ BLOB がコピーされます。 ターゲット BLOB が変更されていない場合、Blob Storage は状態コード 412 (前提条件に失敗しました) を返します。
If-Unmodified-Since 省略可能。 DateTime 値。 この条件付きヘッダーを指定すると、指定した日付/時刻以降にコピー先 BLOB が変更されていない場合にのみ BLOB をコピーできます。 コピー先 BLOB が変更された場合、Blob Storage は状態コード 412 (前提条件に失敗) を返します。
If-Match 省略可能。 ETag 値。 指定した値がETag既存のコピー先 BLOB の値と一致する場合にのみ、この条件付きヘッダーのETag値を指定ETagして BLOB をコピーします。 ETagターゲット BLOB の が に指定された If-Matchと一致ETagしない場合、Blob Storage は状態コード 412 (前提条件に失敗しました) を返します。
If-None-Match 省略可能。 ETag値、またはワイルドカード文字 (*)。

指定したETag値がコピー先 BLOB の値と一致しない場合にのみ、この条件付きヘッダーの値をETag指定ETagして BLOB をコピーします。

操作を実行するワイルドカード文字 (*) を指定します(宛先 BLOB が存在しない場合のみ)。

指定した条件が満たされていない場合、Blob Storage は状態コード 412 (前提条件に失敗) を返します。
x-ms-copy-source:name 必須。 ソース ページ BLOB スナップショットの名前を指定します。

この値は、ページ BLOB スナップショットを指定する最大 2 kibibytes (KiB) の長さの URL です。 この値は要求 URI に含まれるため、URL でエンコードされる必要があります。 ソース BLOB URI は、次の 2 つの方法のいずれかで承認できます。

ソース BLOB URI はページ BLOB スナップショットを参照できますが、スナップショットのベース BLOB に作成された共有アクセス署名 (SAS) トークンを含める必要があります。 SAS の符号付きリソース (sr) フィールドを に設定する b必要があります。 (例: https://<account-name>.blob.core.windows.net/<container-name>/<page-blob-name>?snapshot=2022-07-23T00:14:45.3964054Z&sp=r&st=2022-07-23T00:15:38Z&se=2022-07-23T08:15:38Z&spr=https&sv=2021-06-08&sr=b&sig=<signature>)。

ソース BLOB URI は、パブリック ページ BLOB スナップショット (例: https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>) を参照できます。
x-ms-client-request-id 省略可能。 ログ記録の構成時にログに記録される 1 KiB 文字の制限を持つ、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「Azure Blob Storageの監視」を参照してください。

要求本文

[なし] :

Response

応答には HTTP 状態コードと応答ヘッダー セットが含まれます。

status code

操作が正常に終了すると、ステータス コード 202 (Accepted) が返されます。 状態コードの詳細については、「 状態とエラー コード」を参照してください。

応答ヘッダー

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

構文 説明
ETag 条件付きで操作を実行するために使用できる値が含まれます。 値は引用符で囲まれています。
Last-Modified BLOB が最後に変更された日時。 詳細については、「 ヘッダー内の日付/時刻値の表現」を参照してください。

BLOB に対する書き込み操作 (BLOB のメタデータまたはプロパティの更新を含む) は、BLOB の最終変更時刻を変更します。
x-ms-request-id 作成された要求を一意に識別し、要求のトラブルシューティングに使用できます。 詳細については、「 API 操作のトラブルシューティング」を参照してください。
x-ms-version 要求の実行に使用される Blob Storage のバージョンを示します。
Date 応答が開始された時刻を示す UTC 日付/時刻値。 サービスによってこの値が生成されます。
x-ms-copy-id: <id> このコピー操作の文字列識別子。 をGet Blob Properties使用して、このコピー操作の状態をチェックするか、 を にAbort Copy Blob渡して保留中のコピーを停止します。
x-ms-copy-status: pending コピー操作の状態。 コピーが開始され、進行中であることを示すために、これは常に保留中です。
x-ms-client-request-id 要求と対応する応答のトラブルシューティングに使用できます。 このヘッダーの値は、要求に存在する x-ms-client-request-id 場合、ヘッダーの値と同じです。 この値は、最大 1,024 文字の ASCII 文字で表示されます。 ヘッダーが x-ms-client-request-id 要求に存在しない場合、応答には存在しません。

応答本文

[なし] :

応答のサンプル

増分コピーを実行する要求の応答例を次に示します。

Response Status:
HTTP/1.1 202 Accepted

Response Headers: 
Last-Modified: <date> 
ETag: "0x8CEB669D794AFE2"
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402
x-ms-version: 2016-05-31
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-copy-status: pending
Date: <date>

承認

Azure Storage でデータ アクセス操作を呼び出す場合は、承認が必要です。 次のセクションでは、操作の 宛先オブジェクト を Incremental Copy Blob 承認する方法について説明します。 ソース BLOB またはファイルへのアクセスは、要求ヘッダーの詳細で説明されているように、個別に x-ms-copy-source 承認されます。

重要

Microsoft では、マネージド ID でMicrosoft Entra IDを使用して、Azure Storage への要求を承認することをお勧めします。 Microsoft Entra IDは、共有キーの承認と比較して優れたセキュリティと使いやすさを提供します。

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ユーザー、グループ、マネージド ID、またはサービス プリンシパルが操作を呼び出Incremental Copy Blobすために必要な RBAC アクションと、このアクションを含む最小特権の組み込み Azure RBAC ロールを次に示します。

Azure RBAC を使用したロールの割り当ての詳細については、「 BLOB データにアクセスするための Azure ロールの割り当て」を参照してください。

注釈

増分コピーのコピー先が存在しないか、同じソース BLOB から以前の増分コピーを使用して作成されている必要があります。 作成後、コピー先 BLOB はソースに永続的に関連付けられます。増分コピーにのみ使用できます。 Get Blob Properties API と List Blobs API は、BLOB がこのように作成された増分コピー BLOB であるかどうかを示します。

増分コピー BLOB を直接ダウンロードすることはできません。 サポートされている操作は、 Get Blob Properties、 Incremental Copy Blob、および Delete Blobのみです。 コピーしたスナップショットは、通常どおりに読み取りおよび削除できます。

サービスで増分コピーを非同期的に実行し、完了をポーリングする必要があります。 保留中のコピーを Copy Blob ポーリングする方法の詳細については、API を参照してください。 コピーが完了すると、コピー先 BLOB に新しいスナップショットが含まれます。 API はGet Blob Properties、新しく作成されたスナップショットのスナップショット時刻を返します。

コピー先 BLOB で初めて増分コピーを実行すると、新しい BLOB が作成され、ソースから完全にコピーされたスナップショットが作成されます。 以降の をIncremental Copy Blob呼び出すたびに、前にコピーしたスナップショットからの差分変更のみをコピーすることで、新しいスナップショットが作成されます。

差分変更は、ソース BLOB スナップショットで呼び出しをGet Page Ranges発行することによって、サーバー上で計算されます。 最後にコピーしたスナップショットに設定prevsnapshotします。 したがって、 にも同じ制限が Get Page Ranges 適用されます Incremental Copy Blob。 具体的には、スナップショットを昇順でコピーする必要があります。ソース BLOB が または Copy BlobIncremental Copy Blob を使用Put Blobして再作成された場合、新しいスナップショットでは失敗します。

コピーされたスナップショットによって消費される追加の記憶域スペースは、コピー中に転送される差分データのサイズです。 このサイズを確認するには、スナップショットで差分 Get Page Ranges API 呼び出しを実行して、前のスナップショットと比較します。

こちらもご覧ください

Azure Storage への要求を承認する
状態コードとエラー コード
Blob Storage 操作のタイムアウトの設定