Put Block
Put Block 操作は、コミットする新しいブロックを BLOB の一部として作成します。
要求
要求は Put Block 次のように構築できます。 HTTPS を使用することをお勧めします。
myaccount をストレージ アカウントの名前に置き換えます。
| PUT メソッド要求 URI | HTTP バージョン |
|---|---|
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=id |
HTTP/1.1 |
エミュレートされたストレージ サービス要求
エミュレートされたストレージ サービスに対して要求を行うときは、エミュレーターのホスト名と BLOB サービス ポートを として 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 の開発に Azurite エミュレーターを使用する方法に関するページを参照してください。
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 Services のバージョン管理」を参照してください。 |
Content-Length |
必須。 ブロックのコンテンツのサイズ (バイト単位)。 ブロックのサイズは、バージョン 2019-12-12 以降では 4,000 メビバイト (MiB) 以下である必要があります。 以前のバージョンの制限については、「 解説 」セクションを参照してください。 長さが指定されていない場合、操作は状態コード 411 (必要な長さ) で失敗します。 |
Content-MD5 |
省略可能。 ブロックのコンテンツの MD5 ハッシュ。 このハッシュは、転送時のブロックの整合性を確認するために使用します。 このヘッダーを指定すると、ストレージ サービスによって、到達したコンテンツのハッシュと、このヘッダー値が比較されます。 注: この MD5 ハッシュは BLOB と共に格納されません。 2 つのハッシュが一致しない場合、エラー コード 400 (Bad Request) で操作が失敗します。 |
x-ms-content-crc64 |
省略可能。 ブロック コンテンツの CRC64 ハッシュ。 このハッシュは、転送時のブロックの整合性を確認するために使用します。 このヘッダーを指定すると、ストレージ サービスによって、到達したコンテンツのハッシュと、このヘッダー値が比較されます。 注: この CRC64 ハッシュは BLOB と共に格納されません。 2 つのハッシュが一致しない場合、操作はエラー コード 400 (無効な要求) で失敗します。 Content-MD5 ヘッダーと x-ms-content-crc64 ヘッダーの両方が存在する場合、要求は 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 の監視」を参照してください。 |
要求ヘッダー (顧客が指定した暗号化キー)
バージョン 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: 2011-08-18
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=
Content-Length: 1048576
Response
応答には、HTTP 状態コードおよび一連の応答ヘッダーが含まれています。
status code
操作が正常に終了すると、状態コード 201 (Created) が返されます。
状態コードの詳細については、「 状態コードとエラー コード」を参照してください。
応答ヘッダー
この操作の応答には、次のヘッダーが含まれています。 応答に追加の標準 HTTP ヘッダーが含まれる場合もあります。 すべての標準ヘッダーは 、HTTP/1.1 プロトコル仕様に準拠しています。
| 応答ヘッダー | 説明 |
|---|---|
Content-MD5 |
クライアントがメッセージ コンテンツの整合性を確認できるように返されます。 このヘッダーの値は Blob Storage によって計算され、要求ヘッダーで指定されている値と必ずしも同じとは限りません。 バージョン 2019-02-02 以降の場合、このヘッダーは要求にこのヘッダーがある場合にのみ返されます。 |
x-ms-content-crc64 |
バージョン 2019-02-02 以降では、クライアントがメッセージ コンテンツの整合性を確認できるように、このヘッダーが返されます。 このヘッダーの値は Blob Storage によって計算され、要求ヘッダーで指定されている値と必ずしも同じとは限りません。 このヘッダーは、ヘッダーが要求に存在しない場合 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-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 23:47:09 GMT
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
承認
Azure Storage でデータ アクセス操作を呼び出す場合は、承認が必要です。 以下で説明するように、操作を Put Block 承認できます。
重要
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、またはサービス プリンシパルが操作を呼び出 Put Block すために必要な RBAC アクションと、このアクションを含む最小限の特権を持つ組み込み Azure RBAC ロールを次に示します。
- Azure RBAC アクション:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- 最小特権の組み込みロール:ストレージ BLOB データ共同作成者
Azure RBAC を使用したロールの割り当ての詳細については、「 BLOB データにアクセスするための Azure ロールの割り当て」を参照してください。
注釈
Put Block は、今後含めるブロックをブロック BLOB にアップロードします。 ブロック BLOB 内の各ブロックのサイズは異なる場合があります。 ブロック BLOB には、最大 50,000 個のコミット済みブロックを含めることができます。
次の表では、許可されるブロックと BLOB の最大サイズをサービス のバージョン別に示します。
| サービスのバージョン | 最大ブロック サイズ (経由 Put Block) |
最大 BLOB サイズ (経由 Put Block List) |
単一書き込み操作による最大 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 |
BLOB に関連付けられる可能性があるコミットされていないブロックの最大数は 100,000 です。 この数を超えると、サービスは状態コード 409 (RequestEntityTooLargeBlockCountExceedsLimit) を返します。
ブロックのセットをアップロードしたら、 Put Block List 操作を呼び出して、このセットからサーバー上の BLOB を作成または更新できます。 セット内の各ブロックは、その BLOB 内で一意のブロック ID によって識別されます。 ブロック ID は特定の BLOB にスコープ設定されるため、異なる BLOB に同じ ID を持つブロックを含めることができます。
まだ存在しない BLOB で を呼び出 Put Block すと、コンテンツの長さが 0 の新しいブロック BLOB が作成されます。 この BLOB は、include=uncommittedblobs オプションを指定して List Blobs 操作を実行すると列挙されます。 アップロードするブロックは、新しい BLOB で を呼び出 Put Block List すまでコミットされません。 この方法で作成された BLOB は、サーバー上で 1 週間保持されます。 その期間内にブロックまたはコミットされたブロックを BLOB に追加していない場合、BLOB はガベージ コレクションされます。
操作で正常にアップロードされた Put Block ブロックは、 でコミット Put Block Listされるまで BLOB の一部になりません。 を呼び出して新しい BLOB または更新された BLOB をコミットする前 Put Block List に、 Get BLOB を呼び出す場合は、コミットされていないブロックを含めずに BLOB の内容が返されます。
まだコミットされていない別のブロックと同じブロック ID を持つブロックをアップロードすると、その ID を持つ最後にアップロードされたブロックは、次に成功した Put Block List 操作でコミットされます。
が Put Block List 呼び出されると、ブロック リストで指定されているすべてのコミットされていないブロックが、新しい BLOB の一部としてコミットされます。 BLOB のブロック リストで指定されていないコミットされていないブロックは、ガベージ コレクションされ、Blob Storage から削除されます。 コミットされていないブロックは、前回成功Put Blockした操作の 1 週間以内に同じ BLOB に対するPut BlockPut Block List呼び出しが成功しなかった場合にもガベージ コレクションされます。
BLOB で Put BLOB が呼び出されると、コミットされていないブロックはすべてガベージ コレクションされます。
BLOB にアクティブなリースがある場合、クライアントはブロックを BLOB に書き込む要求に対して有効なリース ID を指定する必要があります。 クライアントがリース ID を指定しないか、無効なリース ID を指定した場合、Blob Storage は状態コード 412 (前提条件に失敗しました) を返します。 クライアントがリース ID を指定しても BLOB にアクティブなリースがない場合、Blob Storage は状態コード 412 (前提条件に失敗しました) も返します。
指定された BLOB の場合、すべてのブロック ID は同じ長さである必要があります。 アップロードされたブロックと既存のコミット前のブロックでブロック ID の長さが異なる場合、サービスはステータス コード 400 (Bad Request) を返します。
バージョン 2019-12-12 以降で 4,000 MiB を超えるブロックをアップロードしようとすると、バージョン 2016-05-31 以降では 100 MiB を超え、古いバージョンでは 4 MiB を超える場合、サービスは状態コード 413 (要求エンティティが大きすぎる) を返します。 また、このサービスは、許可される最大ブロック サイズをバイト単位で含め、応答のエラーに関する追加情報も返します。
を呼び出 Put Block しても、既存の BLOB の最終変更時刻は更新されません。
ページ BLOB に対して Put Block を呼び出すと、エラーが返されます。
アーカイブされた BLOB で を呼び出Put Blockすとエラーが返され、 または cool BLOB でhot呼び出しても BLOB 層は変更されません。
請求
価格要求は、Blob Storage REST API を介して直接、または Azure Storage クライアント ライブラリから Blob Storage API を使用するクライアントから送信できます。 これらの要求では、トランザクションあたりの料金が発生します。 トランザクションの種類は、アカウントの課金方法に影響します。 たとえば、読み取りトランザクションは、書き込みトランザクションとは異なる課金カテゴリに計上されます。 次の表は、ストレージ アカウントの種類に基づく要求の課金カテゴリ Put Block を示しています。
| 操作 | ストレージ アカウントの種類 | 課金カテゴリ |
|---|---|---|
| Put Block | Premium ブロック BLOB Standard 汎用 v2 Standard 汎用 v1 |
書き込み操作1 |
1 操作Put Block は、ストレージ アカウントの既定のアクセス層を使用して一時ストレージにブロックを書き込みます。 たとえば、BLOB をアーカイブ層にアップロードする場合、アップロードの一部である操作は、 Put Block 転送先層ではなく、ストレージ アカウントの既定のアクセス層に基づく書き込み操作として課金されます。
Put Block List と Put Blob の操作は、ただし、BLOB の宛先層に基づく書き込み操作として課金されます。
指定した課金カテゴリの価格については、「 Azure Blob Storage の価格」を参照してください。
こちらもご覧ください
Azure Storage への要求を承認する
状態コードとエラー コード
BLOB サービスのエラー コード
BLOB サービス操作のタイムアウトを設定する