Servicios avanzados de Google

Los servicios avanzados de Apps Script permiten a los desarrolladores experimentados conectarse a ciertas API públicas de Google con menos configuración que si usaran sus interfaces HTTP. Básicamente, los servicios avanzados son wrappers finos alrededor de esas API de Google. Funcionan de la misma manera que los servicios integrados de Apps Script, por ejemplo, ofrecen autocompletado, y Apps Script controla 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 con una API pública de Google. En Apps Script, puedes acceder a estas API a través de servicios avanzados o simplemente haciendo las solicitudes a la API directamente con UrlFetch.

Si usas el método de servicio avanzado, Apps Script controla el flujo de autorización y ofrece asistencia para el 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 tú mismo. También debes crear 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:

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 a partir del 8 de abril de 2019, la API se habilita de forma automática después de que habilitas el servicio avanzado y guardas el proyecto de secuencia de comandos. Si aún no lo hiciste, es posible que también se te solicite aceptar las Condiciones del Servicio de Google Cloud y las API de Google.

   Si el proyecto de la 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 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 Google Cloud.
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 cuando lo veas.
3. En la pantalla siguiente, haga clic en Habilitar API.
4. Cierre Google Cloud Console y vuelva 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 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 API públicas correspondientes, aunque las firmas de los métodos se traducen para su uso en Apps Script. Por lo general, la función de autocompletado del editor de secuencias de comandos proporciona información suficiente para comenzar, pero en las reglas a continuación se explica cómo Apps Script genera una firma de método desde una API pública de Google.

Las solicitudes a las API de Google pueden aceptar diversos tipos de datos, como parámetros de ruta de acceso, parámetros de búsqueda, un cuerpo de solicitud o un archivo 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) en forma de objeto JavaScript.
2. Ruta o parámetros obligatorios, 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 los valores
5. Encabezados de solicitud HTTP, como un objeto JavaScript que asigna nombres de encabezado a los 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 a tener en cuenta:

• Para los métodos que aceptan una carga de contenido multimedia, el parámetro uploadType se establece de forma automática.
• 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 solicitud HTTP y estableces un objeto de JavaScript de encabezados de solicitud, también debes configurar el objeto de 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 finos que permiten el uso de una API de Google dentro de Apps Script. Por lo tanto, cualquier problema que se encuentre durante su uso 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 asistencia para la API subyacente. Se proporcionan vínculos a estas instrucciones de asistencia en cada guía de servicio avanzada de la sección Referencia de Apps Script.