Pesquisa e SearchStream

Vídeo: relatórios

A API Google Ads tem um mecanismo unificado de geração de relatórios de métricas e recuperação de atributos que permite criar consultas usando a linguagem de consulta do Google Ads. Isso permite consultas complexas que podem retornar grandes quantidades de dados sobre contas individuais do Google Ads.

É possível criar consultas usando um dos métodos Search ou SearchStream. Os dois métodos aceitam as mesmas consultas e retornam resultados equivalentes. O método Search retorna dados em tamanhos de página personalizáveis, permitindo que você itere um conjunto de resultados usando paginação. Isso pode ser vantajoso em condições de baixa largura de banda ou não confiáveis, por exemplo, para segmentar um conjunto de resultados grande em respostas menores, que podem ser buscadas novamente se uma conexão for perdida. O método SearchStream, por outro lado, transmite todo o conjunto de resultados em uma única resposta, o que pode ser mais eficiente para a recuperação de dados em massa.

Search e SearchStream usam o mesmo URL de base:

    https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/googleAds

O método de pesquisa baseada em página usa um parâmetro pageSize opcional que limita quantos resultados são retornados em uma única resposta da API.

POST /v16/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}

Se houver mais linhas nos resultados do que pageSize, uma nextPageToken será retornada na resposta:

{
  "results": [
    // ...
    // ...
    // ...
  ],
  "nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
  "fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}

Repetir a mesma consulta com um pageToken adicionado com o valor acima busca a próxima página de resultados:

POST /v16/customers/CUSTOMER_ID/googleAds:search HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
"pageSize": 10000,
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'",
"pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"
}

Para usar o método SearchStream, que retorna todos os resultados em uma única resposta transmitida, basta alterar o método de serviço no URL para searchStream (pageSize e pageToken não são obrigatórios para SearchStream):

POST /v16/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
    "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"
}