このページは Cloud Translation API によって翻訳されました。

API の使用に関するヒント

このドキュメントでは、アプリケーションのパフォーマンスを向上させるためのテクニックをいくつか説明します。場合によっては他の API や汎用 API を使用していますが、ただし、Google Search Console 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 では、こうしたパラメータを使用して各クエリの結果を適切なサイズに制限してください。そうしないと、部分レスポンスによるパフォーマンスの向上が得られないことがあります。