Instalar e usar o Assistente de desenvolvedor da API Google Ads

O Assistente de desenvolvedor da API Google Ads traz experiência profunda 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 as estruturas de 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 sua 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 Python é incluída. Você pode incluir outras bibliotecas de cliente (--php, --ruby, --java, --dotnet ou --all).

Antigravity

Linux / macOS:```bash ./install.sh agy

Ou inclua outras bibliotecas de cliente:

./install.sh agy --java --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type agy

Ou inclua outras bibliotecas de cliente:

.\install.ps1 -Type agy -Java -Dotnet ```

Claude Code

Linux / macOS:```bash ./install.sh claude

Ou inclua outras bibliotecas de cliente:

./install.sh claude --php --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type claude

Ou inclua outras bibliotecas de cliente:

.\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). Também é possível inspecionar ou fixar sua versão ativa da API em config/api_version.txt.

4. Ativar o plug-in

  • Antigravity:reinicie a sessão do host do Antigravity / 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

É possível 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:faça perguntas sobre recursos, práticas recomendadas ou recursos específicos da API Google Ads.

  • Perguntas e respostas em linguagem natural e orientação conceitual:faça perguntas sobre recursos da API Google Ads, regras arquitetônicas ou recursos específicos. O Google Assistente baseia as respostas em definições oficiais de API, em vez de depender apenas do treinamento geral de 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 ele funciona?"
    • Comandos de barra do Claude Code:/explain, /step-by-step, /assistant-tutorial

  • Geração de código de biblioteca de cliente embasada:gere código testado e idiomático usando 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 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 de API e segurança de mutação:execute scripts somente leitura gerados diretamente em um ambiente virtual gerenciado.

    • Basta dizer ao Google Assistente: "Execute o código" ou "Execute o script".
    • Segurança de mutação:para garantir a segurança, as operações de mutação (criar, atualizar, excluir) são geradas para saved/code/, mas nunca são 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:"Receba todos os IDs de cliente do cliente no gerente 123-456-7890"

  • Filtros e exclusões de produtos anunciados 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:bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • Windows (PowerShell): 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 enumerações 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ão off-line. /troubleshoot-conversions
/pmax-filter Gera filtros e exclusões de listagem da PMax. /pmax-filter
/explain Oferece uma explicação estruturada em quatro partes. /explain shared set
/step-by-step Formula um plano de execução de tarefas em várias fases. /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 de plug-ins e as bibliotecas de cliente:

Antigravity

Linux / macOS:bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Claude Code

Linux / macOS:bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

Desinstalação

Para desinstalar o plug-in do assistente:

Antigravity

Linux / macOS:bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell): 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: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Ou no terminal: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(Opcional) Remova o registro do marketplace local: bash claude plugin marketplace remove google-ads-assistant-local

Comunidade e suporte

Diretrizes de contribuição

As contribuições são bem-vindas! Consulte o arquivo CONTRIBUTING.md no repositório do GitHub para conferir as diretrizes.

Anterior
O que é o Assistente para desenvolvedores da API Google Ads?