Blob Batch

  • [アーティクル]

この Blob Batch 操作により、複数の API 呼び出しを 1 つの HTTP 要求に埋め込むことができます。 この API では、ブロック BLOB の BLOB 層の設定と BLOB の削除という 2 種類のサブ要求がサポートされています。 バッチ要求に対してサーバーから返される応答には、バッチ内の各サブ要求の結果が含まれます。 バッチ要求と応答では、バッチ処理仕様の構文が OData 使用され、セマンティクスが変更されます。 この API は、バージョン 2018-11-09 以降で使用できます。

要求

要求は Blob Batch 次のように構築できます。 HTTPS が推奨されます。 myaccount をストレージ アカウントの名前に置き換えます。

Method 要求 URI HTTP バージョン
POST https://myaccount.blob.core.windows.net/?comp=batch

https://myaccount.blob.core.windows.net/containername?restype=container&comp=batch		 HTTP/1.1

URI パラメーター

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

パラメーター 説明
timeout 省略可能。 タイムアウト パラメーターは秒単位で表され、最大値は 120 秒です。 詳細については、「 Blob Storage 操作のタイムアウトの設定」を参照してください。
restype オプション、バージョン 2020-04-08 以降。 パラメーターでサポートされる唯一の restype 値は です container。 このパラメーターを指定する場合、URI にはコンテナー名を含める必要があります。 サブ要求は、同じコンテナーにスコープを設定する必要があります。

要求ヘッダー

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

要求ヘッダー 説明
Authorization 必須。 承認スキーム、ストレージ アカウント名、署名を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
Date または x-ms-date 必須。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
x-ms-version すべての承認された要求に必要です。 この要求に使用する操作のバージョンを指定します。 このバージョンは、すべてのサブ要求に使用されます。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
Content-Length 必須。 要求のサイズ。
Content-Type 必須。 このヘッダーの値は、バッチ境界を持つ である multipart/mixed必要があります。 ヘッダー値の例: multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252。
x-ms-client-request-id 省略可能。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「Azure Blob Storageの監視」を参照してください。

要求本文

BLOB バッチの要求本文には、すべてのサブ要求の一覧が含まれています。 この形式では、バッチ仕様の構文が OData 使用され、セマンティクスが変更されます。

要求本文はバッチ境界で始まり、その後に 2 つの必須ヘッダーが続きます。値が Content-Type のヘッダーと、値 application/httpbinaryが Content-Transfer-Encoding のヘッダーです。 その後に省略可能 Content-ID なヘッダーが続き、各サブ要求を追跡するための文字列値が含まれます。 応答には、追跡に Content-ID 使用する対応する各サブ要求応答のヘッダーが含まれています。

これらの要求ヘッダーの後に必須の空の行が続き、各サブ要求の定義が続きます。 各サブ要求の本文は、要求に必要な動詞、URL、ヘッダー、本文を含む完全な HTTP 要求です。 次の注意事項に注意してください。

  • サブ要求には、 を含めないようにする x-ms-version header必要があります。 すべてのサブ要求は、最上位のバッチ要求バージョンで実行されます。
  • サブ要求 URL には、URL のパス (ホストなし) のみを含める必要があります。
  • 各バッチ要求では、最大 256 個のサブ要求がサポートされます。
  • すべてのサブ要求は、同じ要求の種類である必要があります。
  • 各サブ要求は個別に承認され、サブ要求に指定された情報が含まれます。
  • 要求本文の各行は 、\r\n 文字で終わる必要があります。

要求のサンプル

POST http://account.blob.core.windows.net/?comp=batch HTTP/1.1 
Content-Type: multipart/mixed; boundary=batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
x-ms-version: 2018-11-09 
Authorization: SharedKey account:QvaoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI=
Host: 127.0.0.1:10000 
Content-Length: 1569 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 0 

DELETE /container0/blob0 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:G4jjBXA7LI/RnWKIOQ8i9xH4p76pAQ+4Fs4R1VxasaE= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 1 

DELETE /container1/blob1 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:IvCoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525 
Content-Type: application/http 
Content-Transfer-Encoding: binary 
Content-ID: 2 

DELETE /container2/blob2 HTTP/1.1 
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT 
Authorization: SharedKey account:S37N2JTjcmOQVLHLbDmp2johz+KpTJvKhbVc4M7+UqI= 
Content-Length: 0 

--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525--

Response

応答には、HTTP 状態コードと、最上位のバッチ要求の応答ヘッダーのセットが含まれます。 応答には、そのすべてのサブ要求の応答情報も含まれます。

応答本文

バッチ応答は応答であり multipart/mixed 、各サブ要求の応答が含まれます。 応答がチャンクされます。 各サブ応答は ヘッダーで Content-Type: application/http 始まります。 ヘッダーは Content-ID 、要求で指定された場合に続きます。 その後に HTTP 応答状態コードと、各サブ要求の応答ヘッダーが続きます。

