このページは Cloud Translation API によって翻訳されました。

Google 広告のクエリ言語

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

リソースと関連する属性、セグメント、指標

GoogleAdsService 検索または検索ストリーム

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 のドキュメントをご覧ください。

クエリ結果に基づいて変更を行う

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

現在 PAUSED で表示回数が 1,000 回を超えるキャンペーンに対してクエリを実行します。
レスポンス内の各 GoogleAdsRow の campaign フィールドから Campaign オブジェクトを取得します。
各キャンペーンのステータスを PAUSED から ENABLED に変更します。
キャンペーンを変更するために、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、GetArtifactMetadata などの例があります。reporting フォルダには GetKeywordStats のサンプルがあります。

クエリ文法