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 日あたりのオペレーション割り当てに対する追加のオペレーションとしてカウントされません。クエリが異なり、同じページトークンとともに送信されると、エラーが返されます。