결과 페이지로 이동

한 번에 전체 결과 집합을 다운로드하는 대신 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이 채워지지 않습니다.

Google 클라이언트 라이브러리는 페이지로 나누기를 자동으로 처리합니다. 응답의 행을 반복하기만 하면 됩니다. 현재 페이지의 모든 행이 반환되면 클라이언트 라이브러리는 전체 데이터 세트가 검색될 때까지 자동으로 새 페이지의 행을 가져옵니다. gRPC 대신 REST를 사용하는 경우 각 새 페이지에 대해 명시적으로 요청해야 합니다.

캐싱 및 페이지 토큰 만료

Google Ads API는 후속 페이지 요청이 초기 요청보다 빠르도록 데이터 세트를 내부적으로 캐시합니다. next_page_token 값은 수명이 제한되어 있으며 짧은 기간(약 2시간) 내에 사용하지 않으면 만료됩니다. 페이지 토큰이 만료되면 API에서 오류를 반환하므로 새 쿼리를 시작해야 합니다.

캐시된 데이터를 활용하려면 후속 요청에서 쿼리가 동일하게 유지되어야 합니다. 후속 페이지로 나눈 요청은 탐색기 액세스 및 기본 액세스의 일일 작업 할당량에 추가 작업으로 계산되지 않습니다. 쿼리가 다르고 동일한 페이지 토큰과 함께 전송되면 오류가 반환됩니다.