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 product.

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, que suele ubicarse 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 versiones posteriores. (Python es el lenguaje predeterminado, por lo que debes tenerlo instalado y en tu ruta de acceso)
   • gemini-cli instalado
   • 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 google-ads-api-developer-assistant repositorio de GitHub:

Comenzar

1. Navega al directorio del proyecto:

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

2. Ejecuta la secuencia de comandos de configuración: Esta secuencia de comandos configura gemini-cli para usar los archivos de contexto GEMINI.md del asistente y las herramientas necesarias.

   ./install.sh
   

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

3. Inicia gemini-cli:

   gemini
   

4. Interactúa con el Asistente: Ahora puedes hacer preguntas o dar comandos en lenguaje natural.

Características clave

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

  • "¿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 anuncios rechazados en todas las campañas." El código generado se guarda en el directorio saved_code/.

• Ejecución directa de la API: Ejecuta secuencias de comandos de Python de solo lectura generadas directamente desde gemini-cli y visualiza los resultados con formato en tu terminal. Después de que el Asistente genere el código, recibirás un mensaje en pantalla:

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>

Ingresa run y la secuencia de comandos se ejecutará en el contexto del Asistente si tu lenguaje predeterminado es Python, Ruby o PHP. Los lenguajes compilados no se ejecutarán debido a las políticas de seguridad.

• Exportación de 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/.

• Asistencia para la solución de problemas: Obtén ayuda con los mensajes de error o el comportamiento inesperado de la API.

  • "Recibí el error 'AuthenticationError.OAUTH_TOKEN_INVALID'. ¿Qué debo hacer?"
  • "¿Por qué no veo ningún resultado para mi consulta?"

• Contexto adicional: Agrega tu base de código para el contexto.

  • A partir de la versión 2.3.0, usa la marca context_dir para incluir los archivos de tu proyecto: ./update.sh --context_dir /path/to/your/codebase Esto permite que el Asistente incluya la lógica de tu aplicación en su razonamiento cuando crea respuestas.
  • Esta función permite que el Asistente produzca ejemplos de código guardados en el idioma que elijas, lo que proporciona asistencia incluso cuando no hay una biblioteca cliente oficial disponible.
  • Antes de solicitar el resultado del código, dile al Asistente: write saved code examples in <language of your application>.

Ejemplos de casos de uso

• Informes:
  • "Obtén 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 aparecen 78 en la IU. ¿Cómo puedo depurar esto con la API?"
• Aprendizaje:
  • "/explain 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 solicita ayuda en la pestaña Issues del repositorio.
• Discord: Únete al debate 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 las contribuciones

¡Agradecemos tus contribuciones! Consulta el archivo CONTRIBUTING.md en el repositorio de GitHub para obtener los lineamientos.