オブジェクトの取得

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

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

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

  • GoogleAdsService.SearchStream は、1 つのストリーミング レスポンスですべての行を返します。これは、結果セットが大きい（10,000 行を超える）場合に効率的です。これは、バッチ アプリケーションでできるだけ多くのデータをできるだけ早くダウンロードする場合に適しています。
  • GoogleAdsService.Search は、大きなレスポンスを管理可能な結果ページに分割します。これは、インタラクティブ アプリケーションで一度に結果のページを表示する場合に適しています。

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

リクエストを作成する

search メソッドには SearchGoogleAdsRequest が必要です。これは次の属性で構成されています。

  • A: customer_id
  • Google 広告クエリ言語の query。クエリするリソース、取得する属性、セグメント、指標のほか、返されるオブジェクトを制限するために使用する条件を示します。
  • （GoogleAdsService.Search のみ）ページングの使用時に単一のレスポンスで返すオブジェクト数を示す page_size。
  • （GoogleAdsService.Search のみ）ページングの使用時に結果の次のバッチを取得する page_token（省略可）。

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

レスポンスを処理する

GoogleAdsService は GoogleAdsRow オブジェクトのリストを返します。

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

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

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

不明な列挙型

UNKNOWN のタイプで返されるリソースは、その API バージョンでは完全にサポートされていません。これらのリソースは、Google 広告の管理画面など、他のインターフェースで作成された可能性があります。リソースのタイプが UNKNOWN の場合、指標を選択できますが、API を使用してリソースを変更することはできません。たとえば、UI で導入された新しいキャンペーンや広告が、クエリを実行する API バージョンではサポートされていない場合です。

次の点にご注意ください。

  • UNKNOWN タイプのリソースは、後でサポートされる場合もあれば、無期限に UNKNOWN のままになる場合もあります。
  • UNKNOWN 型の新しいオブジェクトはいつでも表示できます。これらのオブジェクトは、列挙型の値がすでに使用可能であるため、下位互換性があります。リソースは、アカウントの正確な状況を把握できるように、この変更に伴い導入されます。UNKNOWN リソースは、他のインターフェースを介したアカウントの新しいアクティビティや、リソースがサポートされなくなった場合に表示されます。
  • UNKNOWN リソースには、クエリ可能な詳細な指標を関連付けることができます。
  • UNKNOWN リソースは通常、Google 広告の UI にすべて表示されます。
  • 通常、UNKNOWN リソースは変更できません。

セグメンテーション

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

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

たとえば、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 行になります。

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