Append Block From URL操作では、新しいデータ ブロックが既存の追加 BLOB の末尾にコミットされます。
Append Block From URL操作は、BLOB が x-ms-blob-type を AppendBlob に設定して作成された場合にのみ許可されます。
Append Block From URL は、バージョン 2018-11-09 バージョン以降でのみサポートされています。
リクエスト
Append Block From URL 要求は次のように構築できます。 HTTPS をお勧めします。 myaccount
| PUT メソッド要求 URI | HTTP バージョン |
|---|---|
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock |
HTTP/1.1 (英語) |
エミュレートされたストレージ サービスに対して要求を行う場合は、エミュレーターのホスト名と Azure Blob Storage ポートを 127.0.0.1:10000 として指定し、その後にエミュレートされたストレージ アカウント名を指定します。
| PUT メソッド要求 URI | HTTP バージョン |
|---|---|
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock |
HTTP/1.1 (英語) |
詳細については、「ローカルの Azure Storage 開発に Azurite エミュレーターを使用する」を参照してください。
URI パラメーター
| パラメーター | 説明 |
|---|---|
timeout |
任意。 タイムアウト パラメーターは秒単位で表されます。 詳細については、「 Blob Storage 操作のタイムアウトの設定」を参照してください。 |
要求ヘッダー
次の表では、必須の要求ヘッダーと省略可能な要求ヘッダーについて説明します。
| リクエストヘッダー | 説明 |
|---|---|
Authorization |
必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storage への要求を承認する」を参照してください。 |
Date または x-ms-date |
必須。 要求の世界協定時刻 (UTC) を指定します。 詳細については、「Azure Storageへの要求を承認する」を参照してください。 |
x-ms-version |
すべての承認された要求に必要です。 この要求に使用する操作のバージョンを指定します。 詳細については、Azure Storage サービス のバージョン管理のに関するページを参照してください。 |
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/myblobhttps://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 ID でサポートされています。 このヘッダーは、バージョン 2020-10-02 以降でサポートされています。 |
x-ms-source-range |
任意。 指定した範囲内のソース URL 内の BLOB のバイトのみをアップロードします。 これが指定されていない場合、ソース BLOB のコンテンツ全体が 1 つの追加ブロックとしてアップロードされます。 詳細については、「 Blob Storage 操作の範囲ヘッダーの指定 」を参照してください。 |
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-encryption-scope |
任意。 ソース コンテンツの暗号化に使用する暗号化スコープを示します。 このヘッダーは、バージョン 2019-02-02 以降でサポートされています。 |
x-ms-lease-id:<ID> |
BLOBにアクティブなリースがある場合は必要となります。 アクティブなリースを持つ BLOB でこの操作を実行するには、このヘッダーの有効なリース ID を指定します。 |
x-ms-client-request-id |
任意。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を持つクライアント生成の不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティと、サーバーが受信する要求を関連付けすることを強くお勧めします。 詳細については、「Monitor Azure Blob Storage」を参照してください。 |
x-ms-blob-condition-maxsize |
オプションの条件付きヘッダー。 追加 BLOB に許可される最大長 (バイト単位)。
Append Block From URL操作によって BLOB がその制限を超えた場合、または BLOB のサイズが既にこのヘッダーで指定された値より大きい場合、要求は 412 (Precondition Failed) で失敗します。 |
x-ms-blob-condition-appendpos |
Append Block from URL操作にのみ使用されるオプションの条件付きヘッダー。 比較するバイト オフセットを示す数値。
Append Block from URL は、追加位置がこの数値と等しい場合にのみ成功します。 そうでない場合、要求は 412 (前提条件に失敗しました) で失敗します。 |
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 以降で使用できます。 |
この操作では、指定した条件が満たされた場合にのみ API が成功するように、追加の条件付きヘッダーの使用がサポートされています。 詳細については、「 Blob Storage 操作の条件付きヘッダーの指定」を参照してください。
要求ヘッダー (顧客提供の暗号化キー)
バージョン 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=appendblock HTTP/1.1
Request Headers:
x-ms-version: 2018-11-09
x-ms-date: <date>
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152
x-ms-blob-condition-maxsize: 4194304
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=
Content-Length: 0
If-Match: "0x8CB172A360EC34B"
[応答]
応答には、HTTP 状態コードと一連の応答ヘッダーが含まれます。
状態コード
操作が成功すると、状態コード 201 (Created) が返されます。 状態コードの詳細については、「状態コードとエラー コードを参照してください。
応答ヘッダー
この操作の応答には、次のヘッダーが含まれます。 応答には、追加の標準 HTTP ヘッダーを含めることもできます。 すべての標準ヘッダーは、HTTP/1.1 プロトコル仕様に準拠しています。
| 応答ヘッダー | 説明 |
|---|---|
Etag |
ETagには引用符で囲まれた値が含まれています。 クライアントは、この値を使用して、PUT 要求ヘッダーを使用して条件付きIf-Match操作を実行します。 |
Last-Modified |
BLOB が最後に変更された日付/時刻。 日付形式は RFC 1123 に従います。 詳細については、「ヘッダーの日時値の表現」を参照してください。 BLOB に対する書き込み操作 (BLOB のメタデータまたはプロパティの更新を含む) により、BLOB の最終変更時刻が変更されます。 |
Content-MD5 |
このヘッダーは、クライアントがメッセージ コンテンツの整合性を確認できるように返されます。 Blob Storage は、このヘッダーの値を計算します。 これは、要求ヘッダーで指定された値と同じである必要はありません。 バージョン 2019-02-02 以降の場合、このヘッダーは、要求にこのヘッダーがある場合にのみ返されます。 |
x-ms-content-crc64 |
バージョン 2019-02-02 以降の場合。 このヘッダーは、クライアントがメッセージ コンテンツの整合性を確認できるように返されます。 Blob Storage は、このヘッダーの値を計算します。 これは、要求ヘッダーで指定された値と同じである必要はありません。 このヘッダーは、 x-ms-source-content-md5 ヘッダーが要求に存在しない場合に返されます。 |
x-ms-request-id |
このヘッダーは、作成された要求を一意に識別し、要求のトラブルシューティングに使用できます。 |
x-ms-version |
要求の実行に使用された Blob Storage のバージョンを示します。 このヘッダーは、バージョン 2009-09-19 以降に対して行われた要求に対して返されます。 |
Date |
応答が開始された時刻を示すサービスによって生成された UTC 日付/時刻値。 |
x-ms-blob-append-offset |
この応答ヘッダーは、追加操作の場合にのみ返されます。 ブロックがコミットされたオフセットをバイト単位で返します。 |
x-ms-blob-committed-block-count |
BLOB に存在するコミット済みブロックの数。 これを使用して、実行できる追加の数を制御できます。 |
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 以降。 このヘッダーは、要求が暗号化スコープを使用した場合に返されます。 その後、クライアントは、暗号化スコープを使用して、要求の内容が正常に暗号化されていることを確認できます。 |
サンプル応答
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
x-ms-content-crc64: 77uWZTolTHU
Date: <date>
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-blob-append-offset: 2097152
x-ms-blob-committed–block-count: 1000
認証
Azure Storage でデータ アクセス操作を呼び出す場合は、承認が必要です。 次の説明に従って、Append Block From URL 操作を承認できます。
このセクションの認証の詳細は、コピー先に適用されます。 コピー元の承認の詳細については、要求ヘッダー 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 を指定できます。 セキュリティ プリンシパルは、Microsoft Entra ID によって認証され、OAuth 2.0 トークンを返します。 その後、そのトークンを、Blob service に対する要求を認可するために使用できます。
Microsoft Entra ID を使用した承認の詳細については、「Microsoft Entra IDを使用して BLOB へのアクセスを承認する」を参照してください。
権限
Microsoft Entra ユーザー、グループ、マネージド ID、またはサービス プリンシパルが Append Block From URL 操作を呼び出すために必要な RBAC アクションと、このアクションを含む最小特権の組み込み Azure RBAC ロールを次に示します。
- Azure RBAC アクション:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action または Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- 最小特権組み込みロール: ストレージ BLOB データ共同作成者
Azure RBAC を使用したロールの割り当ての詳細については、「BLOB データにアクセスするための Azure ロールの割り当て」を参照してください。
注釈
Append Block From URL 既存の追加 BLOB の末尾にブロックをアップロードします。 データのブロックは、サーバーで呼び出しが成功するとすぐに使用できます。 追加ブロブごとに最大 50,000 回の追加が許可されます。 各ブロックのサイズは異なる場合があります。
次の表では、サービスのバージョンごとに許可されるブロックと BLOB の最大サイズについて説明します。
| サービスのバージョン | 最大ブロックサイズ( Append Block From URL経由) |
最大ブロブ サイズ |
|---|---|---|
| バージョン 2022-11-02 以降 | 100 MiB (プレビュー) | 約 4.75 TiB (100 MiB × 50,000 ブロック) |
| 2022-11-02 より前のバージョン | 4 MiB | 約 195 ギビバイト (GiB) (4 MiB × 50,000 ブロック) |
バージョン 2020-10-02 以降では、コピー操作のソースに対して Microsoft Entra ID 認証がサポートされています。
Append Block From URL BLOB が既に存在する場合にのみ成功します。
Append Block From URL を使用してアップロードされた BLOB はブロック ID を公開しないため、追加 BLOB に対して Get Block List を呼び出すことはできません。 これを行うとエラーが発生します。
要求には、次の省略可能な条件付きヘッダーを指定できます。
x-ms-blob-condition-appendpos: このヘッダーは、クライアントがブロックを追加することを期待するバイト オフセットに設定できます。 要求は、現在のオフセットがクライアントによって指定されたものと一致する場合にのみ成功します。 それ以外の場合、要求はエラー コード 412 (前提条件に失敗しました) で失敗します。1 つのライターを使用するクライアントは、このヘッダーを使用して、ネットワーク障害にもかかわらず
Append Block From URL操作が成功したかどうかを判断できます。x-ms-blob-condition-maxsize: クライアントは、このヘッダーを使用して、追加操作によって BLOB サイズが予想される最大サイズ (バイト単位) を超えないようにすることができます。 条件が失敗した場合、要求はエラー コード 412 (前提条件に失敗しました) で失敗します。
許可されたサイズより大きいブロックをアップロードしようとすると、サービスは HTTP エラーコード 413 (リクエストエンティティが大きすぎます) を返します。 また、このサービスは、許容される最大ブロック・サイズ (バイト単位) など、レスポンスのエラーに関する追加情報も返します。 50,000 を超えるブロックをアップロードしようとすると、サービスはエラー コード 409 (競合) を返します。
BLOB にアクティブなリースがある場合、クライアントは BLOB にブロックを書き込むために、要求に有効なリース ID を指定する必要があります。 クライアントがリース ID を指定しない場合、または無効なリース ID を指定した場合、Blob Storage はエラー コード 412 (前提条件に失敗しました) を返します。 クライアントがリース ID を指定しても、BLOB にアクティブなリースがない場合、サービスはエラー コード 412 を返します。
既存のブロック BLOB またはページ BLOB で Append Block From URL を呼び出すと、サービスはエラー コード 409 (競合) を返します。 存在しない BLOB で Append Block From URL を呼び出すと、サービスはエラー コード 404 (見つかりません) を返します。
重複または遅延した追加を避ける
シングル ライター シナリオでは、クライアントは x-ms-blob-condition-appendpos 条件付きヘッダーを使用して現在のオフセットを確認することで、重複する追加や遅延書き込みを回避できます。 クライアントは、ETagを使用してIf-Matchを条件付きでチェックすることで、重複や遅延を回避することもできます。
複数のライターのシナリオでは、各クライアントは条件付きヘッダーを使用できます。 これは、パフォーマンスに最適ではない可能性があります。 同時追加スループットを最大限に高めるには、アプリケーションはアプリケーション層で冗長な追加と遅延追加を処理する必要があります。 たとえば、アプリケーションでは、追加するデータにエポックやシーケンス番号を追加できます。
指定された課金カテゴリの価格については、Azure Blob Storage の価格
請求書
価格要求は、Blob Storage API を使用するクライアントから、Blob Storage REST API を介して直接、または Azure Storage クライアント ライブラリから送信できます。 これらの要求には、トランザクションあたりの料金が発生します。 トランザクションの種類は、アカウントの課金方法に影響します。 たとえば、読み取りトランザクションは、書き込みトランザクションとは異なる課金カテゴリに発生します。 次の表に、ストレージ アカウントの種類に基づく Append Block From URL 要求の課金カテゴリを示します。
| オペレーション | ストレージ アカウントの種類 | 課金カテゴリ |
|---|---|---|
| URL からブロックを追加 (宛先アカウント1) | Premium ブロック BLOB Standard 汎用 v2 Standard 汎用 v1 |
書き込み操作 |
| URL からブロックを追加 (ソース アカウント2) | Premium ブロック BLOB Standard 汎用 v2 Standard 汎用 v1 |
読み取り操作 |
1宛先アカウントは、書き込みを開始するための 1 つのトランザクションに対して課金されます。
2ソースアカウントでは、ソースへの読み取りリクエストごとに 1 つのトランザクションが発生します。