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 行が生成されます。