瀏覽結果頁面

您可以透過 GoogleAdsService.Search 逐頁瀏覽擷取的結果，不必一次下載整個結果集。如要瞭解如何使用 Google Ads API 產生報表，請參閱「報表總覽」。

Search 最多會傳回 10,000 列的固定頁面。在 SearchGoogleAdsRequest 中設定 page_size 已淘汰，且會傳回 RequestError.PAGE_SIZE_NOT_SUPPORTED 錯誤。

查詢和分頁範例

請參考下列查詢：

SELECT
  ad_group.id,
  ad_group_criterion.type,
  ad_group_criterion.criterion_id,
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type
FROM ad_group_criterion
WHERE ad_group_criterion.type = KEYWORD

如果帳戶包含 50,000 個關鍵字，則結果集會在第一個回應中包含 10,000 個 GoogleAdsRow 物件，以及 next_page_token。

如要擷取接下來的 10,000 列，請再次傳送要求，但將要求中的 page_token 更新為回應中的 next_page_token：

{
  "query": "SELECT ad_group.id, ad_group_criterion.type, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type FROM ad_group_criterion WHERE ad_group_criterion.type = KEYWORD",
  "pageToken": "CN3q9...example_token..."
}

請注意，在包含最後一批資料列的回應中，next_page_token 不會填入資料。

我們的用戶端程式庫會自動處理分頁。您只需要疊代回應的資料列。當目前頁面中的所有資料列都已傳回時，用戶端程式庫會自動為您擷取新頁面的資料列，直到擷取整個資料集為止。如果使用 REST 而非 gRPC，則必須明確要求每個新網頁。

快取和網頁權杖到期

Google Ads API 會在內部快取資料集，因此後續的頁面要求會比初始要求更快。請注意，next_page_token 值有存留時間 (TTL) 限制，如果沒有在短時間內 (約兩小時) 使用，就會過期。如果網頁權杖過期，API 會傳回錯誤，您必須啟動新的查詢。

後續要求必須與先前的要求完全相同，才能使用快取資料。後續的分頁要求不會計入探索存取權和基本存取權的每日作業配額。如果查詢不同，但與同一個頁面權杖一起傳送，系統就會傳回錯誤。