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

このクエリでは、キャンペーン 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 広告クエリ言語を使用するサンプルがあります。たとえば、[基本的なオペレーション] フォルダには GetCampaigns、GetKeywords、SearchForGoogleAdsFields などのサンプルが、

次へ
クエリ文法