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

• Azure RBAC アクション:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write (既存の BLOB への書き込み用) または Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action (新しい BLOB を宛先に書き込むため)
• 最小特権の組み込みロール:ストレージ BLOB データ共同作成者

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

共有アクセス署名 (SAS)

Shared Access Signature (SAS) は、ストレージ アカウント内のリソースへのセキュリティで保護された委任されたアクセスを提供します。 SAS を使用すると、クライアントがデータにアクセスする方法をきめ細かく制御できます。 クライアントがアクセスできるリソース、それらのリソースに対するアクセス許可、および SAS が有効な期間を指定できます。

この操作では Incremental Copy Blob 、 ユーザー委任 SAS、 サービス SAS、 アカウント SAS の 3 種類の共有アクセス署名がサポートされています。

セキュリティのベスト プラクティスとして、ストレージ アカウント キーではなくMicrosoft Entra資格情報を使用することをお勧めします。これは、より簡単に侵害される可能性があります。 アプリケーション設計で共有アクセス署名が必要な場合は、可能であれば、Microsoft Entra資格情報を使用してユーザー委任 SAS を作成します。

ストレージ アカウントに対して共有キー アクセスが許可されていない場合、サービス SAS トークンまたはアカウント SAS トークンは、Blob Storage への要求では許可されません。 詳細については、「 共有キーの禁止が SAS トークンにどのように影響するかを理解する」を参照してください。

ユーザー委任 SAS

ユーザー委任 SAS は、Microsoft Entra資格情報と、SAS に対して指定されたアクセス許可によっても保護されます。

BLOB リソースに Incremental Copy Blob 委任された SAS トークンを使用して操作を呼び出すには、ユーザー委任 SAS トークンの一部として次のアクセス許可が必要です。

操作	オブジェクトの種類	署名されたアクセス許可
Incremental Copy Blob	宛先 BLOB (新規)	作成 (c) または書き込み (w)
Incremental Copy Blob	宛先 BLOB (既存)	書き込み (w)

ユーザー委任 SAS の詳細については、「ユーザー 委任 SAS の作成」を参照してください。

サービス SAS

サービス SAS は、ストレージ アカウント キーで保護されます。 サービス SAS は、BLOB ストレージなどの単一の Azure Storage サービス内のリソースへのアクセスを委任します。

BLOB リソースに Incremental Copy Blob 委任された SAS トークンを使用して操作を呼び出すには、サービス SAS トークンの一部として次のアクセス許可が必要です。

操作	オブジェクトの種類	署名されたアクセス許可
Incremental Copy Blob	宛先 BLOB (新規)	作成 (c) または書き込み (w)
Incremental Copy Blob	宛先 BLOB (既存)	書き込み (w)

サービス SAS の詳細については、「サービス SAS の 作成」を参照してください。

アカウント SAS

アカウント SAS は、ストレージアカウント キーで保護されます。 アカウント SAS は、1 つ以上のストレージ サービスのリソースへのアクセスを委任します。 サービスまたはユーザー委任 SAS を介して実行できるすべての操作は、アカウント SAS を介しても実行できます。

次の表は、アクセスを委任するときに指定する署名付きリソースの種類と署名付きアクセス許可を示しています。

操作	オブジェクトの種類	署名済みサービス	署名されたリソースの種類	署名されたアクセス許可
Incremental Copy Blob	宛先 BLOB (新規)	BLOB (b)	オブジェクト (o)	作成 (c) または書き込み (w)
Incremental Copy Blob	宛先 BLOB (既存)	BLOB (b)	オブジェクト (o)	書き込み (w)

アカウント SAS の詳細については、「アカウント SAS の 作成」を参照してください。

共有キー

この操作では Incremental Copy Blob 、 共有キーの承認がサポートされています。 アカウント キーを使用した承認は、セキュリティが低く、ほとんどのシナリオでは推奨されません。

可能な場合は、ストレージ アカウントの共有キーの承認を禁止することをお勧めします。 詳細については、「共有キーによる承認の防止」を参照してください。

注釈

増分コピーのコピー先が存在しないか、同じソース 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 操作のタイムアウトの設定