ここでは、複数のバッチ API 呼び出しを行って、クライアント側の HTTP 接続の回数を減らす方法について説明します。
このドキュメントでは、特に HTTP リクエストを送信してバッチ リクエストを行う方法について説明します。Google クライアント ライブラリを使用して一括リクエストを実行している場合は、クライアント ライブラリのドキュメントをご覧ください。
概要
クライアントで HTTP 接続を行うたびに、ある程度のオーバーヘッドが発生します。People API ではバッチ処理がサポートされており、クライアントで複数の API 呼び出しを 1 つの HTTP リクエストにまとめることができます。
バッチ処理は次のような状況で使用します。
- API の使用を開始したばかりで、アップロードするデータが大量にある。
- アプリケーションがオフライン（インターネットに接続されていない状態）のときにユーザーがデータを変更したため、更新や削除の呼び出しを大量に送信してローカルデータとサーバー間で同期させる必要がある。
いずれの場合も、各呼び出しを個別に送信する代わりに、1 つの HTTP リクエストにまとめることができます。内部リクエストはすべて、同じ Google API に送信される必要があります。
1 つのバッチ リクエストでは 1,000 回まで呼び出しが可能です。これよりも多くの呼び出しを行う必要がある場合は、複数のバッチ リクエストを使用してください。
注: People API のバッチシステムは OData バッチ処理システムと同じ構文を使用しますが、セマンティクスは異なります。
バッチ リクエストの詳細
バッチ リクエストは、複数の API 呼び出しを 1 つの HTTP リクエストにまとめたもので、API ディスカバリ ドキュメントで指定されている batchPath に送信できます。デフォルトのパスは /batch/api_name/api_version です。このセクションでは、バッチ リクエストの構文について詳しく説明し、最後に例を紹介します。
注: 1 セットの n リクエストをバッチにまとめると、1 件のリクエストとしてではなく n リクエストとして使用量上限にカウントされます。バッチ リクエストは、処理前に一連のリクエストに分割されます。
バッチ リクエストの形式
バッチ リクエストは、multipart/mixed コンテンツ タイプを使用した、複数の People API 呼び出しを含む単一の標準 HTTP リクエストです。そのメインの HTTP リクエスト内の各パーツには、ネストされた HTTP リクエストが含まれます。
各パーツはそれぞれ Content-Type: application/http という形式の HTTP ヘッダーで始まり、オプションの Content-ID ヘッダーを指定することもできます。ただし、パーツヘッダーはパーツの開始箇所を示すためだけに存在していて、ネストされたリクエストとは分かれています。サーバーがバッチ リクエストを別々のリクエストにアンラップした後、パーツヘッダーは無視されます。
各パーツのボディは、それ自体が独自の動詞、URL、ヘッダー、ボディを持つ完全な HTTP リクエストになっています。これらの 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 番目の呼び出しを送信します。
例
次の例は、People API によるバッチ処理の使用方法を示しています。
バッチ リクエストの例
POST /batch HTTP/1.1 accept-encoding: gzip, deflate Authorization: Bearer your_auth_token Content-Type: multipart/mixed; boundary="batch_people" Content-Length: total_content_length--batch_people Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: 1
POST /v1/people:createContact HTTP/1.1 Content-Type: application/json Content-Length: part_content_length Accept: application/json { "names": [{ "givenName": "John", "familyName": "Doe" }] }
--batch_people Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: 2
GET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1 Accept: application/json --batch_people--
バッチ レスポンスの例
これは、前のセクションのリクエスト例に対するレスポンスです。
HTTP/1.1 200 OK Content-Type: multipart/mixed; boundary=batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Date: Tue, 22 Jan 2020 18:56:00 GMT Expires: Tue, 22 Jan 2020 18:56:00 GMT Cache-Control: private--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Content-Type: application/http Content-ID: response-1
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "resourceName": "people/c11111111111111", "etag": "1111", "names": [{ "givenName": "John", "familyName": "Doe" }] }
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Content-Type: application/http Content-ID: response-2
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "resourceName": "people/c123456789012345", "etag": "1234", "emailAddresses": [{ "value": "jane.doe@gmail.com" }] } --batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--