Put Block From URL

この操作により Put Block From URL 、コンテンツが URL から読み取られる BLOB の一部としてコミットされる新しいブロックが作成されます。 この API はバージョン 2018-03-28以降で使用できます。

Request

Put Block From URL 要求の構成は次のとおりです。 HTTPS が推奨されます。 myaccount をストレージ アカウントの名前に置き換えます。

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

エミュレートされたストレージ サービスの URI

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

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

詳細については、「開発とテストにAzure Storage Emulatorを使用する」を参照してください。

URI パラメーター

パラメーター 説明
blockid 必須です。 ブロックを識別する有効な Base64 文字列値。 エンコードする前の文字列のサイズは 64 バイト以下である必要があります。

BLOB の場合、blockid パラメーターに指定する値の長さは、各ブロックのサイズと同じである必要があります。

Base64 文字列は URL エンコードする必要があります。
timeout 省略可能。 timeout パラメーターは、秒単位で表されます。 詳細については、「 BLOB サービス操作のタイムアウトの設定」を参照してください

要求ヘッダー

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

要求ヘッダー 説明
Authorization 必須です。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storage要求を承認する」を参照してください。
Date または x-ms-date 必須です。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage要求を承認する」を参照してください。
x-ms-version すべての承認された要求に必要です。 この要求に使用する操作のバージョンを指定します。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。 Put Block From URL の場合、バージョンは 2018-03-28 以降である必要があります。
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要求を承認する」を参照してください。
Azure Active Directoryではスキーム ベアラーのみがサポートされています。
このヘッダーは、バージョン 2020-10-02 以降でサポートされています。
x-ms-source-range 省略可能。 指定した範囲内のソース URL 内の BLOB のバイトのみをアップロードします。 これが指定されていない場合、ソース BLOB の内容全体が 1 つのブロックとしてアップロードされます。 詳細については、 BLOB サービス操作の範囲ヘッダーの指定 に関するページを参照してください。
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-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 KiB 文字の制限を持つクライアント生成の不透明な値を提供します。 クライアント側のアクティビティをサーバーが受信した要求と関連付けるには、このヘッダーを使用することが強く推奨されます。 詳細については、「Storage Analyticsログ記録と Azure ログ記録: ログを使用した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=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2018-03-28  
x-ms-date: Sat, 31 Mar 2018 14:37:35 GMT    
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-499

Response

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

状態コード

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

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

レスポンス ヘッダー

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

応答ヘッダー 説明
Content-MD5 このヘッダーは、クライアントがメッセージ内容の整合性を確認する目的で返されます。 このヘッダーの値は BLOB サービスによって計算されるので、要求ヘッダーで指定された値と必ずしも同じ値であるとは限りません。 バージョン 2019-02-02 以降の場合、このヘッダーは要求にこのヘッダーがある場合にのみ返されます。
x-ms-content-crc64 バージョン 2019-02-02 以降では、クライアントがメッセージ コンテンツの整合性を確認できるように、このヘッダーが返されます。 このヘッダーの値は BLOB サービスによって計算されるので、要求ヘッダーで指定された値と必ずしも同じ値であるとは限りません。

このヘッダーは、要求にヘッダーが存在しない場合 x-ms-source-content-md5 に返されます。
x-ms-request-id このヘッダーは要求を一意に識別するので、要求のトラブルシューティングに使用できます。 詳細については、「 API 操作のトラブルシューティング」を参照してください
x-ms-version 要求の実行に使用する BLOB サービスのバージョンを示します。
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-client-request-id このヘッダーは、要求と対応する応答のトラブルシューティングに使用できます。 このヘッダーの値は、要求に存在し、その値 x-ms-client-request-id が最大 1024 文字の ASCII 文字で表示される場合、ヘッダーの値と同じです。 ヘッダーが x-ms-client-request-id 要求に存在しない場合、このヘッダーは応答に存在しません。

応答のサンプル

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sat, 31 Mar 2018 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  

承認

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

解説

