オブジェクトの取得

GoogleAdsService は、Google Ads API の統合されたオブジェクト取得およびレポート サービスです。このサービスには、次のメソッドがあります。

  • オブジェクトの特定の属性を取得する。
  • 期間に基づいてオブジェクトのパフォーマンス指標を取得します。
  • 属性に基づいてオブジェクトを並べ替えます。
  • 条件を使用して、レスポンスで返すオブジェクトを指定します。
  • 返されるオブジェクトの数を制限します。

GoogleAdsService は、次の 2 つの方法で結果を返すことができます。

  • GoogleAdsService.SearchStream は、すべての行を 1 つのストリーミング レスポンスで返します。これは、大規模な（10,000 行を超える）結果セットに対してより効率的です。これは、アプリケーションが完全な結果セットをダウンロードする場合や、行をストリームとして処理する場合におすすめです。
  • GoogleAdsService.Search は、大きなレスポンスを管理しやすい結果ページに分割します。これは、インタラクティブなアプリケーションで一度に 1 ページの結果を表示する場合に便利です。

ページングとストリーミングの詳細を確認する。

リクエストを作成する

GoogleAdsService.SearchStream は SearchGoogleAdsStreamRequest を想定し、GoogleAdsService.Search は SearchGoogleAdsRequest を想定しています。どちらのリクエスト タイプにも、次のものが含まれます。

  • A: customer_id
  • Google 広告クエリ言語の query。クエリ対象のリソース、取得する属性、セグメント、指標、返されるオブジェクトを制限するために使用する条件を指定します。

メソッドによっては、リクエストでメソッド固有のフィールドもサポートされます。

  • SearchGoogleAdsStreamRequest（SearchStream のみ）:
    • 集計指標を含むサマリー行をリクエストするオプションの summary_row_setting
  • SearchGoogleAdsRequest（Search のみ）:
    • ページングを使用するときに、次の結果バッチを取得するためのオプションの page_token（page_size は 10,000 行に固定されています。リクエストで page_size を設定すると、RequestError.PAGE_SIZE_NOT_SUPPORTED エラーがスローされます）。
    • return_summary_row、return_total_results_count、omit_results を構成するオプションの search_settings メッセージ
    • クエリを実行せずに検証するためのオプションの validate_only ブール値

Google 広告クエリ言語の詳細については、Google 広告クエリ言語ガイドをご覧ください。

レスポンスを処理する

GoogleAdsService は、GoogleAdsRow オブジェクトのリストを返します（ストリーミングされた SearchGoogleAdsStreamResponse バッチ内、またはページ分けされた SearchGoogleAdsResponse 内）。

各 GoogleAdsRow は、クエリによって返されるオブジェクトを表し、SELECT 句でリクエストされたフィールドに基づいて入力される属性のセットで構成されます。SELECT 句に含まれていない属性は、レスポンスの GoogleAdsRow オブジェクトに入力されません。

たとえば、ad_group_criterion には status 属性がありますが、SELECT 句に ad_group_criterion.status が含まれていないクエリのレスポンスでは、行の ad_group_criterion 属性の status フィールドは入力されません。同様に、SELECT 句に campaign リソースのフィールドが含まれていない場合、行の campaign 属性は入力されません。

各 GoogleAdsRow には、同じ結果セット内の別の行とは異なる属性と指標を設定できます。そのため、行はテーブルの固定行ではなく、オブジェクトとして表示する必要があります。

UNKNOWN および UNSPECIFIED 列挙型

列挙値 UNKNOWN で返されるリソースは、その API バージョンでは完全にはサポートされていません。一方、UNSPECIFIED は、列挙型フィールドが設定されていないか、SELECT 句でリクエストされていないことを示します。UNKNOWN 列挙値を持つリソースは、Google 広告の管理画面など、他のインターフェースで作成された可能性があります。リソースのタイプが UNKNOWN の場合は指標を選択できますが、API を介してリソースを変更することはできません。たとえば、UI で利用可能なキャンペーン タイプや広告タイプが、クエリ対象の API バージョンでサポートされていない場合などです。

ここでは、重要な考慮事項について説明します。

  • UNKNOWN タイプのリソースは、後の API バージョンでサポートされるか、無期限に UNKNOWN のままになる可能性があります。
  • UNKNOWN タイプの新しいオブジェクトはいつでも表示される可能性があります。これらのオブジェクトは、API のすべての列挙型に UNKNOWN 列挙値が存在するため、下位互換性があります。リソースは UNKNOWN とともに返されるため、アカウントの全体的なパフォーマンス指標を正確に把握できます。
  • UNKNOWN リソースには、クエリ可能な詳細な指標を関連付けることができます。
  • UNKNOWN リソースは通常、Google 広告の UI に完全に表示されます。
  • UNKNOWN リソースは通常、API を介して変更できません。

セグメンテーション

レスポンスには、次の組み合わせごとに 1 つの GoogleAdsRow が含まれます。

  • FROM 句で指定されたメインリソースのインスタンス
  • 選択した各 segments フィールドの値

たとえば、FROM campaign を選択し、SELECT 句に segments.ad_network_type と segments.date を含むクエリのレスポンスには、次の組み合わせごとに 1 行が含まれます。

  • campaign
  • segments.ad_network_type
  • segments.date

結果は、選択した個々のフィールドの値ではなく、メインリソースの各インスタンスによって暗黙的にセグメント化されます。次に例を示します。

SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

campaign.status フィールドの個別の値ごとに 1 行ではなく、キャンペーンごとに 1 行になります。

前へ
オブジェクトの変更
次へ
リソース メタデータ