Google 広告クエリ言語

リソースまたはメタデータ情報をクエリする

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

  • GoogleAdsService Search または 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 は、キャンペーンの 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 を超えるキャンペーンをすべてクエリします。1. レスポンスの各 GoogleAdsRow の campaign フィールドから Campaign オブジェクトを取得します。1. 各キャンペーンのステータスを PAUSED から ENABLED に変更します。1. 変更したキャンペーンを使用して 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 などのサンプルがあります。

次へ
クエリ文法