Put Block List

Put Block List 操作は、BLOB を構成するブロック ID の一覧を指定することによって BLOB を書き込みます。 BLOB の一部として書き込まれるには、以前の Put Block 操作でブロックがサーバーに正常に書き込まれている必要があります。

を呼び出 Put Block List して BLOB を更新するには、変更されたブロックのみをアップロードし、新しいブロックと既存のブロックをまとめてコミットします。 これを行うには、コミットされたブロック リストからブロックをコミットするか、コミットされていないブロック リストからブロックをコミットするか、最後にアップロードされたバージョンのブロックのうちどれに属するかを指定します。

Request

要求は Put Block List 次のように構築できます。 HTTPS を使用することをお勧めします。 myaccount をストレージ アカウントの名前に置き換えます。

PUT メソッド要求 URI HTTP バージョン
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1

エミュレートされたストレージ サービス要求

エミュレートされたストレージ サービスに対して要求を行う場合は、エミュレーターのホスト名と BLOB サービス ポートを として 127.0.0.1:10000指定し、その後にエミュレートされたストレージ アカウント名を指定します。

PUT メソッド要求 URI HTTP バージョン
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=blocklist HTTP/1.1

ストレージ エミュレーターでは、最大 2 ギビバイト (GiB) の BLOB サイズのみがサポートされます。

詳細については、ローカルでの Azure Storage の開発に Azurite エミュレーターを使用する方法に関するページを参照してください。

URI パラメーター

次の追加パラメーターを要求 URI に指定できます。

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

要求ヘッダー

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

要求ヘッダー 説明
Authorization 必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
Date または x-ms-date 必須。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
x-ms-version すべての承認された要求に必要です。 この要求に使用する操作のバージョンを指定します。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
Content-Length 必須。 要求コンテンツの長さ (バイト単位)。 このヘッダーは、BLOB 自体ではなく、ブロックのリストのコンテンツ長を参照します。
Content-MD5 省略可能。 要求のコンテンツの MD5 ハッシュ。 このハッシュは転送時の要求コンテンツの整合性を確認するために使用します。 2 つのハッシュが一致しない場合、エラー コード 400 (無効な要求) で操作が失敗します。

このヘッダーは、BLOB 自体のコンテンツではなく、要求コンテンツに関連付けられます。
x-ms-content-crc64 省略可能。 要求コンテンツの CRC64 ハッシュ。 このハッシュは転送時の要求コンテンツの整合性を確認するために使用します。 2 つのハッシュが一致しない場合、エラー コード 400 (無効な要求) で操作が失敗します。

このヘッダーは、BLOB 自体のコンテンツではなく、要求コンテンツに関連付けられます。

Content-MD5 ヘッダーと x-ms-content-crc64 ヘッダーの両方が存在する場合、要求は 400 (無効な要求) で失敗します。

このヘッダーは、バージョン 2019-02-02 以降でサポートされています。
x-ms-blob-cache-control 省略可能。 BLOB のキャッシュ制御を設定します。 このプロパティを指定すると、BLOB と共に格納され、読み取り要求で返されます。

要求で プロパティが指定されていない場合、要求が成功した場合は BLOB に対してクリアされます。
x-ms-blob-content-type 省略可能。 BLOB のコンテンツの種類を設定します。 指定した場合、このプロパティは BLOB と共に格納され、読み取り要求で返されます。

コンテンツ タイプが指定されていない場合は、既定の種類 () application/octet-streamに設定されます。
x-ms-blob-content-encoding 省略可能。 BLOB のコンテンツのエンコードを設定します。 指定した場合、このプロパティは BLOB と共に格納され、読み取り要求で返されます。

要求で プロパティが指定されていない場合、要求が成功した場合は BLOB に対してクリアされます。
x-ms-blob-content-language 省略可能。 BLOB のコンテンツ言語を設定します。 指定した場合、このプロパティは BLOB と共に格納され、読み取り要求で返されます。

要求で プロパティが指定されていない場合、要求が成功した場合は BLOB に対してクリアされます。
x-ms-blob-content-md5 省略可能。 BLOB のコンテンツの MD5 ハッシュ。 このハッシュは検証されません。個々のブロックのハッシュは、各ブロックのアップロード時に検証されたためです。

