Conecta-seEntrar na plataforma

Consulta personalizada (GAQL) · Google Ads

Consulta personalizada (GAQL) usando a conexão Google Ads deste workspace.

Integrações e ferramentasDados e análisesConexão: OAuth

O que faz

Consulta personalizada (GAQL) usando a conexão Google Ads deste workspace.

Quando usar: Use quando o seu fluxo precisar Consulta personalizada (GAQL) usando a conexão Google Ads deste workspace..

Exemplo de situação: Consultar indicadores e usar o resultado em uma decisão do fluxo.

Antes de começar

Conexão necessária: OAuth.

Conecte a conta pelo botão de autorização do campo de credencial e confira qual usuário ou organização foi escolhido.

Passo a passo

  1. Adicione Consulta personalizada (GAQL) · Google Ads ao desenho a partir da aba Blocos e ligue a entrada dele à etapa anterior.
  2. Conecte a conta pelo botão de autorização do campo de credencial e confira qual usuário ou organização foi escolhido.
  3. Revise a ação principal descrita no cartão do bloco.
  4. Preencha os campos obrigatórios. Para usar um dado de uma etapa anterior, digite < e escolha o bloco e o campo.
  5. Clique em Executar com dados de teste e confira, no terminal, o que entrou e o que saiu do bloco.
  6. Só publique depois de conferir o resultado da execução de teste.

Operações

OperaçãoO que faz
Consulta personalizada (GAQL)Executa a operação “Consulta personalizada (GAQL)” com o bloco Consulta personalizada (GAQL) · Google Ads.

Campos

Mostrar campos de

  • Operação

    Escolhe qual ação este bloco executará.

    Opções:
    Consulta personalizada (GAQL)
    Padrão:
    Consulta personalizada (GAQL)

  • Conta do Google Ads

    Obrigatório

    Seleciona a conta já conectada que autoriza o acesso ao serviço.

    Exemplo:
    (escolha a conta conectada)

  • Conta do Google Ads

    ObrigatórioEm campos adicionais

    Informa manualmente a credencial usada pela integração no modo avançado.

  • ID do cliente

    Obrigatório conforme a operação

    ID de cliente do Google Ads (sem hifens).

    Quando aparece:
    Quando o campo “Operação” for diferente de “list_customers”
    Exemplo:
    id-do-recurso

  • ID de cliente da conta de administrador

    Em campos adicionais

    ID da conta de administrador (opcional).

    Quando aparece:
    Quando o campo “Operação” for diferente de “list_customers”
    Exemplo:
    id-do-recurso

  • Consulta GAQL

    Obrigatório conforme a operação

    Informa a consulta usada para localizar ou transformar dados.

    Aparece em:
    Consulta personalizada (GAQL)
    Exemplo:
    SELECT * FROM clientes WHERE status = 'ativo'

  • Data inicial

    Obrigatório conforme a operação

    Define a data, o horário ou a programação usada pela operação.

    Quando aparece:
    Quando o campo “Período” for “Personalizado” e o campo “Operação” for “campaign_performance” ou “ad_performance”
    Exemplo:
    2026-09-15

  • Data final

    Obrigatório conforme a operação

    Define a data, o horário ou a programação usada pela operação.

    Quando aparece:
    Quando o campo “Período” for “Personalizado” e o campo “Operação” for “campaign_performance” ou “ad_performance”
    Exemplo:
    2026-09-15

  • Token da página

    Em campos adicionais

    Token recebido na página anterior; mantenha os outros campos iguais.

    Quando aparece:
    Quando o campo “Operação” for diferente de “list_customers”
    Exemplo:
    Token recebido na página anterior; mantenha os outros campos iguais

Saídas

Para usar um resultado deste bloco em uma etapa seguinte, digite < no campo e escolha o bloco e o campo. A referência tem o formato <consultapersonalizadagaqlgoogleads.customerIds>: antes do ponto vai o nome do bloco no seu fluxo, em minúsculas, sem espaços e sem acentos.

ReferênciaTipoO que contém
<consultapersonalizadagaqlgoogleads.customerIds>jsonIDs de cliente acessíveis diretamente; use customer_client para descobrir as subcontas de uma conta de administrador (list_customers).
<consultapersonalizadagaqlgoogleads.results>jsonLinhas com os campos GAQL selecionados (search).
<consultapersonalizadagaqlgoogleads.campaigns>jsonCampanhas com IDs, nomes, status, datas e orçamentos (list_campaigns), ou impressões, cliques, custo e conversões por dia (campaign_performance).
<consultapersonalizadagaqlgoogleads.adGroups>jsonGrupos de anúncios com ID, nome, status, tipo e identificação da campanha (list_ad_groups).
<consultapersonalizadagaqlgoogleads.ads>jsonMétricas diárias dos anúncios, com IDs do anúncio, do grupo de anúncios e da campanha, impressões, cliques, custo, CTR e conversões (ad_performance).
<consultapersonalizadagaqlgoogleads.totalCount>numberNúmero de linhas retornadas nesta página.
<consultapersonalizadagaqlgoogleads.totalResultsCount>numberTotal de linhas correspondentes, ignorando o LIMIT (search).
<consultapersonalizadagaqlgoogleads.nextPageToken>stringToken da próxima página para todos os relatórios e consultas; null na última página.

Exemplo de uso

Objetivo: Consultar indicadores e usar o resultado em uma decisão do fluxo.

InícioConsulta personalizada (GAQL) · Google Adspróxima etapa
Operação
Consulta personalizada (GAQL)
Conta do Google Ads
(escolha a conta conectada)
ID do cliente
id-do-recurso
Consulta GAQL
SELECT * FROM clientes WHERE status = 'ativo'
Data inicial
2026-09-15
Data final
2026-09-15

Os valores são ilustrativos. Teste primeiro com dados fictícios ou de homologação.

Erros comuns e como resolver

O bloco não executa
Confira se existe um caminho de setas que parte do gatilho (ou do Início) até este bloco. Blocos soltos no desenho são ignorados.
Aparece “Validação do fluxo” no terminal
Há campo obrigatório vazio. Clique no aviso, abra o bloco indicado e preencha o campo marcado.
Um campo chega vazio na etapa seguinte
Confira se a referência aponta para um bloco que já executou e para um campo que existe, como <consultapersonalizadagaqlgoogleads.customerIds>. O nome antes do ponto é o nome do bloco no seu fluxo, em minúsculas, sem espaços e sem acentos.
O campo que eu procuro não aparece
Os campos mudam conforme a operação escolhida. Escolha a operação primeiro; campos menos usados ficam em “Mostrar campos adicionais”.
Erro de autorização ou permissão (401/403)
A conta conectada perdeu o acesso ou não tem permissão para esta operação. Reconecte a conta no campo de credencial e confirme as permissões pedidas.
O serviço recusou a chamada ou devolveu erro
Leia a mensagem no terminal: ela traz o motivo informado pelo serviço. Confira IDs, limites de uso e permissões, e teste antes com um recurso de homologação.

Blocos relacionados