Como recuperar objetos

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

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

A 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 é recomendado se o aplicativo fizer o download de conjuntos de resultados completos ou processar linhas como um stream.
  • GoogleAdsService.Search divide respostas grandes em páginas de resultados gerenciáveis. Isso é útil se o aplicativo interativo exibir uma página de resultados por vez.

Saiba mais sobre paginação x streaming.

Fazer uma solicitação

GoogleAdsService.SearchStream espera um SearchGoogleAdsStreamRequest, e GoogleAdsService.Search espera um SearchGoogleAdsRequest. Os dois tipos de solicitação incluem:

  • Um customer_id
  • Uma query da 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.

Dependendo do método, a solicitação também aceita campos específicos do método:

  • SearchGoogleAdsStreamRequest (somente SearchStream):
  • SearchGoogleAdsRequest (somente Search):
    • Um page_token opcional para recuperar o próximo lote de resultados ao usar a paginação (page_size é fixado em 10.000 linhas; definir page_size na solicitação gera um erro RequestError.PAGE_SIZE_NOT_SUPPORTED)
    • Uma mensagem search_settings opcional para configurar return_summary_row, return_total_results_count e omit_results
    • Um booleano validate_only opcional para validar a consulta sem executá-la.

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

Processar uma resposta

O GoogleAdsService retorna uma lista de objetos GoogleAdsRow (em lotes SearchGoogleAdsStreamResponse transmitidos ou em um SearchGoogleAdsResponse paginado).

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

Tipos de enum UNKNOWN e UNSPECIFIED

Os recursos retornados com um valor de tipo enumerado de UNKNOWN não são totalmente compatíveis com essa versão da API, enquanto UNSPECIFIED indica que um campo de tipo enumerado não foi definido ou não foi solicitado na cláusula SELECT. Os recursos com um valor de tipo enumerado UNKNOWN podem ter sido criados por outras interfaces, 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 pela API. Um exemplo disso seria um tipo de campanha ou tipo de anúncio disponível na interface que não é compatível com a versão da API que você está consultando.

Confira algumas considerações importantes:

  • Um recurso com um tipo UNKNOWN pode ser compatível com uma versão posterior da API 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 tipo enumerado UNKNOWN está presente em todos os tipos enumerados na API. Os recursos são retornados com UNKNOWN para que você tenha uma visão precisa das métricas de performance geral da sua conta.
  • Os recursos do UNKNOWN podem ter métricas detalhadas anexadas que podem ser consultadas.
  • Os recursos de UNKNOWN geralmente ficam totalmente visíveis na interface do Google Ads.
  • Os recursos de UNKNOWN geralmente não podem ser modificados pela API.

Segmentação

A resposta contém um GoogleAdsRow para cada combinação dos seguintes itens:

  • Instância do recurso principal especificado na cláusula FROM
  • Valor de cada campo segments 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 do seguinte:

  • 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 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.

Anterior
Como mudar objetos
Avançar
Metadados do recurso