結果のページング

注: page_size フィールドは Google Ads API の v19 で削除されました。お知らせをご覧ください。page_size フィールドのデフォルト値は 10,000 です。page_size 値の設定を試みないでください。エラーがスローされます。

GoogleAdsService.Search は、10,000 行の固定ページサイズのページングをサポートしています。クエリの結果セットは複数のレスポンスに分割され、各レスポンスには 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 個のキーワードが含まれている場合、結果セットには next_page_token とともに最初のレスポンスで 10,000 個の GoogleAdsRow オブジェクトが含まれます。

次の 10,000 行を取得するには、リクエストをもう一度送信しますが、リクエストの page_token をレスポンスの next_page_token に更新します。行の最後のバッチを含むレスポンスには next_page_token が入力されません。

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

Google Ads API はデータセット全体を内部的にキャッシュするため、後続のリクエストは最初のリクエストよりも高速になります。

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

キーポイント: カスタム ウェブページングなど、手動ページングが必要な場合は、結果をローカル（データベースなど）で取得して保存し、独自のページング ロジックを構築することをおすすめします。