このドキュメントでは、アプリケーションのパフォーマンスを向上させるためのテクニックをいくつか説明します。場合によっては他の API や汎用 API を使用していますが、Google Photos Library API にも同じ概念が適用されます。
gzip を使用した圧縮
各リクエストに必要な帯域幅を削減するための簡単で便利な方法として、gzip 圧縮を有効にする方法があります。この方法では、結果を解凍するために CPU 時間が余分に必要になりますが、ネットワーク費用とのバランスを考えると、時間をかける価値は十分にあります。
gzip でエンコードされたレスポンスを受け取るには、2 つの準備作業が必要です。1 つは、Accept-Encoding
ヘッダーを設定すること、もう 1 つは、ユーザー エージェントに gzip
という文字列を追加することです。以下に、gzip 圧縮を有効にするための正しい形式の HTTP ヘッダーの例を示します。
Accept-Encoding: gzip User-Agent: my program (gzip)
部分リソースを使用した作業
リクエストするデータを必要な部分のみに限定して API 呼び出しのパフォーマンスを向上させる方法もあります。こうすると、アプリケーションで不要なフィールドの転送、解析、保存を行う必要がなくなるため、ネットワーク、CPU、メモリなどのリソースを効率良く利用できるようになります。
部分レスポンス
デフォルトでは、サーバーはリクエストを処理した後、リソースを完全な形で返します。パフォーマンスを向上させるには、サーバーが必要なフィールドのみを送信し、それによって部分レスポンスを取得するように指定します。
部分レスポンスをリクエストするには、fields
リクエスト パラメータを使用して取得するフィールドを指定します。このパラメータは、レスポンス データを返す任意のリクエストで使用できます。
例
以下の例では、fields
パラメータの使い方を汎用的な(架空の)Demo API を用いて示します。
シンプルなリクエスト: 次の HTTP GET
リクエストでは fields
パラメータを省略し、リソース全体を取得します。
https://www.googleapis.com/demo/v1
全リソース レスポンス: 全リソースデータには以下のフィールドが含まれます(他にも多くのフィールドがありますが簡略化するため一部のみ表示しています)。
{ "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?fields=kind,items(title,characteristics/length)
部分レスポンス: サーバーは上記のリクエストに対し、種類情報と情報が削減されたアイテム配列のみからなるレスポンスを返します。アイテム配列の各アイテムには HTML タイトルと長さ特性情報のみが含まれます。
200 OK
{ "kind": "demo", "items": [{ "title": "First title", "characteristics": { "length": "short" } }, { "title": "Second title", "characteristics": { "length": "long" } }, ... ] }
レスポンスとして返されるのは、選択したフィールドとそのフィールドが属する親オブジェクトのみを含む JSON オブジェクトです。
次のセクションで、fields
パラメータの形式の指定方法について説明し、さらにその後に、レスポンスとして返される具体的な内容について詳細に説明します。
fields パラメータの構文のまとめ
fields
リクエスト パラメータの形式は、XPath の構文に基づいています。サポートされている構文を以下にまとめます。その後のセクションで追加の例を挙げて説明します。
- 複数のフィールドを選択するには、カンマ区切りのリストを使用します。
- Use フィールド
a
内にネストされているフィールドb
を選択するにはa/b
と指定します。b
内にネストされているフィールドc
を選択するにはa/b/c
と指定します。
例外: データラッパーを使用する API レスポンスは、
data: { ... }
のようにdata
オブジェクト内にネストされているので、fields
の指定にdata
を含めません。data/a/b
のように、fields の指定に data オブジェクトを含めるとエラーになります。この場合は、fields
をa/b
のように指定してください。 - サブセレクタを使用して特定の配列またはオブジェクトのサブフィールドのセットをリクエストするには、式をかっこ「
( )
」で囲みます。たとえば、
fields=items(id,author/email)
と指定すると、items 配列内の各要素について、アイテム ID と作者のメールアドレスのみが返されます。サブフィールドは 1 つだけでもかまいません。たとえば、fields=items(id)
と指定するのとfields=items/id
と指定するのは同じことです。 - 必要に応じて、フィールドの選択にワイルドカードを使用します。
たとえば
fields=items/pagemap/*
とすると、pagemap のすべてのオブジェクトが選択されます。
fields パラメータのその他の使用例
以下にいくつか例を挙げて、fields
パラメータ値がレスポンスに与える影響を説明します。
注: 他のすべてのクエリ パラメータの値と同じように、fields
パラメータ値には URL エンコードを使用する必要があります。このドキュメントの例では、読みやすさを優先してエンコードを省略しています。
- 返して欲しいフィールドを特定する(フィールド選択を行う)
fields
リクエスト パラメータ値はフィールドのカンマ区切りのリストであり、各フィールドは、レスポンスのルートからの相対位置で指定します。したがって、リスト オペレーションを実行する場合、レスポンスは通常、リソースの配列が格納されたコレクションです。単一のリソースを返すオペレーションを実行する場合、各フィールドは当該リソースからの相対位置で指定します。選択したフィールドが配列(または配列の一部)である場合、サーバーは、配列内のすべての要素について、選択された部分を返します。
以下に、コレクション レベルの例を挙げます。
例 効果 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?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 では、こうしたパラメータを使用して各クエリの結果を適切なサイズに制限してください。そうしないと、部分レスポンスによるパフォーマンスの向上が得られないことがあります。