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

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

目次

  1. gzip の使用
  2. 部分的リソースの使用
    1. 部分的レスポンス

gzip の使用

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

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

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

部分的リソースの使用

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

部分的レスポンス

デフォルトでは、サーバーはリクエストを処理した後、リソースを完全な形で返します。パフォーマンスを向上するには、その代わりにサーバーに必要なフィールドのみを送信するよう指定し、部分的レスポンスを取得するように指定します。

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

次の例では、「デモ」という架空の汎用 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 と作者の 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 では、これらのパラメータを使用して各クエリの結果を適切なサイズに制限してください。そうしないと、部分的レスポンスで可能なパフォーマンスの向上が達成されない場合があります。

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