擷取物件

GoogleAdsService 是 Google Ads API 的統一物件擷取和報表服務。這項服務提供下列方法：

• 擷取物件的特定屬性。
• 根據日期範圍擷取物件的成效指標。
• 根據物件的屬性排序。
• 使用條件指出要在回應中傳回的物件。
• 限制傳回的物件數量。

GoogleAdsService 可以透過下列兩種方式傳回結果：

• GoogleAdsService.SearchStream 以單一串流回應傳回所有資料列，對於大型 (超過 10,000 個資料列) 結果集來說，效率更高。如果批次應用程式想盡快下載大量資料，這或許是更合適的做法。
• GoogleAdsService.Search 會將大型回應分成多個頁面，方便管理結果。如果互動式應用程式一次顯示一頁結果，這可能更合適。

進一步瞭解分頁與串流。

提出要求

搜尋方法需要 SearchGoogleAdsRequest，其中包含下列屬性：

• A customer_id
• Google Ads 查詢語言 query，指出要查詢的資源、要擷取的屬性、區隔和指標，以及用於限制傳回哪些物件的條件
• (GoogleAdsService.Search 專用) 使用分頁時，可選用 page_token 擷取下一批結果。

如要進一步瞭解 Google Ads 查詢語言，請參閱 Google Ads 查詢語言指南。

處理回覆

GoogleAdsService 會傳回 GoogleAdsRow 物件的清單。

每個 GoogleAdsRow 都代表查詢傳回的物件，並包含一組屬性，這些屬性會根據 SELECT 子句中要求的欄位填入。系統不會在回應的 GoogleAdsRow 物件中填入未列於 SELECT 子句中的屬性。

舉例來說，雖然 ad_group_criterion 具有 status 屬性，但如果查詢的 SELECT 子句未包含 ad_group_criterion.status，則回應中資料列的 ad_group_criterion 屬性 status 欄位不會填入資料。同樣地，如果 SELECT 子句未包含 campaign 資源中的任何欄位，系統就不會填入資料列的 campaign 屬性。

每個 GoogleAdsRow 的屬性和指標可能與同一結果集中的其他資料列不同，因此資料列應視為物件，而非表格的固定資料列。

UNKNOWN 列舉型別

該 API 版本不完全支援以 UNKNOWN 類型傳回的資源。這些資源可能是透過其他介面 (例如 Google Ads 使用者介面) 建立。當資源類型為 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 欄位中每個不重複的值各有一列。