Como recuperar objetos

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 para objetos com base em um período.
  • Ordenar objetos com base nos atributos deles.
  • 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 (mais de 10.000 linhas). Isso pode ser mais apropriado se o aplicativo em lote quiser fazer o download da maior quantidade de dados o mais rápido possível.
  • GoogleAdsService.Search dividirá 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 a paginação x streaming.

Como fazer uma solicitação

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

  • customer_id.
  • Uma query da linguagem de consulta do Google Ads que indica o recurso que 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) Uma page_size para indicar quantos objetos retornar em uma única resposta ao usar paginação.
  • (Somente GoogleAdsService.Search) 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 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 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 a 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. Assim, as linhas precisam ser visualizadas como objetos, em vez de linhas fixas de uma tabela.

Tipos de enumeração UNKNOWN

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

Tenha em mente o seguinte:

  • 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 da enumeração já está disponível. Apresentamos os recursos com essa alteração à medida que eles são disponibilizados, para que você tenha uma visão precisa da sua conta. O recurso UNKNOWN pode aparecer devido à nova atividade na sua conta por meio de outras interfaces ou porque um recurso não é mais compatível formalmente.
  • Os recursos de UNKNOWN podem ter métricas detalhadas anexadas a eles que podem ser consultadas.
  • Os recursos UNKNOWN normalmente ficam totalmente visíveis na IU do Google Ads.
  • Geralmente, os recursos de UNKNOWN não podem ser alterados.

Segmentação

A resposta conterá um GoogleAdsRow para cada combinação dos seguintes elementos:

  • instance 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 conterá uma linha para cada combinação dos itens a seguir:

  • campaign
  • segments.ad_network_type
  • segments.date