Instalar e usar o Assistente de desenvolvedor da API Google Ads

O Assistente de desenvolvedor da API Google Ads traz experiência no domínio da API Google Ads diretamente para seu ambiente de programação de IA. Use comandos de linguagem natural e comandos de barra integrados para criar consultas, gerar código de biblioteca de cliente, executar chamadas de API somente leitura, transmitir relatórios ad hoc e resolver problemas de integrações.

O Assistente foi criado para os frameworks de agentes Google Antigravity e Claude Code (v4.0.0) como um plug-in modular. Ele usa contratos AGENTS.md e CLAUDE.md, comandos de barra integrados e habilidades especializadas no domínio para manter um contexto persistente, limites de segurança robustos e pipelines de validação automatizados.

Pré-requisitos

Antes de começar, certifique-se de ter:

  1. Acesso à API Google Ads:

  2. Software:

Primeiros passos

Siga estas etapas para clonar o repositório, executar o script de instalação específico da plataforma, configurar suas credenciais e ativar o plug-in.

1. Clonar o repositório

Clone o repositório na máquina local e navegue até o diretório do projeto:

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. Execute o script de instalação

Execute o script de instalação para sua plataforma segmentada. Por padrão, a biblioteca de cliente do Python é incluída. Você pode incluir outras bibliotecas de cliente (--php, --ruby, --java, --dotnet ou --all).

Antigravity

Linux / macOS:

./install.sh agy
# Or include additional client libraries:
./install.sh agy --java --dotnet

Windows (PowerShell):

.\install.ps1 -Type agy
# Or include additional client libraries:
.\install.ps1 -Type agy -Java -Dotnet

Claude Code

Linux / macOS:

./install.sh claude
# Or include additional client libraries:
./install.sh claude --php --dotnet

Windows (PowerShell):

.\install.ps1 -Type claude
# Or include additional client libraries:
.\install.ps1 -Type claude -Php -Dotnet

3. Configurar credenciais

Verifique se o arquivo de configuração da API (por exemplo, google-ads.yaml, google_ads_php.ini ou google_ads_config.rb) está no diretório $HOME.

(Opcional) Para configurar um ID de cliente padrão, insira o número do ID diretamente em config/customer_id.txt (por exemplo, 1234567890). Você também pode inspecionar ou fixar sua versão ativa da API em config/api_version.txt.

4. Ativar o plug-in

  • Antigravity:reinicie o Antigravity / sessão do host agy para carregar o plug-in.
  • Claude Code:em uma sessão ativa do Claude Code, execute /reload-plugins ou reinicie claude.

5. Interagir com o Google Assistente

Você pode interagir com o Google Assistente usando comandos em linguagem natural ou comandos de barra dedicados diretamente no terminal.

