Append Block From URL

  • [アーティクル]

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

この操作はAppend Block From URL、 を にAppendBlob設定して BLOB が作成x-ms-blob-typeされた場合にのみ許可されます。 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 省略可能。 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/myblob
https://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 (無効な要求) で失敗します。
x-ms-source-content-crc64 省略可能。 URI からの追加ブロック コンテンツの CRC64 ハッシュ。 このハッシュは、URI からのデータの転送中に追加ブロックの整合性を確認するために使用されます。 このヘッダーを指定すると、ストレージ サービスはコピーソースから到着したコンテンツのハッシュをこのヘッダー値と比較します。

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

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

ヘッダーと x-ms-source-content-crc64 ヘッダーの両方x-ms-source-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 From URL BLOB がこの制限を超える場合、または BLOB サイズがこのヘッダーで指定された値を既に超えている場合、要求は 412 (前提条件に失敗) で失敗します。
x-ms-blob-condition-appendpos 操作にのみ使用されるオプションの Append Block from URL 条件付きヘッダー。 比較するバイト オフセットを示す数値。 Append Block from URL は、追加位置がこの数値と等しい場合にのみ成功します。 そうでない場合、要求は 412 で失敗します (前提条件は失敗しました)。

この操作では、指定した条件が満たされた場合にのみ 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"

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 は、このヘッダーの値を計算します。 要求ヘッダーで指定された値と必ずしも同じではありません。

このヘッダーは、ヘッダーが要求に 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の詳細を参照してください。

重要

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 service に対する要求を認可するために使用できます。

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

アクセス許可

Microsoft Entraユーザー、グループ、マネージド ID、またはサービス プリンシパルが操作を呼び出Append Block From URLすために必要な RBAC アクションと、このアクションを含む最小特権の組み込み Azure RBAC ロールを次に示します。

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

注釈

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

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

サービスのバージョン 最大ブロック サイズ (経由 Append Block From URL) 最大 BLOB サイズ
バージョン 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 に対して ブロック リストの取得 を呼び出すことはできません。 これを行うと、エラーが発生します。

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

  • 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 (見つかりません) を返します。

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

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

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

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

請求

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

操作 ストレージ アカウントの種類 課金カテゴリ
URL からのブロックの追加 (宛先アカウント1) Premium ブロック BLOB
Standard 汎用 v2
Standard 汎用 v1		 書き込み操作
URL からのブロックの追加 (ソース アカウント2) Premium ブロック BLOB
Standard 汎用 v2
Standard 汎用 v1		 操作を読み取ります。

1宛先アカウントは、書き込みを開始する 1 つのトランザクションに対して課金されます。
2ソース アカウントでは、ソースへの読み取り要求ごとに 1 つのトランザクションが発生します。