Blob の取得操作は、Content-MD5 応答ヘッダーでこのヘッダーの値を返します。

このプロパティが要求と共に指定されていない場合、要求が成功した場合は BLOB に対してクリアされます。
x-ms-meta-name:value 省略可能。 BLOB に関連付けられているユーザー定義の名前と値のペア。

バージョン 2009-09-19 の時点で、メタデータ名は C# 識別子の名前付け規則に従っている必要があります。
x-ms-encryption-scope 省略可能。 BLOB の暗号化に使用する暗号化スコープを示します。 この値は、コミットされているすべてのブロックの暗号化に使用される暗号化スコープと一致する必要があります。 このヘッダーは、バージョン 2019-02-02 以降でサポートされています。
x-ms-tags 省略可能。 指定したクエリ文字列でエンコードされたタグを BLOB に設定します。 詳細については、「解説」セクション 参照してください。 バージョン 2019-12-12 以降でサポートされています。
x-ms-lease-id:<ID> BLOB にアクティブなリースが存在する場合は必須です。 アクティブなリースが存在する BLOB に対してこの操作を実行するには、このヘッダーに有効なリース ID を指定します。
x-ms-client-request-id 省略可能。 ストレージ分析ログの構成時に分析ログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「Storage Analytics ログについて」および「Azure ログ: ログを使用してストレージ要求を追跡する」を参照してください。
x-ms-blob-content-disposition 省略可能。 BLOB の Content-Disposition ヘッダーを設定します。 バージョン 2013-08-15 以降で使用できます。

ヘッダー フィールドは Content-Disposition 、応答ペイロードの処理方法に関する追加情報を伝達し、追加のメタデータをアタッチするために使用できます。 たとえば、 が に attachment設定されている場合、このヘッダーは、ユーザー エージェントが応答を表示せず、代わりに [名前を付けて保存] ダイアログを表示する必要があることを示します。

GET BLOB および Get Blob Properties 操作からの応答には、content-disposition ヘッダーが含まれます。
x-ms-access-tier 省略可能。 バージョン 2018-11-09 以降。 BLOB に設定する層を示します。 ブロック BLOB の場合、このヘッダーは、バージョン 2018-11-09 以降の BLOB ストレージまたは汎用 v2 アカウントでのみサポートされます。 ブロック BLOB 層の有効な値は、Hot、、CoolCold、および Archiveです。 : Cold レベルは現在プレビュー段階であり、バージョン 2021-12-02 以降でサポートされています。 ブロック BLOB の階層化の詳細については、「 ホット、クール、アーカイブのストレージ層」を参照してください。
x-ms-immutability-policy-until-date バージョン 2020-06-12 以降。 BLOB に設定する 保持期間 の日付を指定します。 これは、BLOB が変更または削除されないように保護できる日付です。 RFC1123 形式に従います。
x-ms-immutability-policy-mode バージョン 2020-06-12 以降。 BLOB に設定する不変ポリシー モードを指定します。 有効値は unlocked または locked です。 値は unlockedユーザーが保持期間 の日付を増減することでポリシーを変更できることを示します。 値は locked 、これらのアクションが禁止されていることを示します。
x-ms-legal-hold バージョン 2020-06-12 以降。 BLOB に設定する訴訟ホールドを指定します。 有効な値は、true および false です。

この操作では、条件ヘッダーを使用して、指定した条件を満たした場合にのみブロック一覧をコミットすることもできます。 詳細については、「 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 である必要があります。

要求本文

要求本文では、Blob Storage で要求されたブロックを確認する必要があるブロック リストを指定できます。 この方法では、BLOB 全体を再アップロードするのではなく、個々のブロックを挿入、置換、または削除することで、既存の BLOB を更新できます。 変更されたブロックまたはブロックをアップロードしたら、保持する既存のブロックと共に新しいブロックをコミットすることで、新しいバージョンの BLOB をコミットできます。

