Google Ads 查詢語言

重要術語

資源
Google Ads 中的實體，例如 campaign 或 ad_group。
區隔
用來將資料分組的維度，例如 segments.date 或 segments.device。如果 SELECT 子句中包含區隔和指標，指標會依區隔拆分。
指標
成效評估指標，例如 metrics.impressions 或 metrics.clicks。
歸因資源
：在 FROM 子句中隱含加入主要資源的資源，可讓您選取其屬性以及主要資源屬性。

查詢資源或中繼資料資訊

Google Ads 查詢語言可查詢 Google Ads API，取得下列類型的資訊：

  • 使用 GoogleAdsService「Search」或「SearchStream」查詢資源及其相關屬性、區隔和指標：GoogleAdsService 查詢的結果是 GoogleAdsRow 執行個體清單，每個 GoogleAdsRow 代表一個資源。

    如果要求任何屬性或指標，資料列也會包含這些欄位。如果要求任何區隔，回應也會為每個區隔資源元組顯示額外資料列。

  • GoogleAdsFieldService 中可用欄位和資源的中繼資料：這項服務提供可查詢欄位的目錄，並列出相容性和類型的詳細資料。

    GoogleAdsFieldService 查詢結果會列出 GoogleAdsField 執行個體，每個 GoogleAdsField 都包含所要求欄位的詳細資料。

如要進一步瞭解查詢結構，請參閱「查詢結構」和「Google Ads 查詢語言文法」。

查詢資源屬性

以下是廣告活動資源屬性的基本查詢範例，說明如何傳回廣告活動 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

這項查詢只會篩選出狀態為 PAUSED 且曝光次數超過 1000 的廣告活動，並依廣告活動 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 且曝光次數超過 1000 的廣告活動。不過，這項查詢會依日期區隔資料。因此，每個產生的 GoogleAdsRow 都代表廣告活動和日期區隔的元組。區隔會分割所選指標，並依 SELECT 子句中的每個區隔分組。

如需可查詢的區隔清單，請參閱 Segments 說明文件。

在特定資源的查詢中，您可以彙整其他相關資源 (如有)。這些相關資源稱為「歸因資源」。您可以在查詢中選取屬性，隱含地彙整歸因資源。

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

這項查詢不僅會選取廣告活動屬性，還會從每個選取的廣告活動中擷取相關屬性。每個產生的 GoogleAdsRow 都代表一個 campaign 物件，其中填入了所選廣告活動屬性，以及所選出價策略屬性 bidding_strategy.name。

如要瞭解廣告活動查詢可用的歸因資源，請參閱 Campaign 參考文件。

最佳做法

  • 請只選取所需欄位，以免回應時間過長和逾時。
  • 在開發和測試期間使用 LIMIT，避免處理大型結果集。
  • 在 WHERE 子句中套用篩選器，盡量減少資料移轉和回應大小。
  • 建構複雜查詢前，請先使用 GoogleAdsFieldService 檢查欄位相容性和資料類型。
  • 請注意，某些欄位 (尤其是涉及大量資料或複雜計算的欄位) 可能會增加查詢成本。

根據查詢結果進行變異

查詢特定資源時，您可以立即將傳回的結果視為物件、修改這些物件，然後傳回該資源服務的變動方法。以下是工作流程範例：

  1. 針對曝光次數超過 1000 的所有 PAUSED 廣告活動執行查詢。
  2. 從回應中每個 GoogleAdsRow 的 campaign 欄位取得 Campaign 物件。
  3. 將每個廣告活動的狀態從「PAUSED」變更為「ENABLED」。
  4. 呼叫 CampaignService.MutateCampaigns，並提供修改後的廣告活動和對應的 FieldMask 來更新。

欄位中繼資料

傳送至 GoogleAdsFieldService 的查詢是用於擷取欄位中繼資料。這項資訊可用於瞭解如何在查詢中搭配使用欄位。由於資料可透過 API 取得，且 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 Ads 查詢語言語法、子句和運算子在所有支援的 Google Ads API 版本 (v23、v24、v25 和 v26) 中都相同，但可查詢的資源、區隔、指標和報表行為目錄會因主要版本而異。在目標 API 版本端點查詢 GoogleAdsFieldService，檢查該版本的欄位和相容性規則：

  • 最終到達網址擴展素材資源檢視畫面：
    • 購物廣告活動支援 (v26 以上版本)： final_url_expansion_asset_view 除了最高成效和搜尋廣告活動外，也支援購物廣告活動 (campaign.advertising_channel_type = 'SHOPPING')。如果是購物廣告活動，您可以選取 ad_group 欄位並依此篩選，但無法選取 asset_group 欄位。
    • 可選取的指標 (v25 以上版本)：查詢 final_url_expansion_asset_view 會傳回檢視畫面的所有可選取指標。在 v24 及更早版本中，回應僅包含最高成效廣告活動的 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 資源除了傳回購物、最高成效、需求開發和影片廣告活動的產品列，也會傳回應用程式廣告活動的產品列 (在 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 (僅在第 23 版中可選取)。
  • 精細日期回溯錯誤代碼：如果查詢依 segments.date、segments.week 或 segments.hour 區隔 (或篩選未滿一個月的日期範圍)，且超出 37 個月的回溯期，則在 v24 以上版本會傳回 DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED (在 v23 則傳回 DateRangeError.UNKNOWN)。詳情請參閱「日期範圍」。

程式碼範例

用戶端程式庫提供在 GoogleAdsService 中使用 Google Ads 查詢語言的範例。basic operations 資料夾包含 GetCampaigns、GetKeywords 和 SearchForGoogleAdsFields 等範例。

下一頁
查詢語法