Put Block From URL は、今後含めるブロックをブロック BLOB にアップロードします。 ブロック BLOB には、最大 50,000 個のブロックを含めることができます。 各ブロックは異なるサイズにすることができます。 アップロードされる Put Block From URL ブロックの最大サイズは 100 MiB です。 より大きなブロック (最大 4,000 MiB) をアップロードするには、「 ブロックの配置」を参照してください。

バージョン 2020-10-02 以降では、コピー操作のソースに対してAzure Active Directory承認がサポートされています。

BLOB は、任意の時点で最大 100,000 個のコミットされていないブロックを持つことができます。 この最大値を超えると、サービスは状態コード 409 (RequestEntityTooLargeBlockCountExceedsLimit) を返します。

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

サービスのバージョン 最大ブロック サイズ (URL から Put Block を使用) 最大 BLOB サイズ (Put Block List 使用) 1 回の書き込み操作による BLOB の最大サイズ (URL からの PUT BLOB 経由)
バージョン 2020-04-08 以降 4,000 MiB 約 190.7 TiB (4,000 MiB x 50,000 ブロック) 5000 MiB (プレビュー)
2020-04-08 より前のバージョン 100 MiB 約 4.75 TiB (100 MiB x 50,000 ブロック) 256 MiB

一連のブロックをアップロードしたら、 Put Block List 操作を呼び出すことによって、このセットからサーバー上の BLOB を作成または更新できます。 各ブロックは、BLOB 内で一意のブロック ID によって識別されます。 ブロック ID のスコープは特定の BLOB に限定されているため、異なる BLOB に同じ ID のブロックが存在する場合があります。

存在しない BLOB に対して Put Block From URL を呼び出した場合、コンテンツ サイズが 0 の新しいブロック BLOB が作成されます。 この BLOB は、include=uncommittedblobs オプションを指定して List Blobs 操作を実行すると列挙されます。 新規 BLOB に対して Put Block List を呼び出すまで、アップロードしたブロックはコミットされません。 この方法で作成した BLOB は 1 週間サーバーに保持されます。この期間にブロックを追加またはコミットしなかった BLOB はガベージ コレクションされます。

Put Block From URL 操作で正常にアップロードされたブロックは、Put Block List でコミットするまでは BLOB に含まれません。 新しい BLOB または更新された BLOB をコミットするために呼び出される前 Put Block List に、 Get BLOB の呼び出しでは、コミットされていないブロックを含めずに BLOB の内容が返されます。

コミット前の他のブロックと同じブロック ID を持つブロックをアップロードすると、次回に Put Block List 操作が成功したときには、その ID で最後にアップロードされたブロックがコミットされます。

Put Block List を呼び出すと、ブロック一覧に指定されたすべてのコミット前のブロックが新規 BLOB の一部としてコミットされます。 BLOB のブロック一覧に指定されていないコミット前のブロックはガベージ コレクションされ、BLOB Service から削除されます。 前回 Put Block From URL 操作が成功してから 1 週間以内に同じ BLOB に対する Put Block List または Put Block From URL の成功した呼び出しが存在しない場合にも、コミット前のブロックはガベージ コレクションされます。 PUT BLOB が BLOB で呼び出されると、コミットされていないブロックはすべてガベージ コレクションされます。

BLOB にアクティブなリースが存在する場合、クライアントが BLOB にブロックを書き込むには、要求に有効なリース ID を指定する必要があります。 クライアントがリース ID を指定しなかった場合、または無効なリース ID を指定した場合、BLOB Service はステータス コード 412 (Precondition Failed) を返します。 クライアントがリース ID を指定し、BLOB にアクティブなリースが存在しない場合にも、BLOB Service はステータス コード 412 (Precondition Failed) を返します。

1 つの BLOB において、すべてのブロック ID の長さは同じである必要があります。 アップロードされたブロックと既存のコミット前のブロックでブロック ID の長さが異なる場合、サービスはステータス コード 400 (Bad Request) を返します。

Put Block From URL を呼び出しても、既存の BLOB の最終更新時刻は更新されません。

ページ BLOB に対して Put Block From URL を呼び出すと、エラーが返されます。

アーカイブされた BLOB を呼び出 Put Block From URL すとエラーが返され、BLOB では Hot/Cool BLOB 層は変更されません。

参照