パフォーマンス向上のヒント

このドキュメントでは、アプリケーションのパフォーマンスの向上に利用できるいくつかのテクニックについて説明します。わかりやすく説明するために他の API や汎用 API を例として使用する場合もありますが、Google アナリティクス API にも同じ考え方を応用することができます。

gzip の使用

gzip 圧縮を有効にすると、各リクエストが消費する帯域幅を手早く低減できます。圧縮を行うと展開が必要になる分 CPU 時間が長くなりますが、多くの場合、そのデメリットを大きく上回るネットワークコストの節約効果が得られます。

gzip でエンコードされたレスポンスを受け取るには、Accept-Encoding ヘッダーを設定し、ユーザーエージェントを変更して文字列 gzip を含める必要があります。gzip 圧縮を有効にする正しい HTTP ヘッダーの例を次に示します。

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

部分リソースを使用した作業

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

部分レスポンス

デフォルトでは、サーバーはリクエストを処理した後、リソースを完全な形で返します。パフォーマンスを向上させるため、本当に必要なフィールドだけを送信するようサーバーに指示し、代わりに「部分レスポンス」を取得することができます。

部分的レスポンスをリクエストするには、fields リクエストパラメータを使用して取得するフィールドを指定します。このパラメータは、レスポンスデータを返すすべてのリクエストで使用できます。

例

「Demo」という汎用（架空）の API での fields パラメータの使用例を次に示します。

通常のリクエスト: 次の 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` の値と、author の `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 では、これらのパラメータを使用して各クエリの結果を適切なサイズに制限してください。そうしないと、部分レスポンスによるパフォーマンスの向上が得られないことがあります。