オブジェクトの取得

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

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

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

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

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

リクエストを作成する

検索メソッドには、次の属性で構成される SearchGoogleAdsRequest が必要です。

• A: customer_id
• Google 広告クエリ言語の query。クエリ対象のリソース、取得する属性、セグメント、指標、返されるオブジェクトを制限するために使用する条件を指定します。
• （GoogleAdsService.Search のみ）ページングの使用時に 1 つのレスポンスで返すオブジェクトの数を示す 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 列挙型

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

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

• UNKNOWN タイプのリソースは、後でサポートすることも、UNKNOWN を無期限にすることもできます。
• UNKNOWN タイプの新しいオブジェクトはいつでも表示できます。これらのオブジェクトには、列挙値がすでに使用可能であるため、下位互換性があります。この変更に伴い、利用可能になったリソースも導入されるため、アカウントを正確に把握できます。UNKNOWN リソースは、他のインターフェースを通じてアカウントで新しいアクティビティが行われた場合や、リソースのサポートが終了した場合に、表示されることがあります。
• UNKNOWN リソースには、クエリ可能な詳細な指標を関連付けることができます。
• UNKNOWN リソースは通常、Google 広告の管理画面にすべて表示されます。
• 通常、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 行が生成されます。