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 提供資料，以及驗證或建構查詢所需的必要中繼資料，開發人員可以透過程式輔助方式執行這項操作。以下是中繼資料的典型查詢：

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 API 版本 (v23、v24 和 v25) 的 Google Ads 查詢語言語法、子句和運算子都相同，但可查詢的資源、區隔、指標和報表行為目錄會因主要版本而異。在目標 API 版本的端點查詢 GoogleAdsFieldService，檢查該版本的欄位和相容性規則：

  • 生命週期目標資源：在第 25 版和後續版本中，所有生命週期目標 (獲取新客、顧客留存率和會員留存率) 都會從統一的 goal 和 campaign_goal_config 資源查詢，取代 customer_lifecycle_goal 和 campaign_lifecycle_goal (在第 24 版和先前的版本中，這些資源與 goal 和 campaign_goal_config 一起用於獲取新客目標，而 goal 和 campaign_goal_config 則用於顧客留存率目標)。
  • 最終到達網址擴展素材資源檢視指標：在第 25 版和後續版本中，查詢 final_url_expansion_asset_view 會傳回檢視畫面的所有可選取指標。在第 24 版和更早版本中，回應只會包含最高成效廣告活動的 metrics.conversions 和 metrics.conversions_value，以及搜尋廣告活動的 metrics.impressions。
  • 應用程式廣告活動的購物產品報表：在第 24 版和後續版本中，shopping_product 資源除了購物、最高成效、需求開發和影片廣告活動外，也會傳回應用程式廣告活動的產品列 (在第 23 版中，應用程式廣告活動會從 shopping_product 結果中排除)。
  • 特定版本的資源、區隔和指標：
    • 第 25 版和後續版本：包含提升評估資源 (例如 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 (可在第 24 版和先前的版本中選取)。
    • 24 以上版本：包含 cart_data_sales_view 資源、segments.conversion_attribution_event_type (位於 shopping_performance_view)、segments.mobile_device_platform 和 segments.ad_network_type (位於 performance_max_placement_view)。移除 campaign.video_brand_safety_suitability (由 customer.video_brand_safety_suitability 取代)、segments.ad_sub_network_type (位於 campaign_budget 上) 和 segments.click_type (位於 ad_group_asset、campaign_asset 和 customer_asset 上，僅適用於 v23)。
  • 精細日期回溯錯誤代碼：查詢依 segments.date、segments.week 或 segments.hour 區隔 (或篩選每月以下日期範圍) 時，若超出 37 個月的回溯期，則在第 24 版以上會傳回 DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED (或在第 23 版中傳回 DateRangeError.UNKNOWN)。詳情請參閱「日期範圍」。

程式碼範例

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

下一頁
查詢語法