A API Google Ads tem um mecanismo unificado de recuperação de atributos e geração de relatórios de métricas, 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 os métodos Search ou SearchStream.
Ambos os métodos aceitam as mesmas consultas e retornam resultados equivalentes. O método Search retorna dados em páginas de tamanho fixo de 10.000 linhas, permitindo que você itere um conjunto de resultados usando a paginação. Isso pode ser vantajoso em condições de baixa
largura de banda ou de rede 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 base:
https://googleads.googleapis.com/v18/customers/CUSTOMER_ID/googleAds
POST /v18/customers/CUSTOMER_ID/googleAds:search 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'"
}
Se houver mais de 10.000 linhas nos resultados,uma nextPageToken será
retornada na resposta:
{
"results": [
// ...
// ...
// ...
],
"nextPageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B",
"fieldMask": "adGroupCriterion.keyword.text,adGroupCriterion.status"
}
A repetição da mesma consulta com um pageToken adicionado aos valores da
solicitação anterior recupera a próxima página de resultados:
POST /v18/customers/CUSTOMER_ID/googleAds:search 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'",
"pageToken": "CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"
}
Para usar o método SearchStream, que retorna todos os resultados em uma única resposta
de streaming, mude o método de serviço no URL para searchStream.
pageToken não é necessário para SearchStream:
POST /v18/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'"
}