Directory API: パフォーマンスに関するヒント

このドキュメントでは、アプリケーションのパフォーマンスを向上させるための手法について説明します。わかりやすく説明するために他の API や汎用 API を例として使用する場合もありますが、Admin SDK 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)

部分レスポンス: サーバーは、上記のリクエストに対するレスポンスで、種類情報(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/a/b のように、fields の指定に data オブジェクトを含めるとエラーになります。この場合は、fieldsa/b のように指定してください。

  • 配列またはオブジェクトの特定のサブフィールド セットをリクエストする場合は、サブセレクタを使用し、かっこ「( )」の中に式を記述する。

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

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

    たとえば fields=items/pagemap/* とすると、pagemap のすべてのオブジェクトが選択されます。

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

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

注: 他のすべてのクエリ パラメータの値と同じように、fields パラメータ値には URL エンコードを使用する必要があります。読みやすくするために、このドキュメントの例ではエンコードを省略します。

取得するフィールドを特定する(フィールド選択を行う)
fields リクエスト パラメータ値はフィールドのカンマ区切りのリストであり、各フィールドは、レスポンスのルートからの相対位置で指定します。そのため、list 操作を実行した場合、レスポンスはコレクションとなり、通常はリソースの配列が含まれます。1 つのリソースを取得する操作を実行する場合は、そのリソースを基準位置としてフィールドを指定します。選択したフィールドが配列または配列の一部である場合、サーバーはその配列の選択された部分のすべての要素を返します。

以下はコレクション レベルの例です。
効果
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?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 では、こうしたパラメータを使用して各クエリの結果を適切なサイズに制限してください。そうしないと、部分レスポンスによるパフォーマンスの向上が得られないことがあります。