オブジェクトの取得

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

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

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

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

詳しくは、ページングとストリーミングをご覧ください。

リクエストを作成する

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 を介してリソースを変更することはできません。たとえば、クエリを実行している API バージョンではサポートされていないキャンペーン タイプや広告タイプが UI で利用できる場合などです。

次の点に注意してください。

• 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 行の結果が返されます。