GoogleAdsService
是 Google Ads API 的統一物件擷取和報表服務。這項服務的方法包括:
- 擷取物件的特定屬性。
- 根據日期範圍擷取物件的成效指標。
- 根據物件屬性將物件排序。
- 使用條件來指出您希望回應傳回的物件。
- 限制傳回的物件數量。
GoogleAdsService
可透過兩種方式傳回結果:
GoogleAdsService.SearchStream
會在單一串流回應中傳回所有資料列,在大型 (超過 10,000 列) 結果集時更有效率。如果您的批次應用程式想要以盡可能快的速度下載資料,則可能更適合。GoogleAdsService.Search
會將大型回應分成可管理的結果頁面。如果您的互動式應用程式會同時顯示一頁結果,則這個方法可能更適合。
進一步瞭解分頁與串流。
提出要求
搜尋方法需要 SearchGoogleAdsRequest
,由下列屬性組成:
customer_id
- Google Ads 查詢語言
query
,用來指定要查詢的資源、要擷取的屬性、區隔和指標,以及用來限制傳回物件的條件。 - (僅限
GoogleAdsService.Search
)page_size
表示使用分頁時,單一回應中要傳回的物件數量。 - (僅限
GoogleAdsService.Search
) 選用page_token
,可在使用分頁時擷取下一批結果。
如要進一步瞭解 Google Ads 查詢語言,請參閱 Google Ads 查詢語言指南。
處理回應
GoogleAdsService
會傳回 GoogleAdsRow
物件的清單。
每個 GoogleAdsRow
都代表查詢傳回的物件,其中包含一組屬性,系統會根據 SELECT
子句中要求的欄位填入這些屬性。SELECT
子句中未包含的屬性不會填入回應的 GoogleAdsRow
物件。
舉例來說,雖然 ad_group_criterion
包含 status
屬性,但對於 SELECT
子句不含 ad_group_criterion.status
的查詢,系統並不會在查詢中填入資料列 ad_group_criterion
屬性的 status
欄位。同樣地,如果 SELECT
子句不包含 campaign
資源中的任何欄位,系統就不會填入資料列的 campaign
屬性。
每個 GoogleAdsRow
可具有同一個結果集中其他資料列的屬性和指標,因此資料列看起來應該是物件,而不是資料表中的固定資料列。
UNKNOWN 列舉類型
該 API 版本無法完整支援以 UNKNOWN
類型傳回的資源。這些資源可能是透過其他介面 (例如 Google Ads UI) 建立。您可以在資源類型為 UNKNOWN
時選取指標,但無法透過 API 變更資源。例如在 UI 中導入的新廣告活動或廣告,但您要查詢的 API 版本並不支援。
以下是幾件注意事項:
- 具有
UNKNOWN
類型的資源可在稍後支援,或無限期保留UNKNOWN
。 - 類型為
UNKNOWN
的新物件隨時可能顯示。由於列舉值已可供使用,因此這些物件具有回溯相容性。我們會在這項異動推出時推出資源,讓您對帳戶有準確的瞭解。如果帳戶透過其他介面出現新的活動,或是系統不再支援某項資源,則UNKNOWN
資源可能就會出現。 UNKNOWN
資源可將詳細指標附加至可查詢的指標。UNKNOWN
資源通常會在 Google Ads 使用者介面中完整顯示。UNKNOWN
項資源通常無法修改。
區隔
回應會包含下列每個組合的一個 GoogleAdsRow
:
FROM
子句指定主要資源的例項- 每個所選
segment
欄位的值
例如,如果查詢選取 FROM campaign
,且 SELECT
子句中有 segments.ad_network_type
和 segments.date
,則回應中會針對每個以下組合顯示一個資料列:
campaign
segments.ad_network_type
segments.date
結果會以主要資源的每個執行個體間接區隔,而非根據所選個別欄位的值。比如
SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
會導致每個「廣告活動」產生一列,而不是為 campaign.status
欄位的每個不同值產生一列。