Instalar e usar o Assistente de desenvolvedor da API Google Ads

O Assistente de desenvolvedor da API Google Ads oferece experiência no domínio da API Google Ads diretamente no 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 agente 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 de domínio especializadas para manter o 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. Executar o script de instalação

Execute o script de instalação para a plataforma segmentada. Por padrão, a biblioteca de cliente do Python está incluída. Opcionalmente, 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 do cliente padrão, insira o número do ID do cliente 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 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 Assistente

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

Principais recursos

  • Perguntas e respostas em linguagem natural:faça perguntas sobre os recursos, as práticas recomendadas ou os recursos específicos da API Google Ads.

  • Perguntas e respostas em linguagem natural e orientação conceitual: faça perguntas sobre os recursos, as regras arquitetônicas ou os recursos específicos da API Google Ads. O Assistente fundamenta as respostas em definições oficiais da 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 no GAQL?"
    • "Explique a diferença entre click_view e impression_view."
    • "O que é um conjunto compartilhado e como faço para usá-lo?"
    • Comandos de barra do Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Geração de código de biblioteca de cliente fundamentado:gere código idiomático testado 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 GAQL:execute e valide automaticamente consultas complexas em relação a metadados da API, compatibilidade de campos, regras de impressão zero e segmentação de datas 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 enum para qualquer versão ativa da API 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 Assistente cria, valida e executa consultas GAQL diretamente na sua conta, transmitindo tabelas formatadas em tempo real 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.

    • Basta dizer ao Assistente: "Execute o código" ou "Execute o script".
    • Segurança de mutação:para 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-as manualmente fora do assistente.

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

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

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

    • Claude Code: /get-cids <manager_cid>
    • Linguagem natural: "Receber todos os IDs de clientes da conta de administrador 123-456-7890"

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

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

  • Contexto adicional da base de código:registre a lógica do aplicativo e a arquitetura personalizada no raciocínio do 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 habilidades, 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 do GAQL. /validate-gaql
/inspect-object Inspeciona campos, tipos e enums do Protobuf. /inspect-object Campaign
/get-cids Resolve hierarquias de MCC 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 produtos anunciados da Performance Max. /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 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: 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 colaboraçã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 programadores da API Google Ads?