このドキュメントでは、アプリケーションのパフォーマンスの向上に利用できるいくつかのテクニックについて説明します。わかりやすく説明するために他の API や汎用 API を例として使用する場合もありますが、Google アナリティクス API にも同じ考え方を応用することができます。
gzip の使用
gzip 圧縮を有効にすると、各リクエストが消費する帯域幅を手早く低減できます。圧縮を行うと展開が必要になる分 CPU 時間が長くなりますが、多くの場合、そのデメリットを大きく上回るネットワーク コストの節約効果が得られます。
gzip でエンコードされたレスポンスを受け取るには、Accept-Encoding
ヘッダーを設定し、ユーザー エージェントを変更して文字列 gzip
を含める必要があります。gzip 圧縮を有効にする正しい HTTP ヘッダーの例を次に示します。
Accept-Encoding: gzip User-Agent: my program (gzip)
部分リソースを使用した作業
API 呼び出しのパフォーマンスを向上させるもう 1 つの方法は、送受信するデータを必要な部分のみに限定することです。こうすると、アプリケーションで不要なフィールドの転送、解析、保存を行う必要がなくなるため、ネットワーク、CPU、メモリなどのリソースを効率良く利用できるようになります。
部分リクエストには次の 2 種類があります。
- 部分レスポンス - どのフィールドをレスポンスに含めるのかを指定するリクエスト(
fields
リクエスト パラメータを使用)。 - パッチ - 変更するフィールドだけを送信する更新リクエスト(HTTP の
PATCH
動詞を使用)。
以下では部分リクエストの実行方法について詳しく説明します。
部分レスポンス
デフォルトでは、サーバーはリクエストを処理した後、リソースを完全な形で返します。パフォーマンスを向上させるため、本当に必要なフィールドだけを送信するようサーバーに指示し、代わりに「部分レスポンス」を取得することができます。
部分的レスポンスをリクエストするには、fields
リクエスト パラメータを使用して取得するフィールドを指定します。このパラメータは、レスポンス データを返す任意のリクエストに指定できます。
fields
パラメータはレスポンス データにのみ影響します。送信が必要なデータがある場合、そのデータへの影響はありません。リソースを変更する際に送信するデータの量を減らすには、patch リクエストを使用します。
例
以下の例では、fields
パラメータの使い方を汎用的な(架空の)Demo API を用いて示します。
通常のリクエスト: 次の HTTP GET
リクエストでは、fields
パラメータを指定していないため、完全なリソースが返されます。
https://www.googleapis.com/demo/v1?key=YOUR-API-KEY
完全なリソース レスポンス: 完全なリソースデータには、次のようなフィールドが含まれます。ここでは、わかりやすくするために多数のフィールドを省略しています。
{ "kind": "demo", ... "items": [ { "title": "First title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }, { "title": "Second title", "comment": "Second comment.", "characteristics": { "length": "long", "accuracy": "medium" "followers": [ ], }, "status": "pending", ... }, ... ] }
部分的レスポンスのリクエスト: 同じリソースに対する次のリクエストでは、fields
パラメータを使用しているため、返されるデータが大幅に少なくなります。
https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)
部分的レスポンス: サーバーは、上記のリクエストに対するレスポンスで、種類情報(kind)と、各アイテムの HTML タイトル(title)および長さの特性情報(characteristics)のみを格納した items 配列を返します。
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
JSON オブジェクトであるこのレスポンスには、指定したフィールドとその親オブジェクトしか含まれていないことに注目してください。
次のセクションで、fields
パラメータの形式の指定方法について説明し、さらにその後に、レスポンスとして返される具体的な内容について詳細に説明します。
fields パラメータの構文のまとめ
リクエストの fields
パラメータ値の形式はほぼ XPath の構文に基づいています。サポートされる構文の概要を以下に示し、次のセクションでその他の例を示します。
- 複数のフィールドを選択する場合は、カンマ区切りのリストを使用する。
- フィールド
a
内にネストされたフィールドb
を選択するにはa/b
を使用し、フィールドb
内にネストされたフィールドc
を選択するにはa/b/c
を使用する。
例外: データラッパーを使用する API レスポンスは、
data: { ... }
のようにdata
オブジェクト内にネストされているので、fields
の指定にdata
を含めません。data オブジェクトをdata/a/b
のように fields の指定に含めるとエラーが発生します。fields
の指定には単純にa/b
を使用します。 - 配列またはオブジェクトの特定のサブフィールド セットをリクエストする場合は、サブセレクタを使用し、かっこ「
( )
」の中に式を記述する。たとえば、
fields=items(id,author/email)
とすると、items 配列に含まれる各要素のアイテム ID(id)と作者(author)のメールアドレスのみが返されます。サブフィールドを 1 つだけ指定することもできます。ここで、fields=items(id)
とfields=items/id
は等価です。 - フィールドの選択では、必要に応じてワイルドカードを使用する。
たとえば
fields=items/pagemap/*
とすると、pagemap のすべてのオブジェクトが選択されます。
fields パラメータのその他の使用例
以下にいくつか例を挙げて、fields
パラメータ値がレスポンスに与える影響を説明します。
注: 他のすべてのクエリ パラメータの値と同じように、fields
パラメータ値には URL エンコードを使用する必要があります。読みやすくするために、このドキュメントの例ではエンコードを省略します。
- 取得するフィールドを指定するか、「フィールドの選択」を行う方法。
- リクエストの
fields
パラメータの値はフィールドのカンマ区切りリストとなり、各フィールドはレスポンスのルートに対して相対的に指定されます。したがって、list 操作を実行する場合、レスポンスはコレクションであり、通常はリソースの配列が含まれます。単一リソースを取得する操作を実行すると、フィールドはそのリソースに対して相対的に指定されます。選択したフィールドが配列または配列の一部である場合、サーバーはその配列の選択された部分のすべての要素を返します。
コレクション レベルの例を以下に示します。
例 結果 items
items 配列内のすべての要素を返す。各要素のすべてのフィールドが含まれるが、対象外のフィールドは含まれない。 etag,items
etag
フィールドと、items 配列内のすべての要素を返す。items/title
items 配列内のすべての要素の title
フィールドのみを返す。
ネストされたフィールドが返される場合、レスポンスには必ず親オブジェクトが含まれる。明示的に指定しない限り、同じ親フィールドのその他の子フィールドは返されない。context/facets/label
context
オブジェクトにネストされているfacets
配列内のすべてのメンバーのlabel
フィールドのみを返す。items/pagemap/*/title
items 配列内の各要素について、 pagemap
の子であるすべてのオブジェクトのtitle
フィールド(存在する場合)のみを返す。
リソースレベルの例を以下に示します。
例 結果 title
リクエストされたリソースの title
フィールドを返す。author/uri
リクエストされたリソースの author
オブジェクトのuri
サブフィールドを返します。links/*/href
links
の子であるすべてのオブジェクトのhref
フィールドを返す。 - 「サブ選択」を使用して特定のフィールドの一部分だけをリクエストする方法。
- デフォルトでは、リクエストで特定のフィールドを指定した場合、サーバーはオブジェクトまたは配列要素全体を返します。特定のサブフィールドだけを含むレスポンスを指定することもできます。それには、"
( )
" 部分選択構文を使用します。以下に例を示します。例 結果 items(title,author/uri)
items 配列内の各要素について、 title
と作者のuri
の値のみを返します。
部分的レスポンスの処理
サーバーは、fields
クエリ パラメータを含む有効なリクエストを処理した後で、リクエストされたデータとともに HTTP 200 OK
ステータス コードを返します。fields
クエリ パラメータにエラーがある場合、または無効である場合は、HTTP 400 Bad Request
ステータス コードとともに、フィールド選択の問題点をユーザーに知らせるエラー メッセージ("Invalid field selection a/b"
など)が返されます。
上記の導入部で紹介した部分的レスポンスの例は次のとおりです。リクエストでは fields
パラメータを使用して必要なフィールドを指定しています。
https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)
この場合の部分的レスポンスは次のようになります。
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
注: maxResults
や nextPageToken
など、データのページ設定のためのクエリ パラメータをサポートする API では、これらのパラメータを使用して各クエリの結果を適切なサイズに制限してください。そうしないと、部分的レスポンスで可能なパフォーマンスの向上が達成されない場合があります。
パッチ(部分更新)
リソースを変更する際に不要なデータの送信を避けることもできます。変更する特定のフィールドについてのみ更新されたデータを送信するには、HTTP の PATCH
動詞を使用します。このドキュメントで説明するパッチの意味は、従来の GData による部分更新の実装の場合とは異なり、よりシンプルになっています。
以下に示す簡単な例は、パッチを使用して、小さな更新を行うために送信する必要があるデータを最小化する方法を示しています。
例
この例は、「Demo」という汎用的な(架空)の API リソースのタイトルだけを更新する簡単なパッチ リクエストです。リソースには、コメント、特徴のセット、ステータスなど、多数のフィールドがありますが、このリクエストでは title
フィールドだけを変更するので、このフィールドだけを送信します。
PATCH https://www.googleapis.com/demo/v1/324 Authorization: Bearer your_auth_token Content-Type: application/json { "title": "New title" }
レスポンス
200 OK
{ "title": "New title", "comment": "First comment.", "characteristics": { "length": "short", "accuracy": "high", "followers": ["Jo", "Will"], }, "status": "active", ... }
サーバーは、200 OK
のステータス コードと、更新済みリソースの完全な表現を返します。パッチ リクエストには title
フィールドしか含まれていなかったので、この値だけが以前と異なります。
注: 部分レスポンスの fields
パラメータをパッチと組み合わせて使用すれば、更新リクエストの効率をさらに高めることができます。パッチ リクエストによって減らせるのはリクエストのサイズのみです。部分レスポンスではレスポンスのサイズを減らします。したがって、双方向で送信されるデータの量を減らすには、パッチ リクエストと fields
パラメータを使用します。
パッチ リクエストの意味
パッチ リクエストの本文には、変更するリソース フィールドだけを含めます。フィールドを指定する際は、部分レスポンスでフィールドを囲む親が返されるのとまったく同様に、フィールドを囲む親オブジェクトをすべて含める必要があります。変更されたデータを送信すると、親オブジェクトのデータが存在する場合は、そのデータに結合されます。
- 追加: まだ存在しないフィールドを追加するには、新しいフィールドとその値を指定します。
- 変更: 既存のフィールドの値を変更するには、そのフィールドを指定して、新しい値を設定します。
- 削除: フィールドを削除するには、フィールドを指定し、そのフィールドを
null
に設定します。たとえば、"comment": null
とします。オブジェクト全体を削除するには(オブジェクトが変更可能な場合)、オブジェクトにnull
を設定します。Java API クライアント ライブラリを使用する場合は、代わりにData.NULL_STRING
を使用します。詳しくは、JSON null をご覧ください。
配列に関する注意: 配列を含むパッチ リクエストを実行すると、既存の配列が指定した配列で置換されます。配列内の項目を個別に変更、追加、または削除することはできません。
読み取り / 変更 / 書き込みサイクルでのパッチの使用
パッチ リクエストを使用する場合は、まず部分的レスポンスで変更が必要なデータを取得することをおすすめします。これは特に、リソースで ETag が使用されている場合に重要です。このようなリソースを正しく更新するためには、HTTP ヘッダーの If-Match
で現在の ETag 値を指定する必要があるためです。データを取得した後で、変更する値を修正し、パッチ リクエストを使用して、修正した値を送り返すことができます。Demo リソースで ETag の使用を想定した例を次に示します。
GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics Authorization: Bearer your_auth_token
部分レスポンスは次のようになります。
200 OK
{ "etag": "ETagString" "title": "New title" "comment": "First comment.", "characteristics": { "length": "short", "level": "5", "followers": ["Jo", "Will"], } }
次のパッチ リクエストはレスポンスに基づくものです。また、下に示すように、fields
パラメータを使用して、パッチ レスポンスで返されるデータを限定しています。
PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics Authorization: Bearer your_auth_token Content-Type: application/json If-Match: "ETagString"
{ "etag": "ETagString" "title": "", /* Clear the value of the title by setting it to the empty string. */ "comment": null, /* Delete the comment by replacing its value with null. */ "characteristics": { "length": "short", "level": "10", /* Modify the level value. */ "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */ "accuracy": "high" /* Add a new characteristic. */ }, }
サーバーは 200 OK の HTTP ステータス コードで応答します。更新されたリソースの部分表現は次のようになります。
200 OK
{ "etag": "newETagString" "title": "", /* Title is cleared; deleted comment field is missing. */ "characteristics": { "length": "short", "level": "10", /* Value is updated.*/ "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */ "accuracy": "high" /* New characteristic is present. */ } }
パッチ リクエストを直接作成する方法
パッチ リクエストによっては、以前に取得したデータを基に作成しなければならないことがあります。たとえば、既存の配列要素をすべて残したまま配列に項目を追加する場合は、先に既存のデータを取得しておく必要があります。同様に、API で ETag が使用されている場合は、リクエストで変更前の ETag 値を送信してからでないと、リソースを正常に更新できません。
注: HTTP の "If-Match: *"
ヘッダーを使用して、ETag の使用中にパッチの実行を強制することができます。そうすることで、書き込みの前に読み取りを実行する必要がなくなります。
上記以外の場合は、既存のデータを先に取得せずにパッチ リクエストを直接作成することができます。たとえば、フィールドを新しい値に更新するパッチ リクエストや、新しいフィールドを追加するパッチ リクエストを簡単に作成できます。次に例を示します。
PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics Authorization: Bearer your_auth_token Content-Type: application/json { "comment": "A new comment", "characteristics": { "volume": "loud", "accuracy": null } }
このリクエストは、comment フィールドに値が設定されている場合は新しい値で上書きし、設定されていない場合は新しい値を設定します。また、characteristics に volume フィールドがある場合はその値を上書きし、ない場合はフィールドを作成します。accuracy フィールドが設定されている場合は、削除されます。
パッチへのレスポンスの処理
有効なパッチ リクエストが処理された後、API は 200 OK
の HTTP レスポンス コードと、変更されたリソースの完全な表現を返します。API で ETag が使用されている場合、サーバーは、パッチ リクエストが正常に処理されれば、PUT
の場合とまったく同様に ETag の値を更新します。
パッチ リクエストでは、リクエストから返されるデータ量を減らすために fields
パラメータを使用している場合を除き、リソースの完全な表現が返されます。
パッチ リクエストによって、リソースの状態が構文的または意味的に無効となる場合、サーバーは 400 Bad Request
または 422 Unprocessable Entity
の HTTP ステータス コードを返し、リソースの状態は変化しません。たとえば、必須フィールドの値を削除しようとした場合、サーバーはエラーを返します。
HTTP の PATCH 動詞がサポートされていない場合の代わりの表記法
ファイアウォールで HTTP の PATCH
リクエストが許可されていない場合は、HTTP の POST
リクエストを実行し、上書きヘッダーを PATCH
に設定します。次に例を示します。
POST https://www.googleapis.com/... X-HTTP-Method-Override: PATCH ...
パッチと更新の違い
HTTP の PUT
動詞を使用する更新リクエストのデータを送信する場合、送る必要があるのは必須またはオプションのフィールドのみです。サーバーによって設定されるフィールドのデータは、送信しても無視されます。そのため、この操作でも部分的更新を行えるように思えるかもしれませんが、この方法にはいくつかの制限事項があります。HTTP 動詞 PUT
を使用した更新では、必須パラメータを省略するとリクエストは失敗し、任意指定のパラメータを省略するとすでに設定済みのデータがクリアされてしまいます。
このため、処理の安全性はパッチを使用した方がはるかに高くなります。パッチでは、変更するフィールドのデータを指定するだけで済み、省略したフィールドのデータはクリアされません。ただし、唯一の例外として反復要素や反復配列があります。反復要素や反復配列をすべて省略した場合、それらはそのままの状態に保たれます。いずれかひとつでも指定した場合は、セット全体が指定したセットに置き換えられます。