各サブ要求によって返されるヘッダーの詳細については、 BLOB の削除 操作と BLOB 層の設定 操作に関するドキュメントを参照してください。

応答のサンプル

HTTP/1.1 202 Accepted 
Transfer-Encoding: chunked 
Content-Type: multipart/mixed; boundary=batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
x-ms-request-id: 778fdc83-801e-0000-62ff-033467000000 
x-ms-version: 2018-11-09 

409
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 0 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e284f 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 1 

HTTP/1.1 202 Accepted 
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2851 
x-ms-version: 2018-11-09 

--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed 
Content-Type: application/http 
Content-ID: 2 

HTTP/1.1 404 The specified blob does not exist. 
x-ms-error-code: BlobNotFound 
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2852 
x-ms-version: 2018-11-09 
Content-Length: 216 
Content-Type: application/xml 

<?xml version="1.0" encoding="utf-8"?> 
<Error><Code>BlobNotFound</Code><Message>The specified blob does not exist. 
RequestId:778fdc83-801e-0000-62ff-0334671e2852 
Time:2018-06-14T16:46:54.6040685Z</Message></Error> 
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed-- 
0

status code

バッチ要求が整形式で承認されている場合、操作は状態コード 202 (Accepted) を返します。 各サブ要求には、操作の結果に応じて独自の応答があります。 サブ要求の状態は、応答本文で返されます。

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

応答ヘッダー

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

承認

を省略した場合 restype=container は、共有キーを使用して親バッチ要求を承認する必要があります。 アカウント アクセス キー、アカウント共有アクセス署名、または Azure Active Directory を使用できます。 以下に示す特定の承認メカニズムの詳細。

が要求に含まれている場合 restype=container は、共有キーまたは Azure Active Directory を使用して親バッチ要求を承認できます。 これらの承認メカニズムのいずれかで署名された共有アクセス署名を使用して承認することもできます。 以下に示す特定の承認メカニズムの詳細。

各サブ要求は個別に承認されます。 サブ要求は、バッチ操作の一部でない場合に操作がサポートするのと同じ承認メカニズムをサポートします。

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ユーザー、グループ、またはサービス プリンシパルが親要求を行Blob Batchうために必要な RBAC アクションと、このアクションを含む最小特権の組み込み Azure RBAC ロールを次に示します。

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

請求

Blob Batch REST 要求は 1 つのトランザクションとしてカウントされ、個々のサブ要求も 1 つのトランザクションとしてカウントされます。 個々のサブ要求の課金の詳細については、 BLOB の削除 操作と BLOB 層の設定 操作に関するドキュメントを参照してください。

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

操作 ストレージ アカウントの種類 課金カテゴリ
Blob Batch (BLOB 層の設定) Premium ブロック BLOB
Standard 汎用 v2		 その他の操作

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

注釈

バッチ要求を使用するメインの利点の 1 つは、クライアントが開く必要がある接続の数を減らすことです。 次の制限事項に注意してください。

  • バッチでサポートされているサブ要求は Set Blob Tier 、(ブロック BLOB の場合) と Delete Blobです。
  • 1 つのバッチで最大 256 個のサブ要求のみをサポートします。 バッチ要求の本文のサイズは 4 MB を超えることはできません。
  • 空のバッチ要求がコード 400 (無効な要求) で失敗します。
  • バッチ サブ要求の実行順序に関する保証はありません。
  • バッチ サブ要求の実行はアトミックではありません。 各サブ要求は個別に実行されます。
  • 各サブ要求は、同じストレージ アカウント内のリソースに対してである必要があります。 1 つのバッチ要求では、異なるストレージ アカウントからの要求の実行はサポートされていません。
  • 入れ子になった要求本文はサポートされていません。
  • サーバーが要求本文の解析に失敗すると、バッチ全体が失敗し、要求は実行されません。
  • バッチで を使用restype=containerしていない場合、アカウント SAS は でBlob Batchサポートされる唯一の共有アクセス署名の種類であることに注意してください。

すべてのサブ要求のスコープを特定のコンテナーに設定する

REST バージョン 2020-04-08 以降、API では、 Blob Batch 指定されたコンテナーへのサブ要求のスコープ設定がサポートされています。 要求 URI にコンテナー名と パラメーターが restype=container 含まれている場合、各サブ要求は同じコンテナーに適用される必要があります。 サブ要求に指定されたコンテナー名が URI で指定されたコンテナー名と一致しない場合、サービスはエラー コード 400 (無効な要求) を返します。

コンテナーに対してサポートされているすべての承認メカニズムは、コンテナーをスコープとする Blob Batch 操作に対して有効です。 各サブ要求は、承認ヘッダーをサービスに送信します。

こちらもご覧ください

Azure Storage の状態とエラー コードに対する要求を承認する Blob Storage エラー コード BlobStorage 操作のタイムアウトの設定