Como recuperar objetos

O GoogleAdsService é o serviço unificado de recuperação e geração de relatórios de objetos da API Google Ads. O serviço tem métodos que:

• Recuperam atributos específicos de objetos.
• Recuperam métricas de performance para objetos com base em um período.
• Ordenam objetos com base nos atributos deles.
• Usam condições para indicar quais objetos você quer que sejam retornados na resposta.
• Limitam o número de objetos retornados.

O GoogleAdsService pode retornar resultados de duas maneiras:

• GoogleAdsService.SearchStream retorna todas as linhas em uma única resposta de streaming,o que é mais eficiente para conjuntos de resultados grandes (mais de 10.000 linhas). Isso pode ser mais adequado se o aplicativo em lote quiser baixar o máximo de dados possível o mais rápido possível.
• GoogleAdsService.Search divide respostas grandes em páginas de resultados gerenciáveis. Isso pode ser mais adequado se o aplicativo interativo mostrar uma página de resultados por vez.

Saiba mais sobre paginação e streaming.

Fazer uma solicitação

O método de pesquisa requer um SearchGoogleAdsRequest, que consiste nos seguintes atributos:

• Um customer_id
• Uma query da Linguagem de consulta do Google Ads que indica o recurso que será pesquisado, os atributos, segmentos e métricas a serem recuperados e as condições usadas para restringir quais objetos retornar
• (GoogleAdsService.Search somente) Um opcional page_token para recuperar o próximo lote de resultados ao usar paginação.

Para mais informações sobre a Linguagem de consulta do Google Ads, consulte o guia da Linguagem de consulta do Google Ads.

Processar uma resposta

O GoogleAdsService retorna uma lista de GoogleAdsRow objetos.

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 na 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 é 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 consideradas objetos, e não linhas fixas de uma tabela.

Tipos de enumeração DESCONHECIDOS

Os recursos retornados com um tipo UNKNOWN não são totalmente compatíveis com essa versão da API. Esses recursos podem ter sido criados por outras interfaces, como a interface do Google Ads. É possível selecionar métricas quando um recurso tem um tipo UNKNOWN, mas não é possível modificar o recurso pela API. Um exemplo disso seria uma nova campanha ou anúncio introduzido na interface, mas indisponível na versão da API que você está consultando.

Confira algumas considerações a serem lembradas:

• Um recurso com um tipo UNKNOWN pode ser compatível mais tarde ou permanecer UNKNOWN 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 ficam disponíveis para que você tenha uma visão precisa da sua conta. O recurso UNKNOWN pode aparecer devido a novas atividades na sua conta por outras interfaces ou quando um recurso não é mais compatível.
• Os recursos UNKNOWN podem ter métricas detalhadas anexadas a eles que podem ser consultadas.
• Os recursos UNKNOWN geralmente são totalmente visíveis na interface do Google Ads.
• Os recursos UNKNOWN geralmente não podem ser modificados.

Segmentação

A resposta contém 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 para uma consulta que seleciona FROM campaign e tem segments.ad_network_type e segments.date na cláusula SELECT contém 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 campaign, não em uma linha para cada valor do campo campaign.status.