Google 広告のクエリ言語

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

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

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

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

リソースの属性のクエリ

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

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

このクエリは、キャンペーン ID で並べ替えています。生成される各 GoogleAdsRow は、選択されたフィールドに入力された campaign オブジェクト(指定されたキャンペーン resource_name を含む)を表します。

キャンペーン クエリに使用できるその他のフィールドについては、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. レスポンス内の各 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 サンプルが含まれています。