パフォーマンス向上

このドキュメントでは、アプリケーションのパフォーマンスを改善するための手法について説明します。アイデアを説明するために、他の実装された API の例が使用されている場合もあります。Display & Video 360 API にも同じ考え方を適用できます。

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

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

部分的レスポンス

デフォルトでは、サーバーはリクエストの処理後にリソースの完全な表現を返します。パフォーマンスを向上させるには、必要なフィールドのみを送信するようサーバーに指示し、代わりに部分レスポンスを取得する方法があります。

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

例

次のサンプルは、Display & Video 360 API での fields パラメータの使用方法を示しています。

シンプルなリクエスト: 次の HTTP GET リクエストでは fields パラメータを省略し、リソース全体を返します。

GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1

完全なリソース レスポンス: 完全なリソースデータには、次のフィールドが含まれます。わかりやすくするため、他の多くのフィールドは省略されています。

200 OK

{
 "advertisers": [
  {
   "name": "advertisers/1",
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  {
   "name": "advertisers/2",
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  ...
 ],
 "nextPageToken": "..."
}

部分的レスポンスのリクエスト: 同じリソースに対する次のリクエストでは、fields パラメータを使用して、返されるデータの量を大幅に減らしています。

GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)

部分レスポンス: 上記のリクエストに対するレスポンスとして、サーバーは簡潔にされた広告主配列を含むレスポンスを返します。この配列には、各広告主の広告主 ID、表示名、パートナー ID プロパティのみが含まれます（存在する場合）。

200 OK

{
 "advertisers": [
  {
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1"
  },
  {
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2"
  },
  ...
 ]
}

レスポンスは、選択したフィールドとそのフィールドを含む親オブジェクトのみを含む JSON オブジェクトです。

次に、fields パラメータの形式を設定する方法の詳細に続いて、レスポンスで返される内容について詳しく説明します。

fields パラメータの構文のまとめ

fields リクエスト パラメータ値の形式は、XPath 構文に大まかに準拠しています。以下に、サポートされている構文の要約を示します。また、次のセクションではその他の例を示します。

  • 複数のフィールドを選択するには、カンマ区切りのリストを使用します。

  • フィールド a 内にネストされているフィールド b を選択するには a/b と指定します。b 内にネストされているフィールド c を選択するには a/b/c と指定します。

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

    たとえば、fields=advertisers(advertiserId,generalConfig/domainUrl) は、advertisers 配列の各要素の広告主 ID とドメイン URL のみを返します。単一のサブフィールドを指定することもできます。ここで、fields=advertisers(advertiserId) は fields=advertisers/advertiserId と同じです。

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

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

返して欲しいフィールドを特定する（フィールド選択を行う）

fields リクエストのパラメータ値は、フィールドのカンマ区切りのリストです。各フィールドは、レスポンスのルートを基準として相対的に指定されます。したがって、list オペレーションを実行する場合、レスポンスはコレクションであり、通常はリソースの配列が含まれます。単一のリソースを返すオペレーションを実行する場合、フィールドはそのリソースからの相対位置で指定されます。選択したフィールドが配列である（または配列の一部である）場合、サーバーは、配列内のすべての要素の選択された部分を返します。

以下に、コレクション レベルの例を示します。

例 影響
advertisers advertisers 配列内のすべての要素（各要素のすべてのフィールドを含む）を返します。他のフィールドは返しません。
advertisers,nextPageToken nextPageToken フィールドと、advertisers 配列内のすべての要素の両方を返します。
advertisers/advertiserId advertisers 配列内のすべての要素の advertiserId のみを返します。

ネストされたフィールドが返されると、レスポンスには、そのフィールドを含む親オブジェクトが含まれます。明示的に選択しない限り、親フィールドには他の子フィールドは含まれません。
advertisers/generalConfig/domainUrl generalConfig オブジェクトの domainUrl フィールドを返します。このオブジェクト自体は advertisers 配列の下にネストされています。

以下に、リソースレベルの例を示します。

例 影響
advertiserId リクエストされたリソースの advertiserId フィールドを返します。
generalConfig/domainUrl リクエストされたリソースの generalConfig オブジェクトの domainUrl フィールドを返します。
部分選択を使用して個々のフィールドの一部のみをリクエストする

デフォルトでは、リクエストで特定のフィールドを指定すると、サーバーはオブジェクトまたは配列要素全体を返します。特定のサブフィールドのみを含むレスポンスを指定することもできます。これを行うには、次の例のように「( )」サブ選択構文を使用します。

例 影響
advertisers(advertiserId,generalConfig/domainUrl) advertisers 配列内の各要素について、advertiserId と generalConfig domainUrl の値のみを返します。
部分レスポンスの処理

サーバーは、fields クエリ パラメータを含む有効なリクエストを処理した後、リクエストされたデータとともに HTTP 200 OK ステータス コードを返します。fields クエリ パラメータにエラーがある場合や無効な場合、サーバーは HTTP 400 Bad Request ステータス コードと、フィールド選択の問題を示すエラー メッセージ（"Invalid field selection a/b" など）を返します。