你可以使用 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
參考說明文件。
根據查詢結果變動
查詢特定資源時,您可以立即將這些傳回的結果當做物件來擷取、修改結果,然後將結果傳回該資源服務中的 mut 方法。以下是範例工作流程:
- 針對目前
PAUSED
且曝光大於 1000 的所有廣告活動執行查詢。 - 從回應中的每個
GoogleAdsRow
的campaign
欄位中取得Campaign
物件。 - 將各廣告活動的狀態從「
PAUSED
」改為「ENABLED
」。 - 呼叫
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
說明文件。
程式碼範例
用戶端程式庫提供了幾個在 GoogleAdsService
中使用 Google Ads 查詢語言的範例。「基本作業」資料夾提供 GetCampaigns
、GetKeywords
和 SearchForGoogleAdsFields
等範例。reporting 資料夾有 GetKeywordStats
範例。