Servicios avanzados de Google

Los servicios avanzados de Google Apps Script te permiten conectarte a ciertas APIs públicas de Google con menos configuración que si usaras sus interfaces HTTP. Los servicios avanzados son wrappers delgados en torno a esas APIs de Google. Funcionan de manera muy similar a los servicios integrados de Apps Script. Por ejemplo, ofrecen autocompletado y Apps Script controla el flujo de autorización automáticamente. Habilita un servicio avanzado antes de usarlo en una secuencia de comandos.

Habilita los servicios avanzados

Para usar un servicio avanzado de Google, sigue estas instrucciones:

Paso 1: Habilita el servicio avanzado

Habilita un servicio avanzado con el editor de Apps Script o edita el manifiesto.

Método A: Usa el editor

  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.

Método B: Usa el manifiesto

Habilita los servicios avanzados editando el archivo de manifiesto. Por ejemplo, para habilitar el servicio avanzado de Google Drive, agrega el campo enabledAdvancedServices al objeto dependencies:

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

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

Paso 2: Habilita la API de Google Cloud (solo para proyectos estándar de Google Cloud)

Si usas un proyecto de Google Cloud predeterminado (creado automáticamente por Apps Script), omite este paso. La API se habilita automáticamente cuando agregas el servicio en el paso 1.

Si usas un proyecto estándar de Google Cloud, habilita manualmente la API correspondiente al servicio avanzado. Para habilitar la API de forma manual, sigue estos pasos:

  1. Abre el proyecto de Cloud 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, "Calendar"). Luego, haz clic en el nombre cuando lo veas.

  3. Haz clic en Habilitar API.

  4. Cierra la consola de Google Cloud y regresa al editor de secuencias de comandos.

Cómo se determinan las firmas de métodos

En 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. La función de autocompletar del editor de secuencias de comandos suele proporcionar suficiente información para comenzar. En las siguientes reglas, se explica cómo Apps Script genera una firma de método a partir de una API pública de Google.

Las solicitudes a las APIs de Google pueden aceptar una variedad de tipos de datos diferentes, incluidos parámetros de ruta, parámetros de búsqueda, un cuerpo de solicitud o un archivo adjunto de carga de medios. Algunos servicios avanzados también pueden aceptar encabezados de solicitudes HTTP específicos (por ejemplo, el servicio avanzado de Calendar).

La firma del método correspondiente en Apps Script tiene los siguientes argumentos:

  1. El cuerpo de la solicitud (por lo general, un recurso), como un objeto JavaScript.
  2. Ruta de acceso o parámetros obligatorios, como argumentos individuales. Si el método requiere varios parámetros de ruta de acceso, estos aparecen en el orden en que se enumeran en la URL del extremo de la API.
  3. El archivo adjunto de carga de medios, como un argumento Blob
  4. Parámetros opcionales (por lo general, parámetros de consulta), 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.

Ten en cuenta estas excepciones:

  • En el caso de los métodos que aceptan una carga de medios, el parámetro uploadType se establece automáticamente.
  • Los métodos llamados delete en la API de Google se llaman 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 estableces un objeto JavaScript de encabezados de solicitudes, también debes establecer el objeto JavaScript de parámetros opcionales (en un objeto vacío si no usas parámetros opcionales).

Ejemplo: Calendar.Events.insert

Para crear un evento de calendario, sigue estos pasos:

La documentación de la API de Google Calendar muestra la estructura de la solicitud HTTP correspondiente:

  • Verbo HTTP: POST
  • URL de la solicitud: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events

  • Cuerpo de la solicitud: Es un recurso Event.

  • Parámetros de consulta: sendUpdates, supportsAttachments, etcétera

En Apps Script, la firma del método se determina reordenando estas entradas:

  1. Cuerpo: Es el recurso del evento (objeto JavaScript).
  2. Ruta: Es calendarId (cadena).
  3. Parámetros opcionales: Son los parámetros de la consulta (objeto JavaScript).

La llamada al método resultante se ve de la siguiente manera:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

¿Servicios avanzados o HTTP?

Cada servicio avanzado de Google está asociado a una API pública de Google. En Apps Script, accede a estas APIs con servicios avanzados o realiza 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 compatibilidad con la función de autocompletar. Habilita el servicio avanzado antes de usarlo.

Si usas el método UrlFetch para acceder directamente a la API, básicamente tratas la API de Google como una API externa. Con este método, puedes usar todos los aspectos de la API. Sin embargo, debes controlar la autorización de la API.

En la siguiente tabla, se comparan los dos métodos:

Función Servicio avanzado UrlFetch (HTTP)
Autorización Se maneja automáticamente Se requiere manipulación manual
Autocompletar Disponible No disponible
Alcance de la funcionalidad Puede ser un subconjunto de la API Acceso completo a todas las funciones de la API
Complejidad Más fácil Más complejo (requiere construir encabezados y analizar respuestas)

Comparación de código

En los ejemplos de código, se muestra la diferencia en la complejidad entre crear un evento de Calendar con el servicio avanzado y con UrlFetchApp.

Servicio avanzado:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

UrlFetch (HTTP):

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

En el caso del método UrlFetchApp, especifica manualmente los permisos de OAuth necesarios en el archivo de manifiesto de la secuencia de comandos.

Usa un servicio avanzado siempre que sea posible y solo usa el método UrlFetch cuando el servicio avanzado no esté disponible o no proporcione la funcionalidad que necesitas.

Compatibilidad con servicios avanzados

Dado que los servicios avanzados son wrappers delgados en torno a las APIs de Google, cualquier problema que se encuentre al usarlos suele ser un problema con la API subyacente, no con Apps Script.

Si tienes un problema mientras usas un servicio avanzado, infórmalo siguiendo las instrucciones de asistencia para la API subyacente.