Instalar e usar o Assistente de desenvolvedor da API Google Ads

Pré-requisitos

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

1. Acesso à API Google Ads :

   • Um token de desenvolvedor da API Google Ads.
   • Um arquivo de configuração da API Google Ads configurado com seu token de desenvolvedor, credenciais do OAuth 2.0 e ID do cliente, localizado no seu diretório inicial. Consulte o guia de configuração da biblioteca de cliente.
   • Familiaridade com os conceitos e a autenticação da API Google Ads.

2. Software :

   • Python 3.10 ou mais recente. O Python é a linguagem padrão. Portanto, você precisa ter essa linguagem instalada e no seu caminho.
   • Ferramenta de linha de comando Google Antigravity instalada.
   • jq (processador JSON de linha de comando). O script de instalação vai tentar instalar esse processador se ele estiver ausente.

3. Repositório :

   • Um clone local do google-ads-api-developer-assistant repositório do GitHub.

Primeiros passos

1. Navegue até o diretório do projeto :

   cd <full path>/google-ads-api-developer-assistant
   

   Observação: se você tiver a integração do shell Antigravity ativada, ao acessar esse diretório, a sessão do assistente será inicializada automaticamente.

2. Execute o script de instalação:esse script inicializa o ambiente de desenvolvimento e clona as bibliotecas de cliente necessárias do Google Ads (o Python é instalado por padrão).

   ./install.sh
   

   Se você estiver no Windows, execute o script do PowerShell install.ps1.

3. Configure as credenciais:verifique se o arquivo google-ads.yaml (ou equivalente de linguagem) está no seu diretório inicial.

4. Interaja com o assistente:depois que a sessão estiver ativa, você poderá interagir com o assistente usando linguagem natural 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.

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

• Geração de código:gere consultas GAQL e snippets de código Python executáveis.

  • "Mostre as campanhas com mais conversões nos últimos 30 dias."
  • "Receba todos os nomes de grupos de anúncios ativados para o ID da campanha 12345."
  • "Encontre anúncios reprovados em todas as campanhas." O código gerado é automaticamente linted usando ruff e salvo no diretório saved/code/.

• Execução direta da API:execute scripts Python somente leitura gerados diretamente em um ambiente virtual isolado (.venv) e confira os resultados formatados como tabelas no terminal.

  • Basta dizer ao assistente: "Execute o código" ou "Execute o script".
  • Por segurança, as operações de mutação (criar, atualizar, excluir) são geradas, mas nunca executadas.

• Exportação de CSV:salve resultados tabulares de chamadas de API em um arquivo CSV.

  • "Salve os resultados em um arquivo CSV." Os arquivos são salvos no diretório saved/csv/.

• Diagnóstico e solução de problemas avançados:receba ajuda com mensagens de erro, comportamento inesperado da API ou problemas de conversão off-line.

  • "Por que não estou vendo nenhum resultado para minha consulta?"
  • "Resolva meus problemas de conversão para o cliente 123-456-7890." (Gera um relatório de diagnóstico detalhado em saved/data/).

• Contexto adicional:adicione sua própria base de código ou bibliotecas personalizadas para contexto.

  • Use o script update.sh com a opção --context_path para registrar os arquivos do projeto: none ./update.sh --context_path /path/to/your/codebase
  • Isso permite que o assistente inclua a lógica do aplicativo no raciocínio ao criar respostas ou gerar código no idioma de sua preferência.

Exemplos de casos de uso

• Relatórios:
  • "Mostre as cinco principais palavras-chave por custo do mês passado para o cliente 12345678."
• Estrutura da conta:
  • "Liste todos os nomes de campanhas e os IDs delas."
• Solução de problemas:
  • "Fiz o upload de 100 conversões, mas apenas 78 aparecem na interface. Como posso depurar isso usando a API?"
• Aprendizagem:
  • "/explain o que é um conjunto compartilhado"
• **Geração de código**:
  • "Escreva um código para criar uma campanha Performance Max para company name."

Comunidade e suporte

• Problemas do GitHub: relate bugs, sugira recursos ou peça ajuda na guia "Problemas" do repositório.
• Discord: participe da discussão no canal #ads-api-ai-tools no servidor do Discord da Comunidade de publicidade e medição do Google.
• Feedback: compartilhe seu feedback neste formulário de pesquisa.

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.