擷取物件

目標： 瞭解如何使用 GoogleAdsService 擷取物件和成效統計資料。如需報表概念，請參閱報表指南。

GoogleAdsService 是 Google Ads API 的統一物件擷取和報表服務。這項服務的方法包括：

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

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

• GoogleAdsService.SearchStream 會在單一串流回應中傳回所有資料列，對於大型 (超過 10,000 列) 結果集來說更有效率。如果應用程式會下載完整結果集，或以串流形式處理資料列，建議採用這種方法。
• GoogleAdsService.Search 會將大型回應拆分為易於管理的結果頁面。如果互動式應用程式一次顯示一頁結果，這個方法就能派上用場。

進一步瞭解分頁與串流。

提出要求

GoogleAdsService.SearchStream 預期 SearchGoogleAdsStreamRequest，而 GoogleAdsService.Search 預期 SearchGoogleAdsRequest。這兩種要求類型都包含：

• customer_id
• Google Ads 查詢語言 query，指出要查詢的資源、要擷取的屬性、區隔和指標，以及用來限制傳回物件的條件

視方法而定，要求也支援方法專屬欄位：

• SearchGoogleAdsStreamRequest (僅限SearchStream)：
  • 選用 summary_row_setting，要求提供包含匯總指標的摘要列
• SearchGoogleAdsRequest (僅限Search)：
  • 選用 page_token，用於在使用分頁時擷取下一批結果 (page_size 固定為 10,000 列；在要求中設定 page_size 會擲回 RequestError.PAGE_SIZE_NOT_SUPPORTED 錯誤)
  • 選用的 search_settings 訊息，用於設定 return_summary_row、return_total_results_count 和 omit_results
  • 選用的 validate_only 布林值，用於驗證查詢而不執行

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

處理回應

GoogleAdsService 會傳回 GoogleAdsRow 物件清單 (位於串流 SearchGoogleAdsStreamResponse 批次或分頁 SearchGoogleAdsResponse 中)。

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

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

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

UNKNOWN 和 UNSPECIFIED 列舉類型

如果傳回的資源列舉值為 UNKNOWN，表示該 API 版本不完全支援該資源；UNSPECIFIED 則表示列舉欄位尚未設定，或未在 SELECT 子句中要求。具有 UNKNOWN 列舉值的資源可能是透過其他介面 (例如 Google Ads UI) 建立。如果資源類型為 UNKNOWN，您可以選取指標，但無法透過 API 變更資源。舉例來說，使用者介面中提供的廣告活動或廣告類型，可能不支援您查詢的 API 版本。

請注意以下事項：

• UNKNOWN 類型的資源可能會在後續 API 版本中獲得支援，或無限期維持 UNKNOWN 狀態。
• UNKNOWN 類型的新物件隨時可能出現。這些物件具有回溯相容性，因為 API 中的每個列舉都有 UNKNOWN 列舉值。資源會與 UNKNOWN 一併傳回，讓您準確掌握帳戶的整體成效指標。
• UNKNOWN 資源可附加詳細指標，供您查詢。
• UNKNOWN 資源通常會完整顯示在 Google Ads 使用者介面中。
• UNKNOWN 資源通常無法透過 API 變更。

區隔

回應會針對下列各項組合，包含一個 GoogleAdsRow：

• FROM 子句中指定的主要資源例項
• 每個所選segments欄位的值

舉例來說，如果查詢選取 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 欄位的每個不重複值產生一列。

注意： 不同 API 版本提供的區隔可能有所差異。舉例來說，AdGroupAsset、CampaignAsset 和 CustomerAsset 上的 segments.click_type，以及 campaign_budget 上的 segments.ad_sub_network_type 只能在 v23 及更早版本中選取；PerformanceMaxPlacementView 上的 segments.ad_network_type 適用於 v24 及更新版本；segments.ad_sub_format_type 和 segments.loyalty_membership 適用於 v25 及更新版本；segments.search_lift_keyword_bundle 和 segments.search_property 適用於 v26 及更新版本。請使用 GoogleAdsFieldService，確認區隔與您查詢的 API 版本相容。