パフォーマンス向上

このドキュメントでは、アプリケーションのパフォーマンスを向上させるためのテクニックをいくつか紹介します。場合によっては他の API や汎用 API を使用していますが、Resource Manager API にも同じ概念を適用できます。

gzip の使用

各リクエストに必要な帯域幅を削減するための簡単で便利な方法として、gzip 圧縮を有効にする方法があります。この方法では、結果を解凍するために CPU 時間が余分に必要になりますが、ネットワーク費用とのバランスを考えると、時間をかける価値は十分にあります。

gzip でエンコードされたレスポンスを受け取るには、2 つの準備作業が必要です。1 つは、Accept-Encoding ヘッダーを設定すること、もう 1 つは、ユーザー エージェントに gzip という文字列を追加することです。以下に、gzip 圧縮を有効にするための正しい形式の HTTP ヘッダーの例を示します。

Accept-Encoding: gzip
User-Agent: my program (gzip)

部分リソースを使用する

API 呼び出しのパフォーマンスを向上させるためのもう 1 つの方法は、データの必要な部分のみをリクエストすることです。これにより、アプリケーションが不要なフィールドを転送、解析、保存することがなくなるため、ネットワーク、CPU、メモリなどのリソースをより効率的に使用できます。

部分レスポンス

デフォルトでは、サーバーは、リクエストを処理した後、リソース全体を返します。パフォーマンスを向上させるには、必要なフィールドのみを送信するようサーバーに要求して、部分レスポンスを受信します。

部分レスポンスをリクエストするには、fields リクエスト パラメータを使って必要なフィールドを指定します。このパラメータは、レスポンス データを返すどのリクエストにも指定できます。

以下の例では、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)

部分レスポンス: 上記のリクエストに対するレスポンスとして、サーバーは、種類情報、各アイテムの HTML タイトルと長さのみを含む削減されたアイテム配列が格納されたレスポンスを返します。

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 と指定します。

    例外: data ラッパーを使用する API レスポンスの場合、data: { ... } のように data オブジェクト内にレスポンスがネストされます。この場合は、fields 仕様に data を含めないでください。data/a/b のように、fields 指定に data オブジェクトを含めるとエラーになります。そうした場合は、a/b のように単に fields 指定を使用してください。

  • サブセレクタを使用して特定の配列またはオブジェクトのサブフィールドのセットをリクエストするには、式をかっこ( )で囲みます。

    たとえば、fields=items(id,author/email) と指定すると、items 配列内の各要素について、アイテム ID と作者のメールアドレスのみが返されます。サブフィールドは 1 つだけでもかまいません。たとえば、fields=items(id) と指定するのと、fields=items/id と指定するのは等価です。

  • 必要に応じて、フィールドの選択にワイルドカードを使用します。

    たとえば、fields=items/pagemap/* と指定すると、ページマップ内のすべてのオブジェクトが選択されます。

fields パラメータのその他の使用例

以下にいくつか例を挙げて、fields パラメータ値がレスポンスに与える影響を説明します。

注: すべてのクエリ パラメータ値と同様に、fields パラメータ値も URL エンコードされている必要があります。このドキュメントの例では、読みやすさを優先してエンコーディングを省略しています。

返して欲しいフィールドを特定する(フィールド選択を行う)
fields リクエスト パラメータ値はフィールドのカンマ区切りリストであり、各フィールドは、レスポンスのルートからの相対位置で指定します。したがって、リスト オペレーションを実行する場合、レスポンスは通常、リソースの配列が格納されたコレクションです。単一のリソースを返すオペレーションを実行する場合、各フィールドは当該リソースからの相対位置で指定します。選択したフィールドが配列(または配列の一部)である場合、サーバーは、配列内のすべての要素について、選択された部分を返します。

以下に、コレクション レベルの例を挙げます。
効果
items items 配列内のすべての要素を返します。各要素内のすべてのフィールドが含まれますが、その他のフィールドは含まれません。
etag,items etag フィールド、および items 配列内のすべての要素を返します。
items/title 配列内のすべての要素について、title フィールドのみを返します。

ネストされたフィールドが返されると、レスポンスには、そのフィールドを含む親オブジェクトが毎回含まれます。親フィールド内のその他の子フィールドは、明示的に選択されていない限り含まれません。
context/facets/label label 配列(この配列自体も facets オブジェクト内にネストされている)のすべてのメンバーについて、context フィールドのみを返します。
items/pagemap/*/title items 配列内の各要素について、title のすべての子オブジェクトの pagemap フィールド(存在する場合)のみを返します。

以下に、リソースレベルの例を挙げます。
効果
title リクエストされたリソースの title フィールドを返します。
author/uri リクエストされたリソースの uri オブジェクトの author サブフィールドを返します。
links/*/href
href のすべての子オブジェクトの links フィールドを返します。
部分選択を使用して個々のフィールドの一部のみをリクエストします。
デフォルトでは、リクエストに特定のフィールドを指定すると、サーバーは、オブジェクト全体または配列要素全体を返します。こうした場合に、特定のサブフィールドのみを含むレスポンスを指定することもできます。それには、"( )" 部分選択構文を使用します。以下に例を示します。
効果
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"
    }
  },
  ...
  ]
}

注: データをページ分割するためのクエリ パラメータ(maxResultsnextPageToken など)をサポートしている API では、それらのパラメータを使用して、各クエリの結果のサイズを管理可能なサイズまで削減してください。そうしないと、部分レスポンスによるパフォーマンスの向上が得られないことがあります。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Resource Manager のドキュメント