Instalar e usar o Assistente de desenvolvedor da API Google Ads

Observação: essa ferramenta é um projeto de código aberto e não um produto oficial do Google product.

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, normalmente localizado no 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, é necessário que ele esteja instalado e no seu caminho.
   • gemini-cli instalado.
   • 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
   

2. Execute o script de configuração:esse script configura o gemini-cli para usar os arquivos de contexto GEMINI.md do assistente e as ferramentas necessárias.

   ./install.sh
   

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

3. Inicie o gemini-cli :

   gemini
   

4. Interaja com o assistente:agora você pode fazer perguntas ou dar comandos em linguagem natural.

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 é salvo no diretório saved_code/.

• Execução direta da API:execute scripts Python somente leitura gerados diretamente do gemini-cli e confira os resultados formatados no terminal. Depois que o assistente gerar o código, você vai receber um comando na tela:

To run this script, you will need to replace YOUR_CUSTOMER_ID with your actual
Google Ads customer ID and execute the following command in
your shell: <command>

Insira run. O script será executado no contexto do assistente se o idioma padrão for Python, Ruby ou PHP. As linguagens compiladas não serão executadas devido às políticas de segurança.

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

• Assistência para solução de problemas:receba ajuda com mensagens de erro ou comportamento inesperado da API.

  • "Recebi o erro 'AuthenticationError.OAUTH_TOKEN_INVALID'. O que devo fazer?"
  • "Por que não estou recebendo resultados para minha consulta?"

• Contexto adicional:adicione sua base de código para contexto.

  • A partir da versão 2.3.0, use a flag context_dir para incluir os arquivos do projeto: ./update.sh --context_dir /path/to/your/codebase Isso permite que o assistente inclua a lógica do aplicativo no raciocínio ao criar respostas.
  • Esse recurso permite que o assistente produza exemplos de código salvos no idioma escolhido, oferecendo suporte mesmo quando uma biblioteca de cliente oficial não está disponível.
  • Antes de solicitar a saída do código, diga ao assistente: write saved code examples in <language of your application>

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.