Google Ads 查詢語言

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Google Ads 查詢語言可以向 Google Ads API 查詢

資源及其相關屬性、區隔和指標。
GoogleAdsService 搜尋SearchStream
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

這項查詢只會篩選處於 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 狀態且曝光次數超過 1000 次的廣告活動;不過,這項查詢是按日期區隔資料。這會導致每個產生的 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 參考說明文件

根據查詢結果進行變動

查詢特定資源時,您可以立即將傳回的結果視為物件並進行修改,然後將結果傳回該資源的服務中的 var 方法。以下是工作流程範例:

  1. 針對目前是 PAUSED 且曝光次數超過 1000 的所有廣告活動執行查詢。
  2. 從回應中每個 GoogleAdsRowcampaign 欄位取得 Campaign 物件。
  3. 將每個廣告活動的狀態從「PAUSED」改為「ENABLED」。
  4. 使用修改的廣告活動呼叫 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> 替換為資源 (例如 customercampaign) 或欄位 (例如 campaign.idmetrics.impressionsad_group.id)。

如需可查詢的欄位清單,請參閱 GoogleAdsField 說明文件

程式碼範例

用戶端程式庫提供在 GoogleAdsService 中使用 Google Ads 查詢語言的範例。基本作業資料夾具有範例,例如 GetCampaignsGetKeywordsSearchForGoogleAdsFields。「reporting」資料夾具有 GetKeywordStats 範例。