Append Block操作は既存の追加ブロブの末尾に新しいデータブロックをコミットします。
Append Block操作は、ブロブがx-ms-blob-typeをAppendBlobに設定して作成された場合にのみ許可されます。
Append Block バージョン2015-02-21以降のみサポートされています。
リクエスト
Append Block 要求は次のように構築できます。 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 パラメーター
| パラメーター | Description |
|---|---|
timeout |
Optional.
timeout パラメーターは秒単位で表されます。 詳細については、「 Azure Blob Storage Operationsのタイムアウト設定」をご覧ください。 |
要求ヘッダー
次の表では、必須の要求ヘッダーと省略可能な要求ヘッダーについて説明します。
| リクエストヘッダー | Description |
|---|---|
Authorization |
必須。 承認スキーム、アカウント名、署名を指定します。 詳細は 「Azure Storageへのリクエストを承認」 をご覧ください。 |
Date または x-ms-date |
必須。 要求の世界協定時刻 (UTC) を指定します。 詳細については、「Azure Storageへの要求を承認する」を参照してください。 |
x-ms-version |
許可されたすべての要求に必要です。 この要求に使用する操作のバージョンを指定します。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。 |
Content-Length |
必須。 ブロック内容の長さ(バイト単位)です。 バージョン2022-11-02以降では、ブロックサイズが100 MiB(プレビュー)以下でなければなりません。 古いバージョンの制限については 備考 セクションを参照してください。 長さが提供されない場合、操作は失敗し、ステータスコードは411(必要長さ)となります。 |
Content-MD5 |
Optional. ブロック内容のMD5ハッシュ。 このハッシュは、輸送中のブロックの整合性を検証するために使われます。 このヘッダーが指定されると、ストレージサービスは到達したコンテンツのハッシュ値をこのヘッダー値と比較します。 このMD5ハッシュはブロブと一緒に保存されていないことに注意してください。 2つのハッシュが一致しない場合、エラーコード400(Bad Request)で操作が失敗します。 |
x-ms-content-crc64 |
Optional. 追加ブロック内容のCRC64ハッシュ。 このハッシュは輸送中のアペンドブロックの整合性を検証するために使われます。 このヘッダーが指定されると、ストレージサービスは到達したコンテンツのハッシュ値をこのヘッダー値と比較します。 このCRC64ハッシュはブロブと一緒に保存されていないことに注意してください。 2つのハッシュが一致しない場合、エラーコード400(Bad Request)で操作が失敗します。 Content-MD5ヘッダーとx-ms-content-crc64ヘッダーの両方が存在する場合、リクエストはエラーコード400で失敗します。このヘッダーは2019-02-02以降のバージョンでサポートされています。 |
x-ms-encryption-scope |
Optional. 要求の内容の暗号化に使用する暗号化スコープを示します。 このヘッダーは2019-02-02以降のバージョンでサポートされています。 |
x-ms-lease-id:<ID> |
BLOBにアクティブなリースがある場合は必要となります。 アクティブなリースを持つ BLOB でこの操作を実行するには、このヘッダーの有効なリース ID を指定します。 |
x-ms-client-request-id |
Optional. クライアントが生成した不透明な値に、ログの構成時にログに記録される 1 キビバイト (KiB) の文字制限を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けることを強くお勧めします。 詳細については、「 Azure Blob Storage の監視」を参照してください。 |
x-ms-blob-condition-maxsize |
オプションの条件付きヘッダー。 追加ブロブに許可される最大長さ(バイト数)を指定します。
Append Block操作でブロブがその制限を超えるか、ブロブのサイズがすでにこのヘッダーで指定された値を上回っている場合、リクエストはエラーコード412(前提条件失敗)で失敗します。 |
x-ms-blob-condition-appendpos |
オプションの条件付きヘッダーは、 Append Block 操作専用です。 比較するバイトオフセットを示す数字です。
Append Block は付加位置がこの数値に等しい場合にのみ成功します。 もしそうでなければ、リクエストはエラーコード412(前提条件失敗)で失敗します。 |
この操作は、指定された条件が満たされた場合にのみAPIが成功するように、追加の条件付けヘッダーの使用をサポートします。 詳細については、「 Azure Blob Storage operationsの条件付けヘッダーの指定」をご覧ください。
リクエストヘッダー(顧客提供の暗号鍵)
バージョン2019-02-02以降は、顧客提供の鍵でブロブを暗号化するリクエストで以下のヘッダーを指定できるようになりました。 顧客提供の鍵(および対応するヘッダーセット)による暗号化は任意です。
| リクエストヘッダー | Description |
|---|---|
x-ms-encryption-key |
必須。 Base64でエンコードされたAES-256暗号鍵。 |
x-ms-encryption-key-sha256 |
必須。 Base64で符号化されたSHA256ハッシュの暗号鍵。 |
x-ms-encryption-algorithm: AES256 |
必須。 暗号化に使用するアルゴリズムを指定します。 このヘッダーの値は AES256でなければなりません。 |
リクエストヘッダー(構造化ボディ)
バージョン2025-01-05以降、構造化ボディフォーマットを活用するために、リクエストで以下のヘッダーを指定することができます。
| リクエストヘッダー | Description |
|---|---|
Content-Length |
必須。 は符号化された要求の長さでなければなりません(ブロック内容の長さだけでなく)。 ヘッダーの値がエンコードされたリクエストの期待長さと一致しない場合、エラーコード400(Bad Request)で操作が失敗します。 |
x-ms-structured-body |
必須。 メッセージ形式が構造化されている場合は必ず含めなければなりません。 このヘッダーの値は、メッセージスキーマのバージョンとプロパティを含みます。 現在サポートされているのは XSM/1.0; properties=crc64のみで、これはリクエストがエンコードされたメッセージ内でcrc64チェックサムセグメントを使用していることを示しています。 値がこれに合わない場合、エラーコード400(Bad Request)で操作が失敗します。 リクエストに提供された内容が特定のセグメントのチェックサムと一致しない場合も失敗します。 |
x-ms-structured-content-length |
必須。 メッセージ形式が構造化されている場合は必ず含めなければなりません。 このヘッダーの値はブロック内容の長さであり、メッセージエンコーディングのため常に Content-Length ヘッダーの値より小さいです。 ヘッダーの値がリクエストで提供されたブロック内容の長さと一致しない場合、エラーコード400(Bad Request)で操作が失敗します。 |
リクエストの本文
リクエストボディにはブロックの内容が含まれています。
サンプルリクエスト
Request Syntax:
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock HTTP/1.1
Request Headers:
x-ms-version: 2015-02-21
x-ms-date: <date>
x-ms-blob-condition-appendpos: 2097152
x-ms-blob-condition-maxsize: 4194304
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=
Content-Length: 1048
If-Match: "0x8CB172A360EC34B"
[応答]
応答には、HTTP 状態コードと一連の応答ヘッダーが含まれます。
状態コード
操作が成功すると、状態コード 201 (Created) が返されます。
状態コードの詳細については、「状態コードとエラー コードを参照してください。
応答ヘッダー
この操作の応答には、次のヘッダーが含まれます。 応答には、追加の標準 HTTP ヘッダーを含めることもできます。 すべての標準ヘッダーは、 HTTP/1.1 プロトコル仕様に準拠しています。
| 応答ヘッダー | Description |
|---|---|
ETag |
ETagには引用符で値が付けられています。 クライアントはIf-Matchリクエストヘッダーを使って条件付きPUT操作を行うことができます。 |
Last-Modified |
ブロブが最後に修正された日付と時間。 日付形式は RFC 1123 に従います。 詳細については、「 ヘッダーにおける日付-時刻の値を表現する」を参照してください。 ブロブに対する書き込み操作(メタデータやプロパティの更新を含む)は、ブロブの最後に修正された時間を変更します。 |
Content-MD5 |
このヘッダーは、クライアントがメッセージ コンテンツの整合性を確認できるように返されます。 このヘッダーの値はBlob Storageによって計算されます。 リクエストヘッダーで指定されている値が必ずしも同じではありません。 バージョン2019-02-02以降では、このヘッダーはリクエストにこのヘッダーがある場合のみ返されます。 |
x-ms-content-crc64 |
バージョン2019-02-02以降では、このヘッダーが返され、クライアントがメッセージの内容の整合性をチェックできます。 このヘッダーの値はBlob Storageによって計算されます。 リクエストヘッダーで指定されている値が必ずしも同じではありません。 このヘッダーは、 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以降です。 このヘッダーは、リクエストが暗号化スコープを使用した場合に返されます。 クライアントは暗号化スコープを使ってリクエストの内容が正常に暗号化されていることを確認します。 |
x-ms-client-request-id |
このヘッダーを使用して、要求と対応する応答のトラブルシューティングを行うことができます。 このヘッダーの値は、リクエスト内に存在する場合の x-ms-client-request-id ヘッダーの値と等しいです。 値は最大 1024 文字の ASCII 文字です。 リクエストに x-ms-client-request-id ヘッダーがなければ、このヘッダーはレスポンスにも存在しません。 |
x-ms-structured-body |
リクエストが構造化ボディリクエストとして処理された場合は返却されます。 このヘッダーの値は、現在 XSM/1.0; properties=crc64される必要がありますリクエストで送信される値と等しいです。 |
サンプル応答
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
Authorization
Azure Storage でデータ アクセス操作を呼び出す場合は、承認が必要です。 次の説明に従って、Append Block 操作を承認できます。
Important
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 へのアクセスを承認する」を参照してください。
Permissions
Microsoft Entra ユーザー、グループ、マネージド ID、またはサービス プリンシパルが Append Block 操作を呼び出すために必要な RBAC アクションと、このアクションを含む最小特権の組み込み Azure RBAC ロールを次に示します。
- Azure RBAC action:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action または Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- 最小特権の組み込みロール:Storage Blob Data Contributor
Azure RBAC を使用したロールの割り当ての詳細については、「 BLOB データにアクセスするための Azure ロールの割り当て」を参照してください。
注釈
Append Block 既存の追加ブロブの末尾にブロックをアップロードします。 サーバー上で通話が成功すると、データブロックは即座に利用可能になります。 1つの付録ブロブに対して最大50,000個のアペンドが許可されています。 各ブロックは異なるサイズを持つことができます。
以下の表は、サービスバージョンごとに許容される最大ブロックおよびブロブサイズを示しています。
| サービスのバージョン | 最大ブロックサイズ( Append Block経由) |
最大ブロブサイズ |
|---|---|---|
| バージョン 2022-11-02以降 | 100 MiB(プレビュー) | 約4.75 TiB(50,000ブロック×100 MiB) |
| 2022年11月2日以前のバージョン | 4 MiB | 約195ギビバイト(GiB)(4 MiB×50,000ブロック) |
Append Block 成功するのは、ブロブがすでに存在している場合のみです。
Append Blockを使ってアップロードしたブロブはブロックIDを公開しません。 追加ブロックリストを付けるブロック リスト を呼び出すことはできません。 そうするとエラーが発生します。
リクエストに対して、以下のオプションの条件付きヘッダーを指定することができます:
x-ms-blob-condition-appendpos: このヘッダーはクライアントがブロックを追加する予定のバイトオフセットに設定できます。 リクエストは、現在のオフセットがクライアントの指定と一致している場合にのみ成功します。 そうでなければ、リクエストはエラーコード412(前提条件失敗)で失敗します。単一のライターを使用するクライアントは、このヘッダーを使ってネットワーク障害があっても
Append Block操作が成功したかどうかを判断できます。x-ms-blob-condition-maxsizeクライアントはこのヘッダーを使って、追加操作によってブロブサイズが予想される最大バイトサイズを超えないようにできます。 条件が失敗した場合、リクエストはエラーコード412(前提条件失敗)で失敗します。
許可サイズを超えるブロックをアップロードしようとすると、サービスはエラーコード413(Request Entity Too Large)を返します。 サービスはまた、応答のエラーに関する追加情報も返します。これには、許容される最大ブロックサイズ(バイト単位)が含まれます。 5万ブロック以上アップロードしようとすると、サービスはエラーコード409(矛盾)を返します。
ブロブにアクティブなリースがある場合、クライアントはブロックを書き込むためにリクエストに有効なリースIDを指定しなければなりません。 クライアントがリースIDを指定しなかったり、無効なリースIDを指定した場合、Blob Storageはエラーコード412(Precondition Failed)を返します。 クライアントがリースIDを指定しても、ブロブにアクティブなリースがない場合、Blob Storageはエラーコード412も返します。
既存のブロックブロブやページブロックで Append Block を呼び出すと、サービスはコンフリクトエラーを返します。 存在しないブロブに対して Append Block を呼び出すと、サービスもエラーを返します。
重複や遅延の付加を避ける
シングルライターのシナリオでは、クライアントは *x-ms-blob-condition-appendpos 条件ヘッダーを使って現在のオフセットを確認することで重複の付加や書き込み遅延を回避できます。 クライアントはIf-Matchを利用して条件付きでETag確認することで、重複や遅延を回避できます。
複数ライターのシナリオでは、各クライアントが条件付きヘッダーを使用できますが、パフォーマンス面で最適とは言えないかもしれません。 最も高い同時付加スループットを得るために、アプリケーション層では冗長な付加および遅延付加処理を処理すべきです。 例えば、アプリは追加されるデータにエポックやシーケンス番号を追加できます。
Billing
価格要求は、Blob Storage REST API を介して直接、または Azure Storage クライアント ライブラリから、Blob Storage API を使用するクライアントから発信できます。 これらの要求では、トランザクションごとに料金が発生します。 トランザクションの種類は、アカウントの請求方法に影響します。 たとえば、読み取りトランザクションは、書き込みトランザクションとは異なる請求カテゴリに発生します。 次の表は、ストレージ アカウントの種類に基づく Append Block 要求の課金カテゴリを示しています。
| Operation | ストレージ アカウントの種類 | 請求カテゴリ |
|---|---|---|
| ブロックの追加 | Premium ブロック BLOB 標準汎用 バージョン 2 標準汎用バージョン1 |
書き込み操作 |
Append Blockはオブジェクトレベルの階層化をサポートしておらず、デフォルトのアカウントアクセス層設定からアクセス層を推定し、それに応じて請求されます。 デフォルトのアカウントティア設定について詳しくは、「 Blob Data のアクセス層 - Azure Storage」をご覧ください。
指定した課金カテゴリの価格については、「 Azure Blob Storage の価格」を参照してください。