擷取物件

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