Google 広告のクエリ言語

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

リソースとその関連属性、セグメント、指標
GoogleAdsService 検索または SearchStream
GoogleAdsService のクエリの結果は GoogleAdsRow インスタンスのリストであり、各 GoogleAdsRow はリソースを表します。属性や指標がリクエストされた場合、行にはそれらのフィールドも含まれます。セグメントがリクエストされると、セグメント タプルごとに行も追加されます。
使用可能なフィールドとリソースに関するメタデータ
GoogleAdsFieldService

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

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

リソースの属性のクエリ

以下は、キャンペーン ID の属性の基本的なクエリであり、キャンペーン 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 のドキュメントをご覧ください。

コードの例

クライアント ライブラリには、GoogleAdsService の Google 広告クエリ言語を使用した例があります。basic operations フォルダには、GetCampaigns、GetKeywords、SearchForGoogleAdsFields などの例があります。reporting フォルダには GetKeywordStats のサンプルがあります。

次へ
クエリ文法