正在擷取物件

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

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

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

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

進一步瞭解分頁與串流。

提出要求

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

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

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

處理回應

GoogleAdsService 會傳回 GoogleAdsRow 物件的清單。

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

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

每個 GoogleAdsRow 都可以在同一組結果中，擁有其他資料列的不同屬性和指標；因此，資料列應視為物件，而非表格的固定資料列。

不明的列舉類型

該 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 欄位不重複值一列。