Google Ads 查詢語言

Google Ads 查詢語言可查詢 Google Ads API 的

資源及其相關屬性、區隔和指標
GoogleAdsService Search 或 SearchStream
GoogleAdsService 查詢的結果是 GoogleAdsRow 例項的清單，其中每個 GoogleAdsRow 都代表一個資源。如果要求任何屬性或指標，則資料列也會包含這些欄位。如果要求任何區隔，回應也會針對每個區隔-資源元組顯示額外的列。
關於可用欄位和資源的中繼資料
GoogleAdsFieldService

這項服務提供可查詢欄位的目錄，並說明這些欄位的相容性和類型。

GoogleAdsFieldService 查詢的結果是 GoogleAdsField 例項的清單，每個 GoogleAdsField 都包含要求欄位的詳細資料。

查詢資源的屬性

以下是廣告活動資源屬性的基本查詢，說明如何傳回廣告活動 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 且曝光次數超過 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 代表廣告活動和日期 Segment 的元組。請注意，區隔會將所選指標分割，並在 SELECT 子句中依各區隔分組。

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

在針對特定資源的查詢中，您可能可以與其他相關資源 (如有) 彙整。這些相關資源稱為「歸因資源」。您可以在查詢中選取屬性，以隱含方式彙整已指派屬性的資源。

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

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

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

根據查詢結果進行變異

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

  1. 針對目前為 PAUSED 且曝光次數超過 1000 的所有廣告活動執行查詢。
  2. 從回應中每個 GoogleAdsRow 的 campaign 欄位取得 Campaign 物件。
  3. 將各個廣告活動的狀態從「PAUSED」變更為「ENABLED」。
  4. 使用修改過的廣告活動呼叫 CampaignService.MutateCampaigns，即可更新廣告活動。

欄位中繼資料

傳送至 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 說明文件。

程式碼範例

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

下一頁
查詢文法