BLOB を更新する場合、ブロック ID をコミット後のブロック一覧から検索するか、コミット前のブロック一覧から検索するか、またはコミット前のブロック一覧を検索した後でコミット後のブロック一覧から検索するかを指定できます。 使用する方法を指定するには、要求本文内の適切な XML 要素内にあるブロック ID を次のように指定します。

  • Blob Storage が名前付きブロックの Committed コミット済みブロック リストのみを検索する必要があることを示すには、 要素内のブロック ID を指定します。 コミットされたブロックリストにブロックが見つからない場合、ブロックは BLOB の一部として書き込まれず、Blob Storage は状態コード 400 (Bad Request) を返します。

  • Blob Storage が名前付きブロックの Uncommitted コミットされていないブロック リストのみを検索する必要があることを示すには、 要素内のブロック ID を指定します。 コミットされていないブロック リストにブロックが見つからない場合、ブロックは BLOB の一部として書き込まれず、Blob Storage は状態コード 400 (無効な要求) を返します。

  • Blob Storage が最初にコミットされていないブロック リストを Latest 検索する必要があることを示すために、 要素内のブロック ID を指定します。 対象ブロックがコミット前のブロック一覧に見つかった場合、そのブロックのバージョンが最新であり、BLOB に書き込まれます。 コミットされていない一覧にブロックが見つからない場合、サービスはコミットされたブロック リストで名前付きブロックを検索し、そのブロックが見つかった場合はそのブロックを BLOB に書き込む必要があります。

このバージョンの の Put Block List 要求本文では、次の XML 形式が使用されます。

<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Committed>first-base64-encoded-block-id</Committed>  
  <Uncommitted>second-base64-encoded-block-id</Uncommitted>  
  <Latest>third-base64-encoded-block-id</Latest>  
  ...  
</BlockList>  
  

要求のサンプル

を示 Put Block Listすために、コミットする 3 つのブロックをアップロードしたとします。 次の例では、一覧の各ブロックの最新バージョンを使用するように指定して、新規 BLOB をコミットします。 各ブロックがコミット済みであるかどうかを意識する必要はありません。

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1  
  
Request Headers:  
x-ms-date: Wed, 31 Aug 2011 00:17:43 GMT  
x-ms-version: 2011-08-18  
Content-Type: text/plain; charset=UTF-8  
Authorization: SharedKey myaccount:DJ5QZSVONZ64vAhnN/wxcU+Pt5HQSLAiLITlAU76Lx8=  
Content-Length: 133  
  
Request Body:  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Latest>AAAAAA==</Latest>  
  <Latest>AQAAAA==</Latest>  
  <Latest>AZAAAA==</Latest>  
</BlockList>  
  

次に、BLOB を更新するとします。 新しい BLOB には、次の変更があります。

  • ID ANAAAA== の新規ブロック。 このブロックは、最初に Put Block の呼び出しでアップロードする必要があり、 の呼び出しまでコミットされていないブロック リストに Put Block List表示されます。

  • ID AZAAAA== のブロックの更新。 このブロックは、最初に Put Block の呼び出しでアップロードする必要があり、 の呼び出しまでコミットされていないブロック リストに Put Block List表示されます。

  • ID AAAAAA== のブロックの削除。 このブロックは への次の呼び出しには Put Block List含まれていないため、ブロックは実質的に BLOB から削除されます。

次の例は、Put Block List を呼び出して BLOB を更新する場合を示しています。

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1  
  
Request Headers:  
x-ms-date: Wed, 31 Aug 2009 00:17:43 GMT  
x-ms-version: 2011-08-18  
Content-Type: text/plain; charset=UTF-8  
Authorization: SharedKey myaccount:DJ5QZSVONZ64vAhnN/wxcU+Pt5HQSLAiLITlAU76Lx8=  
Content-Length: 133  
  
Request Body:  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Uncommitted>ANAAAA==</Uncommitted>  
  <Committed>AQAAAA==</Committed>  
  <Uncommitted>AZAAAA==</Uncommitted>  
</BlockList>  
  

[応答]

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

状態コード

操作が正常に終了すると、状態コード 201 (Created) が返されます。

状態コードの詳細については、「 状態とエラー コード」を参照してください。

応答ヘッダー

