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
子句要求的欄位填入一組屬性。回應中 GoogleAdsRow
物件不會包含未包含在 SELECT
子句中的屬性。
例如,雖然 ad_group_criterion
有一個 status
屬性,但針對 SELECT
子句未包含 ad_group_criterion.status
的查詢,系統並未在資料列的 status
屬性中填入 status
欄位。同樣地,如果 SELECT
子句不包含 campaign
資源中的任何欄位,則不會填入資料列的 campaign
屬性。
每個 GoogleAdsRow
都可以有相同結果集中其他資料列的不同屬性和指標,因此資料列應視為物件,而非固定的資料表資料列。
列舉類型不明
該 API 版本完全不支援以 UNKNOWN
類型傳回的資源。這些資源可能是透過 Google Ads UI 等其他介面建立。您可以在資源擁有 UNKNOWN
類型時選取指標,但無法透過 API 修改資源。其中一個是使用者介面中的新廣告活動或廣告,但您正在查詢的 API 版本不支援這項功能。
以下是幾件注意事項:
- 系統日後可能會支援使用
UNKNOWN
類型的資源,或者一律使用UNKNOWN
。 - 類型為「
UNKNOWN
」的新物件隨時都有顯示。由於列舉值已經可用,所以這些物件具有回溯相容性。我們推出這項調整後,就會推出新的資源,方便您準確查看帳戶。系統可能會顯示UNKNOWN
資源,原因是您已透過其他介面在帳戶中有新的活動,或是系統不再提供某項資源。 UNKNOWN
資源可能附有可查詢的指標詳細資料。UNKNOWN
資源通常可以在 Google Ads 使用者介面中完整顯示。UNKNOWN
項資源通常無法修改。
區隔
回應會包含以下每個組合的一個 GoogleAdsRow
:
FROM
子句中指定的主要資源 instance- 每個所選
segment
欄位的值
舉例來說,如果查詢在 FROM campaign
子句中選取 FROM campaign
,且 segments.ad_network_type
和 segments.date
具有查詢,則該查詢會針對下列各項組合提供一列:
campaign
segments.ad_network_type
segments.date