Como recuperar objetos

Objetivo: entender como recuperar objetos e estatísticas de desempenho usando GoogleAdsService Para conceitos de relatório, consulte os guias de relatórios.

O GoogleAdsService é o objeto unificado e serviços de geração de relatórios e recuperação 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.

O GoogleAdsService pode retornar resultados em duas maneiras:

• GoogleAdsService.SearchStream retorna todas as linhas em uma única resposta de streaming, o que é mais eficiente para grandes (maiores do que 10.000 linhas). Isso pode ser mais apropriado se o aplicativo em lote deseja baixar o máximo de dados possível sempre que possível.
• GoogleAdsService.Search divide grandes respostas em páginas gerenciáveis de resultados. Isso pode ser mais apropriado se o seu aplicativo interativo exibir uma página de resultados em um tempo de resposta.

Saiba mais sobre a paginação e o streaming.

Fazer uma solicitação

O método de pesquisa requer uma SearchGoogleAdsRequest, que consiste dos seguintes atributos:

• Um customer_id
• Uma query na linguagem de consulta do Google Ads que indica o recurso a ser consultado, os atributos segmentos e métricas a serem recuperados e as condições usadas para restringir quais objetos são retornados
• (Somente para o GoogleAdsService.Search) A page_size para indicar quantos objetos retornar em uma única resposta quando usando a paginação.
• (Somente para o GoogleAdsService.Search) Um page_token opcional para recuperar o próximo lote de resultados ao usar paginação.

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

Processar uma resposta

GoogleAdsService retorna uma lista de Objetos GoogleAdsRow.

Cada GoogleAdsRow representa um objeto retornado por uma consulta e consiste em uma conjunto de atributos que são preenchidos com base nos campos solicitados no cláusula SELECT. Atributos não incluídos na cláusula SELECT não são preenchido nos objetos GoogleAdsRow da resposta.

Por exemplo, embora um ad_group_criterion tenha um atributo status, o 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 campaign.

Cada GoogleAdsRow pode ter atributos e métricas diferentes de outra linha no mesmo conjunto de resultados. então as linhas devem ser visualizadas como objetos em vez e as 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 com essa versão da API. Esses recursos podem ter sido criados do Google, como a interface do Google Ads. É possível selecionar métricas quando um recurso tem um tipo de UNKNOWN, mas não é possível modificar o recurso usando a API. Um exemplo disso seria uma nova campanha ou anúncio sendo introduzido na interface, mas não suportados na 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 mais tarde ou permanecer UNKNOWN indefinidamente.
• Novos objetos com o tipo UNKNOWN podem aparecer a qualquer momento. Esses objetos são compatível com versões anteriores porque o valor do tipo enumerado já está disponível. Recursos foram apresentados com essa mudança à medida que estiverem disponíveis, para que você tenha visualização precisa da sua conta. O recurso UNKNOWN pode aparecer devido a novas atividades em sua conta por meio de outras interfaces ou quando um recurso não é mais compatível.
• UNKNOWN recursos podem ter métricas detalhadas anexadas a eles que estã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 seguinte:

• 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 conter 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 por cada instância do recurso principal, não por os 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 distinto do campaign.status.