Servicios avanzados de Google

Los servicios avanzados de Apps Script permiten que los desarrolladores experimentados se conecten a ciertas API públicas de Google con menos configuración que con sus interfaces HTTP. En esencia, los servicios avanzados son wrappers estrechos alrededor de esas API de Google. Funcionan de manera muy similar a los servicios integrados de Apps Script. Por ejemplo, ofrecen autocompletado y Apps Script maneja el flujo de autorización de forma automática. Sin embargo, debes habilitar un servicio avanzado antes de poder usarlo en una secuencia de comandos.

Para ver qué API 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 un servicio avanzado, simplemente conéctate a ella como cualquier otra API externa.

¿Servicios avanzados o HTTP?

Cada uno de los servicios avanzados de Google está asociado a una API pública de Google. En Apps Script, puedes acceder a estas API a través de servicios avanzados o con tan solo realizar 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 autocompletado. 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, lo que haces es esencialmente tratar la API de Google como una API externa. Con este método, se pueden usar todos los aspectos de la API. Sin embargo, debes manejar la autorización de la API. 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 cuando sea posible y solo usar el método UrlFetch cuando el servicio avanzado no proporciona la funcionalidad que necesitas.

Requisitos

Antes de usar un servicio avanzado, debes cumplir con los siguientes requisitos:

1. Debes habilitar el servicio avanzado en tu proyecto de secuencia de comandos.

2. 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 de esa fecha, 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, también se te puede pedir que aceptes las Condiciones del Servicio de Google Cloud Platform y las API de Google.

   Si tu proyecto de secuencia de comandos usa un proyecto de GCP estándar o un proyecto de GCP predeterminado más antiguo, 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:

1. Abre el proyecto de Apps Script.
2. A la izquierda, haz clic en Editor .
3. A la izquierda, junto a Servicios, haz clic en Agregar un servicio .
4. Selecciona un servicio avanzado de Google y haz clic en Agregar.

Nota: Si usas un proyecto de GCP estándar (o un proyecto de GCP predeterminado más antiguo que se creó antes del 8 de abril de 2019), también debes habilitar de forma manual la API correspondiente al servicio avanzado. Para habilitar la API, haz lo siguiente:

1. Abre el proyecto de GCP asociado con tu secuencia de comandos en la Consola de API de Google.
2. En la parte superior de la consola, haz clic en la barra de búsqueda y escribe parte del nombre de la API (por ejemplo, "Calendario); luego, haz clic en el nombre una vez que lo veas.
3. En la siguiente pantalla, haga clic en Habilitar API.
4. Cierra la consola de API y regresa al editor de secuencias de comandos. Haz clic en Aceptar en el cuadro de diálogo.

Después de habilitar un servicio avanzado, estará disponible en autocompletar.

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 API públicas correspondientes, aunque las firmas de métodos se traducen para su uso en Apps Script. La función de autocompletado del editor de secuencias de comandos suele proporcionar suficiente información para comenzar, pero las reglas a continuación explican cómo Apps Script genera una firma de método a partir de una API de Google pública.

Las solicitudes a las API de Google pueden aceptar una variedad de tipos de datos diferentes, incluidos los parámetros de ruta, los parámetros de búsqueda, un cuerpo de solicitud o un adjunto de carga de contenido 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:

1. El cuerpo de la solicitud (por lo general, un recurso) como un objeto JavaScript.
2. Ruta o parámetros requeridos, como argumentos individuales.
3. El archivo adjunto de carga de contenido multimedia, como argumento Blob
4. Parámetros opcionales, como un objeto JavaScript que asigna nombres de parámetros a valores
5. Encabezados de solicitud HTTP, como un objeto 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 uploadType se establece automáticamente.
• Los métodos llamados delete en la API de Google se denominan remove en Apps Script, ya que delete es una palabra reservada en JavaScript.
• Si un servicio avanzado está configurado para aceptar encabezados de solicitudes HTTP y configuras un objeto JavaScript de encabezados de solicitud, también debes establecer los parámetros opcionales de objeto JavaScript (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 en Apps Script. Por lo tanto, cualquier problema que se encuentre mientras se usa suele ser un problema con la API subyacente, no con Apps Script.

Si tienes un problema mientras usas un servicio avanzado, debes informarlo con las instrucciones de asistencia de la API subyacente. Los vínculos a estas instrucciones de asistencia se proporcionan en cada guía de servicio avanzada de la sección Referencia de Apps Script.