Google 広告クエリ言語

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

リソースとその関連する属性、セグメント、指標を
GoogleAdsService Search または 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

このクエリは、ステータスが PAUSED でインプレッション数が 1, 000 を超えるキャンペーンのみをフィルタし、キャンペーン ID で並べ替えます。結果の 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 リファレンス ドキュメントをご覧ください。

クエリ結果に基づくミューテーション

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

  1. 現在 PAUSED でインプレッション数が 1,000 を超えるすべてのキャンペーンに対してクエリを実行します。
  2. レスポンス内の各 GoogleAdsRowcampaign フィールドから 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> は、リソース(customercampaign など)またはフィールド(campaign.idmetrics.impressionsad_group.id など)に置き換えることができます。

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

コードの例

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