Instala y usa el Asistente para desarrolladores de la API de Google Ads

Nota: Esta herramienta es un proyecto de código abierto y no un producto oficial de Google.

Requisitos previos

Antes de comenzar, asegúrate de tener lo siguiente:

1. Acceso a la API de Google Ads:

   • Un token de desarrollador de la API de Google Ads
   • Un archivo de configuración de Google Ads configurado con tu token de desarrollador, credenciales de OAuth 2.0 y el ID de cliente, ubicado en tu directorio principal Consulta la guía de configuración de la biblioteca cliente.
   • Conocimiento de los conceptos y la autenticación de la API de Google Ads

2. Software:

   • Python 3.10 o una versión posterior Python es el lenguaje predeterminado, por lo que debes tenerlo instalado y en tu ruta de acceso.
   • Se instaló la herramienta de línea de comandos de Google Antigravity.
   • jq (procesador JSON de línea de comandos) La secuencia de comandos de instalación intentará instalarlo si falta.

3. Repositorio:

   • Una clonación local del repositorio de google-ads-api-developer-assistant de GitHub

Comenzar

1. Navega al directorio del proyecto:

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

   (Nota: Si tienes habilitada la integración de la shell de Antigravity, ingresar a este directorio inicializará automáticamente la sesión del asistente).

2. Ejecuta la secuencia de comandos de instalación: Esta secuencia de comandos inicializa el entorno de desarrollo y clona las bibliotecas cliente de Google Ads requeridas (Python se instala de forma predeterminada).

   ./install.sh
   

   Si usas Windows, ejecuta la secuencia de comandos de PowerShell install.ps1.

3. Configura las credenciales: Asegúrate de que tu google-ads.yaml (o su equivalente en el idioma) esté ubicado en tu directorio principal.

4. Interactúa con Asistente: Una vez que la sesión esté activa, podrás interactuar con Asistente en lenguaje natural directamente en la terminal.

Características clave

• Preguntas y respuestas en lenguaje natural: Haz preguntas sobre las funciones de la API de Google Ads, las prácticas recomendadas o los recursos específicos.

  • "¿Cuáles son los tipos de campaña disponibles?"
  • "¿Cómo filtro por fecha en GAQL?"
  • "Explica la diferencia entre click_view y impression_view".

• Generación de código: Genera consultas de GAQL y fragmentos de código de Python ejecutables.

  • "Muéstrame las campañas con la mayor cantidad de conversiones en los últimos 30 días".
  • "Obtén todos los nombres de los grupos de anuncios habilitados para el ID de campaña 12345".
  • "Busca los anuncios rechazados en todas las campañas". El código generado se verifica automáticamente con ruff y se guarda en el directorio saved/code/.

• Ejecución directa de la API: Ejecuta directamente las secuencias de comandos de Python de solo lectura generadas dentro de un entorno virtual aislado (.venv) y visualiza los resultados con formato de tablas en tu terminal.

  • Solo tienes que decirle al Asistente: "Ejecuta el código" o "Ejecuta la secuencia de comandos".
  • Por seguridad, se generan operaciones de mutación (crear, actualizar, borrar), pero nunca se ejecutan.

• Exportación a CSV: Guarda los resultados tabulares de las llamadas a la API en un archivo CSV.

  • "Guarda los resultados en un archivo CSV". Los archivos se guardan en el directorio saved/csv/.

• Diagnóstico y solución de problemas avanzados: Obtén ayuda con los mensajes de error, el comportamiento inesperado de la API o los problemas relacionados con las conversiones sin conexión.

  • "¿Por qué no veo ningún resultado para mi búsqueda?"
  • "Soluciona los problemas relacionados con las conversiones del cliente 123-456-7890" (genera un informe de diagnóstico detallado en saved/data/).

• Contexto adicional: Agrega tu propia base de código o bibliotecas personalizadas para proporcionar contexto.

  • Usa la secuencia de comandos update.sh con la opción --context_path para registrar los archivos de tu proyecto: none ./update.sh --context_path /path/to/your/codebase
  • Esto permite que el Asistente incluya la lógica de tu aplicación en su razonamiento cuando crea respuestas o genera código en tu idioma preferido.

Ejemplos de casos de uso

• Informes:
  • "Dame las 5 palabras clave principales por costo del mes pasado para el cliente 12345678".
• Estructura de la cuenta:
  • "Enumera todos los nombres de las campañas y sus IDs".
• Solución de problemas:
  • "Subí 100 conversiones, pero solo 78 aparecen en la IU. ¿Cómo puedo depurar esto con la API?"
• Aprendizaje:
  • "/explica qué es un conjunto compartido"
• Generación de código:
  • "Escribe código para crear una campaña de máximo rendimiento para company name".

Comunidad y asistencia

• Problemas de GitHub: Informa errores, sugiere funciones o pide ayuda en la pestaña Issues del repositorio.
• Discord: Únete a la conversación en el canal #ads-api-ai-tools del servidor de Discord de la comunidad de Google Advertising and Measurement.
• Comentarios: Comparte tus comentarios a través de este formulario de encuesta.

Lineamientos para la contribución

¡Se aceptan contribuciones! Consulta el archivo CONTRIBUTING.md en el repositorio de GitHub para obtener instrucciones.