オブジェクトの取得

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

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

GoogleAdsService は、 次の 2 つの方法で結果を返します。

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

ページングとストリーミングの詳細をご覧ください。

リクエストを作成する

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

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

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

レスポンスを処理する

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

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

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

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

UNKNOWN 列挙型

タイプが UNKNOWN のリソースは、その API バージョンでは完全にサポートされていません。これらのリソースは、Google 広告の UI などの他のインターフェースで作成された可能性があります。リソースのタイプが 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 ごとに 1 行になり、 campaign.status フィールドの別々の値ごとに 1 つの行にはなりません。