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 のドキュメントをご覧ください。

特定のリソースのクエリで、他の関連リソースが利用可能であれば結合できることもあります。これらの関連リソースは、「関連付けされたリソース」と呼ばれます。クエリで属性を選択すると、関連付けられたリソースに対して暗黙的に結合できます。

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

このクエリでは、キャンペーン属性だけでなく、選択した各キャンペーンから関連属性も取得されます。結果として得られる GoogleAdsRow はそれぞれ、選択したキャンペーン属性と選択された入札戦略属性 bidding_strategy.name が入力された campaign オブジェクトを表します。

キャンペーン クエリで使用可能なアトリビューション リソースについては、Campaign リファレンス ドキュメントをご覧ください。

クエリ結果に基づく変更

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

  1. 現在 PAUSED で、インプレッション数が 1,000 を超えるすべてのキャンペーンにクエリを実行します。
  2. レスポンス内の各 GoogleAdsRow の campaign フィールドから Campaign オブジェクトを取得します。
  3. 各キャンペーンのステータスを PAUSED から ENABLED に変更します。
  4. 変更したキャンペーンで 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 のドキュメントをご覧ください。

コードの例

Google 広告のクエリ言語を GoogleAdsService で使用する際のクライアント ライブラリのサンプルをご確認ください。basic オペレーション フォルダには、GetCampaigns、GetKeywords、SearchForGoogleAdsFields などの例があります。reporting フォルダには GetKeywordStats のサンプルがあります。

次へ
クエリ文法