Append Block

  • [アーティクル]

この操作により Append Block 、既存の追加 BLOB の末尾に新しいデータ ブロックがコミットされます。

この操作はAppend Block、 を にAppendBlob設定して BLOB が作成x-ms-blob-typeされた場合にのみ許可されます。 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 パラメーター

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

要求ヘッダー

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

要求ヘッダー 説明
Authorization 必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「 Azure Storage への要求を承認する 」を参照してください。
Date または x-ms-date 必須。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
x-ms-version すべての承認された要求に必要です。 この要求に使用する操作のバージョンを指定します。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
Content-Length 必須。 ブロックのコンテンツのサイズ (バイト単位)。 ブロック サイズは、バージョン 2022-11-02 以降では 100 MiB (プレビュー) 以下である必要があります。 以前のバージョンの制限については、「 解説 」セクションを参照してください。

サイズが指定されない場合、操作はステータス コード 411 (Length Required) で失敗します。
Content-MD5 省略可能。 ブロックのコンテンツの MD5 ハッシュ。 このハッシュは、転送時のブロックの整合性を確認するために使用します。 このヘッダーを指定すると、ストレージ サービスによって、到達したコンテンツのハッシュと、このヘッダー値が比較されます。

この MD5 ハッシュは BLOB と共に格納されていないことに注意してください。

2 つのハッシュが一致しない場合、操作はエラー コード 400 (Bad Request) で失敗します。
x-ms-content-crc64 省略可能。 追加ブロック コンテンツの CRC64 ハッシュ。 このハッシュは、トランスポート中に追加ブロックの整合性を確認するために使用されます。 このヘッダーを指定すると、ストレージ サービスによって、到達したコンテンツのハッシュと、このヘッダー値が比較されます。

この CRC64 ハッシュは BLOB と共に格納されていないことに注意してください。

2 つのハッシュが一致しない場合、操作はエラー コード 400 (Bad Request) で失敗します。

ヘッダーと x-ms-content-crc64 ヘッダーの両方Content-MD5が存在する場合、要求はエラー コード 400 で失敗します。

このヘッダーは、バージョン 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) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「Azure Blob Storageの監視」を参照してください。
x-ms-blob-condition-maxsize オプションの条件付きヘッダー。 追加 BLOB に許可される最大長をバイト単位で指定します。 操作によって Append Block BLOB がこの制限を超えた場合、または BLOB サイズがこのヘッダーで指定された値を既に超えている場合、要求はエラー コード 412 (前提条件失敗) で失敗します。
x-ms-blob-condition-appendpos 操作にのみ使用されるオプションの Append Block 条件付きヘッダー。 数値は、比較するバイト オフセットを示します。 Append Block は、追加位置がこの数値と等しい場合にのみ成功します。 そうでない場合、要求はエラー コード 412 (前提条件に失敗) で失敗します。

この操作では、指定した条件が満たされた場合にのみ API が成功するように、追加の条件付きヘッダーの使用がサポートされています。 詳細については、「Azure 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: 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"

Response

応答には、HTTP 状態コードおよび一連の応答ヘッダーが含まれています。

status code

操作が正常に終了すると、状態コード 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 によって計算されます。 要求ヘッダーで指定された値と必ずしも同じではありません。

このヘッダーは、ヘッダーが要求に 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 場合、ヘッダーの値と同じです。 この値は、表示可能な ASCII 文字が最大 1024 文字です。 ヘッダーが x-ms-client-request-id 要求に存在しない場合、このヘッダーは応答に存在しません。

応答のサンプル

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 説明するように承認できます。

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

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

注釈

Append Block は、既存の追加 BLOB の末尾にブロックをアップロードします。 データのブロックは、呼び出しがサーバーで成功した直後に使用できます。 追加 BLOB ごとに最大 50,000 個の追加が許可されます。 各ブロックのサイズは異なる場合があります。

次の表では、許可されるブロックと BLOB の最大サイズをサービス のバージョン別に示します。