この操作の応答には、次のヘッダーが含まれています。 応答に追加の標準 HTTP ヘッダーが含まれる場合もあります。 すべての標準ヘッダーは 、HTTP/1.1 プロトコル仕様に準拠しています

[応答] 説明
ETag エンティティ タグに含まれる値は、クライアントが If-Match 要求ヘッダーを使用して条件付き GET/PUT 操作を実行するときに使用できます。 要求バージョンが 2011-08-18 以降の場合、ETag 値は引用符で囲まれます。
Last-Modified BLOB が最後に更新された日時。 日付形式は RFC 1123 に従います。 詳細については、「 ヘッダーの日付/時刻値を表す」を参照してください。

BLOB を変更する操作 (BLOB のメタデータまたはプロパティの更新など) を行うと、BLOB の最終更新時刻が変更されます。
Content-MD5 クライアントがメッセージ コンテンツの整合性を確認できるように返されます。 このヘッダーは、要求の内容 (この場合は、BLOB 自体のコンテンツではなくブロックの一覧) を参照します。 バージョン 2019-02-02 以降の場合、このヘッダーは、要求にこのヘッダーがある場合にのみ返されます。
x-ms-content-crc64 バージョン 2019-02-02 以降では、クライアントがメッセージ コンテンツの整合性を確認できるように、このヘッダーが返されます。 このヘッダーは、要求の内容 (この場合は、BLOB 自体のコンテンツではなくブロックの一覧) を参照します。

ヘッダーが要求に存在しない場合 Content-md5 、このヘッダーが返されます。
x-ms-request-id 行われた要求を一意に識別し、それを使用して要求のトラブルシューティングを行うことができます。 詳細については、「 API 操作のトラブルシューティング」を参照してください。
x-ms-version 要求の実行に使用される Blob Storage のバージョン。 このヘッダーは、バージョン 2009-09-19 以降に対して行われた要求に対して返されます。
Date 応答がいつ開始されたかを示す、サービスによって生成される UTC 日付/時刻値。
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-version-id: <DateTime> バージョン 2019-12-12 以降。 BLOB を一意に識別する不透明 DateTime な値を返します。 このヘッダーの値は BLOB のバージョンを示し、後続の要求で BLOB にアクセスするために使用できます。
x-ms-client-request-id 要求とそれに対応する応答のトラブルシューティングに使用できます。 このヘッダーの値は、要求に存在し、その値に 1,024 文字以下の ASCII 文字が含まれている場合、ヘッダーの値 x-ms-client-request-id と等しくなります。 ヘッダーが x-ms-client-request-id 要求に存在しない場合は、応答に存在しません。

応答のサンプル

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 00:17:44 GMT  
ETag: “0x8CB172A360EC34B”  
Last-Modified: Sun, 25 Sep 2011 00:17:43 GMT  
x-ms-version: 2011-08-18  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-version-id: <DateTime>  

承認

この操作は、アカウント所有者と、この BLOB またはそのコンテナーに書き込むアクセス許可を持つ共有アクセス署名を持つすべてのユーザーによって呼び出すことができます。

要求で要求ヘッダーを持つタグが指定されている x-ms-tags 場合、呼び出し元は BLOB タグの設定 操作の承認要件を満たす必要があります。

注釈

Put Block List 操作によって、BLOB を作成するためにブロックが結合される順序が決まります。

ブロック一覧内に同じブロック ID を複数回指定できます。 ブロック ID が複数回指定されている場合、最終的にコミットされた BLOB のブロック リスト内の各場所のバイト範囲を表します。 同じブロック ID が一覧に複数出現した場合は、そのブロック ID のすべてのインスタンスを同じブロック一覧に指定する必要があります。 つまり、すべてのインスタンスを Committed 要素、Uncommitted 要素、Latest 要素のいずれかに指定する必要があります。

では Put Block List、BLOB 全体を再度アップロードすることなく、個々のブロックを挿入、更新、または削除することで、既存の BLOB を変更できます。 新規 BLOB を作成する場合、または既存 BLOB のコンテンツを更新する場合、ブロック ID を現在のコミット後のブロック一覧とコミット前のブロック一覧の両方から指定できます。 このようにして、コミットされていないブロック リストからいくつかの新しいブロックを指定し、コミットされたブロック リストの残り (既に既存の BLOB の一部である) を指定することで、BLOB を更新できます。

