Como recuperar objetos

Objetivo: entender como extrair objetos e estatísticas de performance usando GoogleAdsService. Para conceitos de geração de relatórios, consulte os guias de relatórios.

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:

• Recuperar atributos específicos de objetos.
• Recupere métricas de desempenho de objetos com base em um período.
• Ordenar objetos com base em seus atributos.
• Use condições para indicar quais objetos você quer retornar na resposta.
• Limite 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,que é mais eficiente para conjuntos de resultados grandes (maiores que 10.000 linhas). Isso pode ser mais apropriado se o aplicativo em lote quiser fazer o download do máximo de dados possível.
• GoogleAdsService.Search divide respostas grandes em páginas de resultados gerenciáveis. Isso pode ser mais apropriado se o aplicativo interativo exibir uma página de resultados por vez.

Saiba mais sobre paginação versus streaming.

Fazer uma solicitação

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

• Um customer_id
• Uma Linguagem de consulta do Google Ads query que indica qual recurso será consultado, os atributos, segmentos e métricas a serem recuperados e as condições usadas para restringir quais objetos são retornados.
• (Somente GoogleAdsService.Search) Um page_size para indicar quantos objetos retornar em uma única resposta ao usar a paginação.
• (Somente GoogleAdsService.Search) Um page_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 de Linguagem de consulta do Google Ads.

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. Atributos não incluídos na cláusula SELECT não são preenchidos nos objetos GoogleAdsRow na resposta.

Por exemplo, embora 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 UNKNOWN não são totalmente compatíveis com essa versão da API. Esses recursos poderiam ter sido criados em 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 com a API. Um exemplo disso seria uma nova campanha ou anúncio sendo introduzido na interface, mas sem suporte para a versão da API que você está consultando.

Aqui estão algumas considerações a serem feitas:

• Um recurso com um tipo UNKNOWN pode receber suporte mais tarde ou permanecer como 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 do tipo enumerado já está disponível. Os recursos são introduzidos com essa mudança à medida que são disponibilizados para que você tenha uma visualização precisa da sua conta. O recurso UNKNOWN pode aparecer devido a novas atividades na sua conta usando outras interfaces ou quando um recurso não tem mais suporte.
• Os recursos UNKNOWN podem ter métricas detalhadas anexadas que são analisáveis.
• Os recursos UNKNOWN normalmente 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 uma linha por valor distinto do campo campaign.status.