サービスのバージョン 最大ブロック サイズ (経由 Append Block) 最大 BLOB サイズ
バージョン 2022-11-02 以降 100 MiB (プレビュー) 約 4.75 TiB (100 MiB × 50,000 ブロック)
2022-11-02 より前のバージョン 4 MiB 約 195 ギビバイト (GiB) (4 MiB × 50,000 ブロック)

Append Block は、BLOB が既に存在する場合にのみ成功します。

を使用 Append Block してアップロードされた BLOB は、ブロック ID を公開しません。 追加 BLOB に対して Get Block List を呼び出すことはできません。 これにより、エラーが発生します。

要求では、次の省略可能な条件付きヘッダーを指定できます。

  • x-ms-blob-condition-appendpos: このヘッダーは、クライアントがブロックを追加することを想定しているバイト オフセットに設定できます。 要求は、現在のオフセットがクライアントによって指定されたオフセットと一致する場合にのみ成功します。 それ以外の場合、要求はエラー コード 412 (前提条件に失敗しました) で失敗します。

    1 つのライターを使用するクライアントは、このヘッダーを使用して、ネットワーク障害が発生しても操作が成功したかどうかを Append Block 判断できます。

  • x-ms-blob-condition-maxsize: クライアントはこのヘッダーを使用して、追加操作によって BLOB サイズが予想される最大サイズ (バイト単位) を超えないようにすることができます。 条件が失敗した場合、要求はエラー コード 412 (前提条件に失敗しました) で失敗します。

許可されたサイズより大きいブロックをアップロードしようとすると、サービスはエラー コード 413 (要求エンティティが大きすぎます) を返します。 許容される最大ブロック サイズ (バイト単位) など、エラーに関する追加情報も応答で返されます。 50,000 ブロックを超えるブロックをアップロードしようとすると、サービスはエラー コード 409 (競合) を返します。

BLOB にアクティブなリースが存在する場合、クライアントが BLOB にブロックを書き込むには、要求に有効なリース ID を指定する必要があります。 クライアントがリース ID を指定しない場合、または無効なリース ID を指定した場合、Blob Storage はエラー コード 412 (前提条件に失敗しました) を返します。 クライアントがリース ID を指定していても、BLOB にアクティブなリースがない場合、Blob Storage はエラー コード 412 も返します。

既存のブロック BLOB またはページ BLOB で を呼び出 Append Block すと、サービスから競合エラーが返されます。 存在しない BLOB で を呼び出 Append Block すと、サービスもエラーを返します。

重複または遅延した追加を回避する

1 つのライター シナリオでは、条件付きヘッダーを使用して*x-ms-blob-condition-appendpos現在のオフセットをチェックすることで、クライアントは重複する追加や遅延書き込みを回避できます。 クライアントでは、 を使用If-Matchして 条件付きで をチェックETagすることで、重複や遅延を回避することもできます。

複数のライター シナリオでは、各クライアントで条件付きヘッダーを使用できますが、これはパフォーマンスに最適ではない可能性があります。 同時実行の追加スループットが最も高い場合は、アプリケーションレイヤーで冗長な追加と遅延付加を処理する必要があります。 たとえば、アプリケーションでは、追加するデータにエポックまたはシーケンス番号を追加できます。

請求

価格要求は、Blob Storage REST API を介して直接、または Azure Storage クライアント ライブラリを介して Blob Storage API を使用するクライアントから送信できます。 これらの要求では、トランザクションあたりの料金が発生します。 トランザクションの種類は、アカウントの課金方法に影響します。 たとえば、読み取りトランザクションは、書き込みトランザクションとは異なる課金カテゴリに計上されます。 次の表は、ストレージ アカウントの種類に基づく要求の課金カテゴリ Append Block を示しています。

操作 ストレージ アカウントの種類 課金カテゴリ
Append Block Premium ブロック BLOB
Standard 汎用 v2
Standard 汎用 v1		 書き込み操作

指定した課金カテゴリの価格については、「Azure Blob Storage価格」を参照してください。