Google 広告クエリ言語

主な用語

リソース
Google 広告のエンティティ（campaign、ad_group など）。
セグメント
データをグループ化するために使用されるディメンション（segments.date、segments.device など）。セグメントが指標とともに SELECT 句に含まれている場合、指標はセグメントごとに分割されます。
指標
パフォーマンスの測定値（metrics.impressions、metrics.clicks など）。
アトリビューション リソース
FROM 句のメインリソースに暗黙的に結合されるリソース。メインリソースの属性とともにその属性を選択できます。

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

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

  • GoogleAdsService の Search または SearchStream を使用するリソースと、それに関連する属性、セグメント、指標: GoogleAdsService クエリの結果は GoogleAdsRow インスタンスのリストで、各 GoogleAdsRow はリソースを表します。

    属性または指標がリクエストされた場合、行にはそれらのフィールドも含まれます。セグメントがリクエストされた場合、レスポンスにはセグメントとリソースの組み合わせごとに追加の行が表示されます。

  • GoogleAdsFieldService で使用可能なフィールドとリソースに関するメタデータ: このサービスは、クエリ可能なフィールドのカタログを提供し、その互換性とタイプに関する詳細情報を提供します。

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

クエリ構造の詳細については、クエリ構造と Google 広告クエリ言語の文法をご覧ください。

リソース属性をクエリする

キャンペーン リソースの属性を対象とした基本的なクエリの例を以下に示します。このクエリでは、キャンペーンの 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

このクエリでは、ステータスが PAUSED で、インプレッション数が 1, 000 を超えるキャンペーンのみをフィルタし、キャンペーン ID で並べ替えます。結果の各 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 は、キャンペーンと日付セグメントのタプルを表します。セグメント化すると、選択した指標が分割され、SELECT 句の各セグメントでグループ化されます。

クエリ可能なセグメントの一覧については、Segments のドキュメントをご覧ください。

特定のリソースに対するクエリでは、他の関連リソースが利用可能であれば、それらのリソースと結合できます。これらの関連リソースは「属性リソース」と呼ばれます。クエリで属性を選択することで、属性付きリソースに暗黙的に結合できます。

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

このクエリは、キャンペーン属性を選択するだけでなく、選択した各キャンペーンから関連する属性も取得します。結果として得られる各 GoogleAdsRow は、選択したキャンペーン属性と、選択した入札戦略属性 bidding_strategy.name が入力された campaign オブジェクトを表します。

キャンペーン クエリで使用できる属性リソースについては、Campaign のリファレンス ドキュメントをご覧ください。

ベスト プラクティス

  • レスポンス時間が長くなったり、タイムアウトが発生したりしないように、必要なフィールドのみを選択します。
  • 開発とテストの際は、LIMIT を使用して、大規模な結果セットを処理しないようにします。
  • WHERE 句にフィルタを適用して、データ転送とレスポンス サイズを最小限に抑えます。
  • 複雑なクエリを作成する前に、GoogleAdsFieldService を使用してフィールドの互換性とデータ型を確認します。
  • 一部のフィールド、特に大量のデータや複雑な計算を伴うフィールドは、クエリ費用を増加させる可能性があることに注意してください。

クエリ結果に基づいて変更する

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

  1. インプレッション数が 1,000 を超えるすべての PAUSED キャンペーンに対してクエリを実行します。
  2. レスポンスの各 GoogleAdsRow の campaign フィールドから Campaign オブジェクトを取得します。
  3. 各キャンペーンのステータスを PAUSED から ENABLED に変更します。
  4. 変更したキャンペーンと対応する FieldMask を指定して 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 のドキュメントをご覧ください。

バージョン固有の違い

Google 広告クエリ言語の構文、句、演算子は、サポートされているすべての Google Ads API バージョン（v23、v24、v25、v26）で同じですが、クエリ可能なリソース、セグメント、指標、レポート動作のカタログはメジャー バージョンによって異なります。ターゲット API バージョンのエンドポイントで GoogleAdsFieldService をクエリして、そのバージョンのフィールドと互換性ルールを検査します。

  • 最終ページ URL の拡張のアセットビュー:
    • ショッピング キャンペーンのサポート（v26 以降）: final_url_expansion_asset_view は、P-MAX キャンペーンと検索キャンペーンに加えて、ショッピング キャンペーン（campaign.advertising_channel_type = 'SHOPPING'）をサポートしています。ショッピング キャンペーンでは、ad_group フィールドを選択してフィルタできますが、asset_group フィールドは選択できません。
    • 選択可能な指標（v25 以降）: final_url_expansion_asset_view をクエリすると、ビューで選択可能なすべての指標が返されます。v24 以前では、レスポンスには P-MAX キャンペーンの metrics.conversions と metrics.conversions_value、検索キャンペーンの metrics.impressions のみが含まれます。
  • ライフサイクル目標のリソース: v25 以降では、すべてのライフサイクル目標（新規顧客の獲得、顧客維持、ロイヤルティ維持）が、統合された goal リソースと campaign_goal_config リソースからクエリされます。customer_lifecycle_goal と campaign_lifecycle_goal（v24 以前では、顧客維持目標の goal と campaign_goal_config とともに、新規顧客の獲得目標に使用されていました）は置き換えられます。
  • アプリ キャンペーンのショッピング商品レポート: v24 以降では、shopping_product リソースは、ショッピング キャンペーン、P-MAX キャンペーン、デマンド ジェネレーション キャンペーン、動画キャンペーンに加えて、アプリ キャンペーンの商品行を返します（v23 では、アプリ キャンペーンは shopping_product の結果から除外されます）。
  • バージョン固有のリソース、セグメント、指標:
    • v26 以降: search_lift_keyword_bundle リソース、campaign.lift_measurement_config、local_services_lead.campaign、segments.search_lift_keyword_bundle、segments.search_property、検索数の増加に関する指標（metrics.relative_search_lift、metrics.normalized_incremental_searches、metrics.search_lift_cost_micros、metrics.search_lift_impressions など）が含まれます。
    • v25 以降: リフト測定リソース（lift_measurement_config など）、セグメント（segments.ad_sub_format_type、segments.loyalty_membership など）、YouTube エンゲージメント指標（metrics.youtube_likes、metrics.youtube_comments、metrics.youtube_shares）が含まれます。local_services_lead.contact_details.email（v24 以前で選択可能）が削除されます。
    • v24 以降: cart_data_sales_view リソース、shopping_performance_view の segments.conversion_attribution_event_type、segments.mobile_device_platform、performance_max_placement_view の segments.ad_network_type が含まれます。campaign.video_brand_safety_suitability（customer.video_brand_safety_suitability に置き換え）、campaign_budget の segments.ad_sub_network_type、ad_group_asset、campaign_asset、customer_asset の segments.click_type（v23 でのみ選択可能）を削除します。
  • 詳細な日付ルックバック エラーコード: 37 か月のルックバック ウィンドウを超えて segments.date、segments.week、segments.hour でセグメント化する（または 1 か月未満の日付範囲でフィルタする）クエリは、v24 以降では DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED（v23 では DateRangeError.UNKNOWN）を返します。詳しくは、期間をご覧ください。

コードの例

クライアント ライブラリには、GoogleAdsService で Google 広告クエリ言語を使用する例が用意されています。basic operations フォルダには、GetCampaigns、GetKeywords、SearchForGoogleAdsFields などの例があります。

次へ
クエリ文法