Google 広告クエリ言語

Google 広告クエリ言語を使って、Google Ads API に対して次の点をクエリできます。

リソースとそれに関連する属性、セグメント、指標

GoogleAdsService [検索] または [SearchStream]

GoogleAdsService クエリの結果は、GoogleAdsRow インスタンスのリストです。各 GoogleAdsRow はリソースを表します。属性または指標がリクエストされた場合、行にはそれらのフィールドも含まれます。セグメントがリクエストされた場合、レスポンスにはセグメントリソースタプルごとに追加の行も表示されます。

使用可能なフィールドとリソースに関するメタデータ

GoogleAdsFieldService

このサービスでは、クエリ可能フィールドのカタログに、その互換性とタイプに関する詳細が提供されます。

GoogleAdsFieldService クエリの結果は GoogleAdsField インスタンスのリストで、各 GoogleAdsField にはリクエストされたフィールドの詳細が含まれています。

リソースの属性のクエリ

以下は、キャンペーンリソースの属性に対する基本クエリです。キャンペーン ID、名前、ステータスを返す方法を示しています。

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

このクエリは、キャンペーン ID で並べ替えます。結果の GoogleAdsRow はそれぞれ、選択したフィールド（特定のキャンペーンの resource_name を含む）が入力された campaign オブジェクトを表します。

キャンペーンクエリに使用できるその他のフィールドについては、Campaign リファレンスドキュメントをご覧ください。

指標のクエリ

特定のリソースに対して選択した属性とともに、関連する指標をクエリすることもできます。

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

このクエリは、キャンペーン ID で並べ替えて、ステータスが PAUSED でインプレッションが 1, 000 を超えるキャンペーンのみをフィルタします。結果として得られる各 GoogleAdsRow の metrics フィールドに、選択した指標が入力されます。

クエリ可能な指標の一覧については、Metrics のドキュメントをご覧ください。

セグメントのクエリ

特定のリソースの選択した属性とともに、関連するセグメントをクエリすることもできます。

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date during LAST_30_DAYS
ORDER BY campaign.id

このクエリでは、指標のクエリと同様に、ステータスが PAUSED でインプレッション数が 1,000 を超えているキャンペーンのみをフィルタします。ただし、このクエリではデータが日付別に分割されます。これにより、キャンペーンのタプルを表す各 GoogleAdsRow と日付 Segment が生成されます。セグメント化すると、選択した指標が分割され、SELECT 句の各セグメントでグループ化されることに注意してください。

クエリ可能なセグメントの一覧については、Segments のドキュメントをご覧ください。

クエリ結果に基づく変更

特定のリソースをクエリする際、返された結果をオブジェクトとしてすぐに取得して変更し、そのリソースのサービスの DoFn メソッドに返すことができます。ワークフローの例を以下に示します。

現在 PAUSED で、インプレッション数が 1,000 を超えているすべてのキャンペーンに対してクエリを実行します。
レスポンスの各 GoogleAdsRow の campaign フィールドから Campaign オブジェクトを取得します。
各キャンペーンのステータスを PAUSED から ENABLED に変更します。
変更したキャンペーンを使って CampaignService.MutateCampaigns を呼び出し、キャンペーンを更新します。

フィールドメタデータ

GoogleAdsFieldService に送信されるクエリは、フィールドメタデータを取得するためのものです。この情報を使用すると、クエリでフィールドをどのように組み合わせられるかを理解できます。データは API から利用でき、クエリの検証または作成に必要なメタデータが提供されるため、デベロッパーはプログラムでこの処理を行うことができます。メタデータの一般的なクエリは次のとおりです。

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

このクエリの <INSERT_RESOURCE_OR_FIELD> は、リソース（customer、campaign など）またはフィールド（campaign.id、metrics.impressions、ad_group.id など）に置き換えることができます。

クエリ可能なフィールドの一覧については、GoogleAdsField のドキュメントをご覧ください。

コードの例

クライアントライブラリには、GoogleAdsService で Google 広告クエリ言語を使用する例があります。基本オペレーションのフォルダには、GetCampaigns、GetKeywords、SearchForGoogleAdsFields などの例があります。reporting フォルダには GetKeywordStats の例があります。

クエリ文法