増分コピー BLOB

2025-06-11

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

リクエスト

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

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 に指定し、その後にエミュレートされたストレージアカウント名を指定します。また、この要求が増分コピー用であることを示すために、 comp クエリパラメーターを incrementalcopy に設定します。

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` 値が既存のコピー先 BLOB の `ETag` 値と一致する場合にのみ、BLOB をコピーします。宛先 BLOB の`ETag`が `If-Match` に指定された`ETag`と一致しない場合、Blob Storage は状態コード 412 (前提条件に失敗しました) を返します。
`If-None-Match`	任意。 `ETag`値、またはワイルドカード文字 (``)。この条件付きヘッダーに `ETag` 値を指定して BLOB をコピーするには、指定した BLOB の値がコピー先 BLOB の`ETag`値と一致しない場合にのみ`ETag`。操作を実行するワイルドカード文字 (``) を指定します (宛先 BLOB が存在しない場合のみ)。指定した条件が満たされていない場合、Blob Storage は状態コード 412 (前提条件に失敗) を返します。
`x-ms-copy-source:name`	必須。ソースページ BLOB スナップショットの名前を指定します。この値は、ページ BLOB スナップショットを指定する最大 2 キビバイト (KiB) の長さの URL です。値は、要求 URI に表示されるように URL エンコードする必要があります。ソース BLOB URI は、次の 2 つの方法のいずれかで承認できます。ソース BLOB URI はページ BLOB スナップショットを参照できますが、スナップショットのベース BLOB に作成された Shared Access Signature (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 文字の制限を持つ、クライアント生成の不透明な値を提供します。このヘッダーを使用して、クライアント側のアクティビティと、サーバーが受信する要求を関連付けすることを強くお勧めします。詳細については、「Monitor Azure Blob Storage」を参照してください。

リクエストの本文

なし。

[応答]

応答には、HTTP 状態コードと一連の応答ヘッダーが含まれます。

状態コード

操作が成功すると、状態コード 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 要求ヘッダーの詳細で説明されているように、個別に承認されます。

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 を指定できます。セキュリティプリンシパルは、OAuth 2.0 トークンを返すために Microsoft Entra ID によって認証されます。その後、トークンを使用して、BLOB サービスに対する要求を承認できます。

Microsoft Entra ID を使用した承認の詳細については、「Microsoft Entra IDを使用して BLOB へのアクセスを承認する」を参照してください。

権限

Microsoft Entra ユーザー、グループ、マネージド ID、またはサービスプリンシパルが 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 ロールの割り当て」を参照してください。

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

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

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

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

ユーザー委任 SAS

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

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

オペレーション	オブジェクトの種類	署名されたアクセス許可
増分コピー BLOB	宛先 BLOB (新規)	作成 (c) または書き込み (w)
増分コピー BLOB	宛先 BLOB (既存)	書き込み (w)

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

サービス SAS

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

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

オペレーション	オブジェクトの種類	署名されたアクセス許可
増分コピー BLOB	宛先 BLOB (新規)	作成 (c) または書き込み (w)
増分コピー BLOB	宛先 BLOB (既存)	書き込み (w)

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

アカウント SAS

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

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

オペレーション	オブジェクトの種類	署名されたサービス	署名されたリソースの種類	署名されたアクセス許可
増分コピー BLOB	宛先 BLOB (新規)	BLOB (b)	オブジェクト (o)	作成 (c) または書き込み (w)
増分コピー BLOB	宛先 BLOB (既存)	BLOB (b)	オブジェクト (o)	書き込み (w)

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

注釈

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

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

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

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

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

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

こちらも参照ください

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