正在擷取物件

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 列舉類型

如果資源傳回的類型為 UNKNOWN，表示該 API 版本不完全支援這類資源。這些資源可能是透過其他介面 (例如 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 欄位中每個不重複的值各有一列。