Principais recursos

  • Perguntas e respostas em linguagem natural e orientação conceitual:faça perguntas sobre recursos da API Google Ads, regras de arquitetura, práticas recomendadas ou recursos específicos. O Assistente fundamenta as respostas em definições oficiais de API, em vez de se basear apenas no treinamento geral do LLM.

    • "Quais são os tipos de campanha disponíveis?"
    • "Como faço para filtrar por data na GAQL?"
    • "Explique a diferença entre click_view e impression_view."
    • "O que é um conjunto compartilhado e como usá-lo?"
    • Comandos de barra do Claude Code:/explain, /step-by-step, /assistant-tutorial

  • Geração de código da biblioteca de cliente fundamentada:gere código testado e idiomático usando as bibliotecas de cliente oficiais do Google Ads (Python, Java, PHP, .NET e Ruby).

    • "Mostre as campanhas com mais conversões nos últimos 30 dias."
    • "Receba todos os nomes de grupos de anúncios ativados para o cliente 123-456-7890."
    • "Escreva um código para criar uma campanha Performance Max" O código gerado é salvo no diretório saved/code/.

  • Validação programática de consultas da GAQL:faça um teste a seco e valide automaticamente consultas complexas em relação a metadados da API, compatibilidade de campos, regras de zero impressão e segmentação por data antes da execução.

    • Claude Code:/validate-gaql
    • Linguagem natural:validate: SELECT campaign.id FROM campaign

  • Inspeção de esquema de objeto e Protobuf:inspecione dinamicamente estruturas de recursos, campos aninhados, tipos de dados e valores de enumeração para qualquer versão de API ativa sem sobrecarga de metadados remotos.

    • Claude Code:/inspect-object <resource_or_enum>
    • Linguagem natural:"Inspecionar recurso de campanha"

  • Relatórios ad hoc em tempo real e exportação de CSV:peça dados de performance em inglês simples. O Google Assistente cria, valida e executa consultas da GAQL diretamente na sua conta, transmitindo tabelas formatadas ao vivo para o terminal.

    • "Mostre as cinco principais palavras-chave por custo no mês passado para o cliente 123-456-7890."
    • "Salve os resultados como um arquivo CSV". (Exporta para saved/csv/).

  • Execução direta da API e segurança de mutação:execute scripts somente leitura gerados diretamente em um ambiente virtual gerenciado.

    • Diga ao Google Assistente: "Execute o código" ou "Execute o script".
    • Alterar segurança:para segurança, as operações de mutação (criar, atualizar, excluir) são geradas para saved/code/, mas nunca executadas diretamente pelo assistente. Revise e execute manualmente fora do assistente.

  • Diagnóstico avançado e solução de problemas de conversão:investigue falhas no upload de conversões off-line, pré-valide arquivos de upload e gere relatórios de diagnóstico detalhados.

    • Claude Code:/troubleshoot-conversions
    • Linguagem natural:"Resolva problemas de conversões para o cliente 123-456-7890." (Relatórios salvos em saved/data/).

  • Mapeamento da hierarquia de contas da MCC:recupere IDs de cliente de subcontas e mapeie hierarquias de contas em uma conta de administrador.

    • Claude Code:/get-cids <manager_cid>
    • Linguagem natural:"Extraia todos os IDs de cliente do gerente 123-456-7890"

  • Filtros e exclusões de informações do produto das campanhas Performance Max:gere árvores de partição de produtos e exclusões de URL de páginas da Web para grupos de recursos.

    • Claude Code:/pmax-filter
    • Linguagem natural: "Crie filtros de exclusão de página da Web para minha campanha PMax"

  • Contexto adicional da base de código:registre a lógica do aplicativo e a arquitetura personalizada no raciocínio do Google Assistente.

    • Linux / macOS:

      ./update.sh agy --context_dir /path/to/your/codebase
# Or for Claude Code:
./update.sh claude --context_dir /path/to/your/codebase

    • Windows (PowerShell):

      .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Referência de comandos de barra do Claude Code

Ao usar o Claude Code, os seguintes comandos de barra integrados estão disponíveis. No Google Antigravity, invoque esses mesmos recursos usando comandos de linguagem natural ou nomes de ferramentas de habilidade, como validate_gaql e inspect_object, conforme descrito em Principais recursos:

Comando de barra Finalidade Exemplo
/validate-gaql Valida a sintaxe, a compatibilidade e as regras da GAQL. /validate-gaql
/inspect-object Inspeciona campos, tipos e enums do Protobuf. /inspect-object Campaign
/get-cids Resolve hierarquias de MCCs e CIDs de clientes. /get-cids 1234567890
/troubleshoot-conversions Executa diagnósticos de upload de conversões off-line. /troubleshoot-conversions
/pmax-filter Gera filtros e exclusões de produtos da PMax. /pmax-filter
/explain Fornece uma explicação estruturada em quatro partes. /explain shared set
/step-by-step Formula um plano de execução de tarefas multifásico. /step-by-step upload conversions
/assistant-tutorial Executa um tutorial interativo de 11 etapas. /assistant-tutorial

Manutenção e atualizações

Para atualizar o repositório, a instalação do plug-in e as bibliotecas de cliente:

Antigravity

Linux / macOS:

./update.sh agy          # Update Antigravity plugin
./update.sh agy --all    # Include all client libraries

Windows (PowerShell):

.\update.ps1 -Type agy
.\update.ps1 -Type agy -All

Claude Code

Linux / macOS:

./update.sh claude       # Update Claude Code plugin
./update.sh claude --all # Include all client libraries

Windows (PowerShell):

.\update.ps1 -Type claude
.\update.ps1 -Type claude -All

Desinstalação

Para desinstalar o plug-in do assistente:

Antigravity

Linux / macOS:

rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell):

Remove-Item -Recurse -Force `
  "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

Em seguida, reinicie a sessão do host do Antigravity.

Claude Code

Em uma sessão ativa do Claude Code:

/plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Ou no terminal:

claude plugin uninstall \
  google-ads-api-developer-assistant@google-ads-assistant-local

(Opcional) Remova o registro do marketplace local:

claude plugin marketplace remove google-ads-assistant-local

Comunidade e suporte

Diretrizes de contribuição

Sua contribuição é bem-vinda! Consulte o arquivo CONTRIBUTING.md no repositório do GitHub para conferir as diretrizes.

Anterior
O que é o assistente para programadores da API Google Ads?