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:

  2. Software:

    • Python 3.10 ou mais recente. Python é a linguagem padrão. Portanto, ela precisa estar instalada e no seu caminho.
    • O gemini-cli instalado.
    • jq (processador JSON da linha de comando). O script de instalação tentará instalar esse pacote se ele estiver faltando.

  3. Repositório:

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:ele 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 a gemini-cli:

    gemini

  4. Interagir com o Google Assistente:agora é possível fazer perguntas ou dar comandos em linguagem natural.

Principais recursos

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

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

  • Geração de código:gere consultas da 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 da gemini-cli e confira os resultados formatados no terminal. Depois que o Assistente gerar o código, você vai receber uma solicitação 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>

Digite run. O script será executado no contexto do Google Assistente se o idioma padrão for Python, Ruby ou PHP. Linguagens compiladas não serão executadas devido a 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/.

  • Ajuda para resolver 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 aparecem resultados para minha consulta?"

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 e IDs das campanhas."
  • Solução de problemas:
    • "Fiz o upload de 100 conversões, mas apenas 78 aparecem na interface. Como posso depurar isso usando a API?"
  • Aprendizado:
    • "/explain what a shared set is"
  • Geração de código:
    • "Escreva um código para criar uma campanha Performance Max para company name."

Comunidade e suporte

Diretrizes de contribuição

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