擷取物件

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_typesegments.date 具有查詢,則該查詢會針對下列各項組合提供一列:

  • campaign
  • segments.ad_network_type
  • segments.date