一括リクエストの送信

ここでは、複数の API 呼び出しを一括で行って、クライアント側の HTTP 接続の回数を減らす方法について説明します。

具体的には、HTTP リクエストを送信して一括リクエストを行う方法を取り上げます。Google クライアント ライブラリを使用して一括リクエストを行う場合は、クライアント ライブラリのドキュメントをご覧ください。

概要

クライアントで HTTP 接続を行うたびに、ある程度のオーバーヘッドが発生します。Google Cloud Deployment Manager V2 API では一括処理がサポートされており、クライアントは複数の API 呼び出しを 1 つの HTTP リクエストにまとめることができます。

一括処理は次のような状況で使用します。

• API の使用を開始したばかりで、アップロードするデータが大量にある。
• アプリケーションがオフライン（インターネットに接続されていない状態）のときにユーザーがデータを変更したため、ローカルデータとサーバー間で同期して、多数の更新と削除の呼び出しを送信する必要がある。

いずれの場合も、各呼び出しを別々に送信する代わりに、複数の呼び出しを 1 つの HTTP リクエストにまとめることができます。複数のユーザーや Google API に対するリクエストをグループ化することもできます。

1 つの一括リクエストに含めることができる呼び出しの上限は 1,000 個です。これ以上の数の呼び出しを行う必要がある場合は、一括リクエストを複数使用します。

注: Google Cloud Deployment Manager V2 API の一括処理システムは OData 一括処理システムと同じ構文を使用しますが、セマンティクスは異なります。

一括リクエストの詳細

一括リクエストは 1 つの HTTP リクエストにまとめられた複数の API 呼び出しで構成されます。このセクションでは、一括リクエストの構文について詳しく説明し、最後に例を示します。

注: n 個のリクエストが 1 つにまとめられている場合、1 つのリクエストではなく n 個のリクエストとして使用数に加算されます。一括リクエストは、処理の前に個々のリクエストに分けられます。

一括リクエストの形式

一括リクエストは multipart/mixed コンテンツ タイプを使用した単一の標準 HTTP リクエストで、複数の Google Cloud Deployment Manager V2 API 呼び出しから成ります。そのメインの HTTP リクエスト内の各パーツには、ネストされた HTTP リクエストが含まれます。

各パーツはそれぞれ Content-Type: application/http HTTP ヘッダーで始まり、オプションの Content-ID ヘッダーを指定することもできます。ただし、パーツヘッダーはパーツの開始箇所を示すためだけに存在していて、ネストされたリクエストとは分かれています。サーバーが一括リクエストを別々のリクエストにアンラップした後、パーツヘッダーは無視されます。

各パーツのボディ自体が完全な HTTP リクエストで、独自の動詞、URL、ヘッダー、ボディが含まれます。HTTP リクエストには URL のパス部分のみを含める必要があり、完全な URL は、一括リクエストでは許可されていません。

外側の一括リクエストの HTTP ヘッダー（Content-Type などの Content- ヘッダー以外）は一括リクエスト内の各リクエストに適用されます。ある HTTP ヘッダーを外側のリクエストと個々の呼び出しの両方で指定した場合、個々の呼び出しのヘッダー値は外側の一括リクエストのヘッダー値を上書きします。個々の呼び出しのヘッダーはその呼び出しにのみ適用されます。

たとえば、特定の呼び出しに Authorization ヘッダーを指定した場合、そのヘッダーはその呼び出しにのみ適用されます。Authorization ヘッダーを外側のリクエストに指定した場合、そのヘッダーはすべての呼び出しに適用されます。ただし、各呼び出しに独自の Authorization ヘッダーを指定している場合は各呼び出しの Authorization ヘッダーで上書きされます。

サーバーが一括リクエストを受信すると、外側のリクエストのクエリ パラメータとヘッダー（指定した場合）を各パーツに適用し、各パーツを個別の HTTP リクエストとして処理します。

一括リクエストへのレスポンス

サーバーのレスポンスは multipart/mixed コンテンツ タイプを使用した単一の標準 HTTP レスポンスです。各パーツは一括リクエスト内のいずれかのリクエストに対するレスポンスで、リクエストと同じ順序にネストされます。

リクエストのパーツと同様にレスポンスの各パーツには、ステータス コード、ヘッダー、ボディを含む完全な HTTP レスポンスが含まれます。また、リクエストのパーツと同様にレスポンスの各パーツは、パーツの開始箇所を示す Content-Type ヘッダーから始まります。

リクエストのパーツに Content-ID ヘッダーがある場合、対応するレスポンスのパーツには、それに一致する Content-ID ヘッダーが指定されます。レスポンスのパーツのヘッダーは、以下の例に示すように、元の値の先頭に文字列 response- が付いた値となります。

注: サーバーは一括リクエスト内の呼び出しを順番どおりに処理するとは限らないため、指定した順序で実行されると想定しないでください。2 つの呼び出しを特定の順序で実行したい場合は、1 つの一括リクエストで送信することはできません。代わりに、最初の呼び出しを送信してレスポンスが返ってきてから、2 番目の呼び出しを送信します。

例

以下は、Farm API という汎用（架空）デモ API を使用した一括リクエストの使用例を示しています。これと同じ概念が Google Cloud Deployment Manager V2 API にも当てはまります。

一括リクエストの例

POST /batch HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:[e-mail]>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:[e-mail]>

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:[e-mail]>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

一括レスポンスの例

これは、前のセクションのリクエストの例に対するレスポンスです。

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:[e-mail]>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:[e-mail]>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:[e-mail]>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--