オブジェクトの取得

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

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

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

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

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

リクエストを作成する

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

• A: customer_id
• Google 広告クエリ言語の query。クエリするリソース、取得する属性、セグメント、指標のほか、返されるオブジェクトを制限するために使用する条件を示します。
• （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 広告の 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 行になります。