Los servicios avanzados de Apps Script permiten a los desarrolladores experimentados conectarse a ciertas APIs públicas de Google con menos configuración que con sus interfaces HTTP. Los servicios avanzados son, en esencia, wrappers delgados en torno a esas APIs de Google. Funcionan de manera muy similar a los servicios integrados de Apps Script. Por ejemplo, ofrecen la función de autocompletar y Apps Script maneja el flujo de autorización automáticamente. Sin embargo, debes habilitar un servicio avanzado antes de poder usarlo en una secuencia de comandos.
Para ver qué APIs de Google están disponibles como servicios avanzados, busca la sección Servicios avanzados de Google en la Referencia. Si deseas usar una API de Google que no está disponible como servicio avanzado, solo conéctate a ella como a cualquier otra API externa.
¿Servicios avanzados o HTTP?
Cada uno de los servicios avanzados de Google está asociado con una API pública de Google.
En Apps Script, puedes acceder a estas APIs a través de servicios avanzados o simplemente
realizando las solicitudes a la API directamente con
UrlFetch.
Si usas el método de servicio avanzado, Apps Script maneja el flujo de autorización y ofrece compatibilidad con la función de autocompletar. Sin embargo, debes habilitar el servicio avanzado antes de poder usarlo. Además, algunos servicios avanzados solo proporcionan un subconjunto de la funcionalidad disponible en la API.
Si usas el método UrlFetch para acceder a la API directamente, en esencia, tratas la API de Google como una API externa. Con este método, se pueden usar todos los aspectos de la API. Sin embargo, requiere que controles la autorización de la API por tu cuenta. También debes construir los encabezados necesarios y analizar las respuestas de la API.
En general, es más fácil usar un servicio avanzado siempre que sea posible y solo usar el método UrlFetch cuando el servicio avanzado no proporciona la funcionalidad que necesitas.
Requisitos
Antes de poder usar un servicio avanzado, debes cumplir con los siguientes requisitos:
- Debes habilitar el servicio avanzado en el proyecto de secuencia de comandos.
Debes asegurarte de que la API correspondiente al servicio avanzado esté habilitada en el proyecto de Cloud Platform (GCP) que usa tu secuencia de comandos.
Si tu proyecto de secuencia de comandos usa un proyecto de GCP predeterminado creado el 8 de abril de 2019 o después, la API se habilita automáticamente después de que habilites el servicio avanzado y guardes el proyecto de secuencia de comandos. Si aún no lo has hecho, es posible que también se te solicite que aceptes las Condiciones del Servicio de Google Cloud y de las APIs de Google.
Si tu proyecto de secuencia de comandos usa un proyecto de GCP estándar o uno predeterminado anterior, debes habilitar la API correspondiente del servicio avanzado en el proyecto de GCP de forma manual. Debes tener acceso de edición al proyecto de GCP para realizar este cambio.
Consulta Proyectos de Cloud Platform para obtener más información.
Habilitar servicios avanzados
Para usar un servicio avanzado de Google, sigue estas instrucciones:
- Abre el proyecto Apps Script.
- A la izquierda, haz clic en Editor .
- A la izquierda, junto a Servicios, haz clic en Agregar un servicio .
- Selecciona un servicio avanzado de Google y haz clic en Agregar.
Una vez que habilites un servicio avanzado, estará disponible en el autocompletado.
Cómo se determinan las firmas de métodos
Por lo general, los servicios avanzados usan los mismos objetos, nombres de métodos y parámetros que las APIs públicas correspondientes, aunque las firmas de métodos se traducen para su uso en Apps Script. Por lo general, la función de autocompletado del editor de secuencia de comandos proporciona suficiente información para comenzar, pero las siguientes reglas explican cómo Apps Script genera una firma de método a partir de una API de Google pública.
Las solicitudes a las APIs de Google pueden aceptar una variedad de tipos diferentes de datos, incluidos parámetros de ruta de acceso, parámetros de consulta, un cuerpo de solicitud o un archivo adjunto de carga de archivos multimedia. Algunos servicios avanzados también pueden aceptar encabezados de solicitud HTTP específicos (por ejemplo, el servicio avanzado de Calendario).
La firma del método correspondiente en Google Apps Script tiene los siguientes argumentos:
- Cuerpo de la solicitud (por lo general, un recurso), como un objeto de JavaScript
- Ruta de acceso o parámetros obligatorios, como argumentos individuales.
- El archivo adjunto de carga de contenido multimedia, como argumento
Blob - Parámetros opcionales, como un objeto JavaScript que asigna nombres de parámetros a valores.
- Encabezados de la solicitud HTTP, como un objeto de JavaScript que asigna nombres de encabezado a valores de encabezado
Si el método no tiene ningún elemento en una categoría determinada, se omite esa parte de la firma.
Existen algunas excepciones especiales que debes tener en cuenta:
- Para los métodos que aceptan una carga de contenido multimedia, el parámetro
uploadTypese establece automáticamente. - Los métodos llamados
deleteen la API de Google se denominanremoveen Apps Script, ya quedeletees una palabra reservada en JavaScript. - Si se configura un servicio avanzado para aceptar encabezados de solicitud HTTP y configuras un objeto de JavaScript de encabezados de solicitud, también debes configurar el objeto JavaScript de parámetros opcionales (en un objeto vacío si no usas parámetros opcionales).
Asistencia para servicios avanzados
Los servicios avanzados son solo wrappers delgados que permiten el uso de una API de Google dentro de Apps Script. Por lo tanto, cualquier problema que se encuentre mientras se usan suele ser un problema con la API subyacente, no con Apps Script.
Si encuentras un problema mientras usas un servicio avanzado, debes informarlo con las instrucciones de compatibilidad de la API subyacente. En cada guía de servicio avanzada, se proporcionan vínculos a estas instrucciones de asistencia en la sección Referencia de Apps Script.