Latest 要素に指定したブロック ID がコミット後のブロック一覧とコミット前のブロック一覧の両方に存在する場合、Put Block List はコミット前のブロック一覧からブロックをコミットします。 コミットされたブロック リストにブロック ID が存在し、コミットされていないブロック リストに存在しない場合は、 Put Block List コミットされたブロック リストからブロックをコミットします。

ブロック BLOB 内の各ブロックのサイズは異なる場合があります。 ブロック BLOB には、最大 50,000 個のコミット済みブロックを含めることができます。 BLOB に関連付けられる可能性があるコミットされていないブロックの最大数は 100,000 です。

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

サービスのバージョン 最大ブロック サイズ (経由 Put Block) 最大 BLOB サイズ (経由 Put Block List) 1 回の書き込み操作による最大 BLOB サイズ (経由 Put Blob)
バージョン 2019-12-12 以降 4,000 メビバイト (MiB) 約 190.7 テビバイト (TiB) (4,000 MiB × 50,000 ブロック) 5,000 MiB
バージョン 2016-05-31 から 2019-07-07 100 MiB 約 4.75 TiB (100 MiB × 50,000 ブロック) 256 MiB
2016-05-31 より前のバージョン 4 MiB 約 195 GiB (4 MiB × 50,000 ブロック) 64 MiB

Put Block List を呼び出して既存の BLOB を更新すると、BLOB の既存のプロパティおよびメタデータは上書きされますが、 既存のスナップショットは BLOB 内で維持されます。 条件要求ヘッダーを使用して、指定した条件を満たした場合にのみ操作を実行することもできます。

ブロックがないために Put Block List 操作が失敗した場合は、不足しているブロックをアップロードする必要があります。

コミットされていないブロックは、最後に成功Put Blockした操作の後の 1 週間以内に BLOB に対するPut Block呼び出しがPut Block List成功しなかった場合、ガベージ コレクションされます。 BLOB で Put BLOB が呼び出されると、コミットされていないブロックはすべてガベージ コレクションされます。

ヘッダーにタグが x-ms-tags 指定されている場合は、クエリ文字列でエンコードする必要があります。 タグ キーと値は、 で指定されている名前付けと長さの要件に Set Blob Tags準拠している必要があります。 また、ヘッダーには x-ms-tags 、最大 2 KiB のサイズのタグを含めることができます。 さらにタグが必要な場合は、 BLOB タグの設定操作を 使用します。

BLOB にアクティブなリースがある場合、クライアントはブロック リストをコミットする要求に対して有効なリース ID を指定する必要があります。 クライアントがリース ID を指定しないか、無効なリース ID を指定した場合、Blob Storage は状態コード 412 (前提条件に失敗しました) を返します。 クライアントがリース ID を指定しても BLOB にアクティブなリースがない場合、Blob Storage は状態コード 412 (前提条件に失敗しました) も返します。 クライアントでまだ存在しない BLOB のリース ID が指定されている場合、Blob Storage はバージョン 2013-08-15 以降に対して行われた要求の状態コード 412 (前提条件が失敗) を返します。 以前のバージョンの場合、Blob Storage は状態コード 201 (作成済み) を返します。

BLOB にアクティブなリースが存在する場合、Put Block List を呼び出して BLOB を更新すると、更新された BLOB でもリースは維持されます。

Put Block List はブロック BLOB のみに適用されます。 ページ BLOB に対して Put Block List を呼び出すと、ステータス コード 400 (Bad Request) が返されます。

アーカイブされた BLOB の上書きは失敗し、x-ms-access-tier ヘッダーが指定されていない場合、または cool BLOB を上書きhotすると古い BLOB から層が継承されます。

関連項目

ブロック BLOB、追加 BLOB、およびページ BLOB について理解する
Azure Storage への要求を承認する
状態コードとエラー コード
BLOB サービスのエラー コード
BLOB サービス操作のタイムアウトを設定する