結果をページ分割する

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 は入力されません。

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

キャッシュ保存とページトークンの有効期限

Google Ads API は、内部でデータセットをキャッシュに保存するため、後続のページ リクエストは初回リクエストよりも高速になります。next_page_token 値には有効期間（TTL）があり、短期間（約 2 時間）内に使用されないと期限切れになることに注意してください。ページトークンの有効期限が切れると、API はエラーを返します。新しいクエリを開始する必要があります。

キャッシュに保存されたデータを活用するには、後続のリクエストでクエリが同一である必要があります。後続のページング リクエストは、エクスプローラ アクセスと基本アクセスの 1 日あたりのオペレーション割り当てに対する追加のオペレーションとしてカウントされません。クエリが異なり、同じページトークンとともに送信された場合は、エラーが返されます。