O GoogleAdsService
é o serviço unificado de geração de relatórios e recuperação de objetos da API Google Ads. O serviço tem métodos que:
- Recupere atributos específicos de objetos.
- Recuperar métricas de desempenho de objetos com base em um período.
- Ordenar objetos com base nos atributos.
- Use condições para indicar quais objetos você quer que sejam retornados na resposta.
- Limite o número de objetos retornados.
GoogleAdsService
pode retornar resultados de
duas maneiras:
GoogleAdsService.SearchStream
retorna todas as linhas em uma única resposta de streaming,que é mais eficiente para grandes conjuntos de resultados (com mais de 10.000 linhas). Isso pode ser mais apropriado se o aplicativo em lote quiser fazer o download do máximo de dados o mais rápido possível.- O
GoogleAdsService.Search
divide respostas grandes em páginas gerenciáveis de resultados. Isso pode ser mais apropriado se o aplicativo interativo exibir uma página de resultados por vez.
Saiba mais sobre a paginação e o streaming.
Fazer uma solicitação
O método de pesquisa requer um
SearchGoogleAdsRequest
, que consiste
nos seguintes atributos:
- Um
customer_id
- Uma
query
na linguagem de consulta do Google Ads que indica qual recurso consultar, os atributos, segmentos e métricas a serem recuperados e as condições a serem usadas para restringir quais objetos são retornados. - (Somente
GoogleAdsService.Search
) Umpage_size
para indicar quantos objetos retornar em uma única resposta ao usar a paginação. - (Somente
GoogleAdsService.Search
) Umpage_token
opcional para recuperar o próximo lote de resultados ao usar a paginação.
Para mais informações sobre a Linguagem de consulta do Google Ads, confira o Guia dessa linguagem.
Processar uma resposta
O GoogleAdsService
retorna uma lista de
objetos GoogleAdsRow
.
Cada GoogleAdsRow
representa um objeto retornado por uma consulta e consiste em um conjunto de atributos preenchidos com base nos campos solicitados na cláusula SELECT
. Os atributos não incluídos na cláusula SELECT
não são
preenchidos nos objetos GoogleAdsRow
da resposta.
Por exemplo, embora um ad_group_criterion
tenha um atributo status
, o campo status
do atributo ad_group_criterion
da linha não é preenchido em uma resposta para uma consulta em que a cláusula SELECT
não inclui ad_group_criterion.status
. Da mesma forma, o atributo campaign
da linha não será preenchido se a cláusula SELECT
não incluir nenhum campo do recurso campaign
.
Cada GoogleAdsRow
pode ter atributos e métricas diferentes de outra linha
no mesmo conjunto de resultados. Portanto, as linhas precisam ser visualizadas como objetos em vez de
linhas fixas de uma tabela.
Tipos de tipo enumerado UNKNOWN
Os recursos retornados com um tipo de UNKNOWN
não são totalmente compatíveis
nessa versão da API. Esses recursos poderiam ter sido criados usando outras interfaces, como a IU do Google Ads. É possível selecionar métricas quando um recurso tem o
tipo UNKNOWN
, mas não é possível modificar o recurso usando a API. Um exemplo disso seria uma nova campanha ou anúncio ser introduzido na interface, mas não compatível com a versão da API que você está consultando.
Aqui estão algumas considerações para ter em mente:
- Um recurso com um tipo
UNKNOWN
pode receber suporte posteriormente ou permanecerUNKNOWN
indefinidamente. - Novos objetos com o tipo
UNKNOWN
podem aparecer a qualquer momento. Esses objetos são compatíveis com versões anteriores porque o valor de enumeração já está disponível. Os recursos são introduzidos com essa mudança à medida que são disponibilizados, para que você tenha uma visão precisa da sua conta. O recursoUNKNOWN
pode aparecer devido a novas atividades na sua conta por outras interfaces ou quando um recurso não tem mais suporte. - Os recursos de
UNKNOWN
podem ter métricas detalhadas anexadas que são consultáveis. - Normalmente, os recursos
UNKNOWN
ficam totalmente visíveis na interface do Google Ads. - Geralmente, os recursos
UNKNOWN
não podem ser modificados.
Segmentação
A resposta conteria um GoogleAdsRow
para cada combinação dos itens
a seguir:
- Instância do recurso principal especificado na cláusula
FROM
- Valor de cada campo
segment
selecionado
Por exemplo, a resposta de uma consulta que seleciona FROM campaign
e tem segments.ad_network_type
e segments.date
na cláusula SELECT
conteria uma linha para cada combinação dos itens a seguir:
campaign
segments.ad_network_type
segments.date
Os resultados são segmentados de forma implícita para cada instância do recurso principal, não pelos valores dos campos individuais selecionados. Por exemplo:
SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
resulta em uma linha por campanha, não em uma linha para cada valor do campo campaign.status
.