結果のページング

GoogleAdsService.Search は、リクエストで page_size を指定することでページングをサポートします。これにより、クエリの結果セットが複数のレスポンスに分割され、それぞれに最大 page_size 個のオブジェクトが含まれます。page_size が指定されていない場合は、自動的に最大 10,000 行に設定されます。

たとえば、次のクエリの場合:

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 個のキーワードが含まれ、page_size が 1,000 に設定されている場合、結果セットには、最初のレスポンスで 1,000 個の GoogleAdsRow オブジェクトと next_page_token が含まれます。

次の 1,000 行を取得するには、同じページサイズでリクエストをもう一度送信しますが、リクエストの page_token をレスポンスの next_page_token に更新します。後続のリクエストの page_size の値は、毎回異なる可能性があります。行の最後のバッチを含むレスポンスでは next_page_token は入力されません。

レスポンスの行を繰り返すだけで、自動的にページングが処理されます。現在のページのすべての行が返されると、データセット全体が取得されるまで、クライアント ライブラリが新しいページの行を自動的にフェッチします。gRPC の代わりに REST を使用する場合は、新しいページごとにリクエストを明示的に行う必要があります。

Google Ads API はデータセット全体を内部的にキャッシュするため、後続のリクエストは最初のリクエストよりも高速です。ユースケースに応じて、page_size を 1 ～ 10,000 の任意の値に設定できます。一般に、全体的なパフォーマンスを向上させるには、大きい page_size を使用してラウンド トリップを少なくします。

キャッシュされたデータを利用するには、以降のリクエストでもクエリはまったく同じでなければなりません。特にベーシック アクセスでは、リクエストは割り当て量に加算されません。クエリが異なり、同じページトークンとともに送信されると、エラーが返されます。