Como percorrer resultados

A linguagem de consulta do Google Ads é compatível com paginação especificando page_size na sua solicitação. Isso dividirá o conjunto de resultados da consulta em várias respostas, cada uma contendo até objetos page_size. Se page_size não for especificado, ele será definido automaticamente com o tamanho máximo de página de 10.000 linhas.

Por exemplo, com a seguinte consulta:

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

Se a conta tiver 50.000 palavras-chave e page_size estiver definido como 1,000, o conjunto de resultados conterá 1.000 objetos GoogleAdsRow na primeira resposta, junto com uma next_page_token. Para recuperar as próximas mil linhas, basta enviar a solicitação novamente com o mesmo tamanho de página, mas atualizar o page_token da solicitação para o next_page_token da resposta. O valor de page_size nas solicitações subsequentes poderá ser diferente a cada vez.

Nossas bibliotecas de cliente lidam com a paginação automaticamente. Basta iterar pelas linhas da resposta. Quando todas as linhas da página atual forem retornadas, a biblioteca de cliente buscará uma nova página de linhas automaticamente em seu nome até que todo o conjunto de dados seja recuperado. Se você estiver usando REST em vez de gRPC, faça uma solicitação explicitamente para cada nova página.

A API Google Ads armazena internamente todo o conjunto de dados em cache. Assim, as solicitações subsequentes são mais rápidas do que a primeira. Dependendo do caso de uso, é possível definir page_size como qualquer valor entre 1 e 10.000. Para um desempenho geral mais rápido, é necessário usar um page_size maior, já que há menos respostas de ida e volta.

A consulta precisa permanecer exatamente a mesma nas próximas solicitações para aproveitar os dados armazenados em cache. As solicitações não contribuem para a cota, especialmente para acesso básico. Se a consulta for diferente e for enviada com o token da página, ocorrerá um erro.