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 similar a los servicios integrados de Apps Script. Por ejemplo, ofrecen autocompletado y Apps Script controla el flujo de autorización de forma automática. Habilita un servicio avanzado antes de usarlo en una secuencia de comandos.

Cómo habilitar 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 el código del editor code.
3. A la izquierda, junto a Servicios, haz clic en Agregar un servicio add.
4. Selecciona un servicio avanzado de Google y haz clic en Agregar.

Método B: Usa el manifiesto

Para habilitar los servicios avanzados, edita 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 predeterminado de Google Cloud (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 estándar proyecto de Google Cloud, habilita de forma manual la API correspondiente al servicio avanzado. Para habilitar la API de forma manual, haz lo siguiente:

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

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 usarse en Apps Script. La función de autocompletado 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 consulta, un cuerpo de solicitud o un adjunto de carga de medios. Algunos servicios avanzados también pueden aceptar encabezados de solicitud HTTP específicos (por ejemplo, el servicio avanzado de Calendar).

La firma de 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. Parámetros de ruta o obligatorios, como argumentos individuales. Si el método requiere varios parámetros de ruta, aparecen en el orden en que se enumeran en la URL del extremo de la API.
3. El adjunto de carga de medios, como un Blob argumento.
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 encabezados a valores de encabezados.

Si el método no tiene elementos en una categoría determinada, se omite esa parte de la firma.

Ten en cuenta estas excepciones:

• Para 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 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 JavaScript de encabezados de solicitud, 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 Calendar evento, haz lo siguiente:

En la documentación de la API de Google Calendar, se muestra la estructura de solicitud HTTP correspondiente:

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

• Cuerpo de la solicitud: Un recurso Event.

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

En Apps Script, la firma del método se determina mediante la reordenación de estas entradas:

1. Cuerpo: El recurso de evento (objeto JavaScript).
2. Ruta: El calendarId (cadena).
3. Parámetros opcionales: Los parámetros de 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 con una API pública de Google. En Apps Script, accede a estas APIs con servicios avanzados o realizando 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 el autocompletado. Habilita el servicio avanzado antes de usarlo.

Si usas el método UrlFetch para acceder a la API directamente, básicamente tratas la API de Google como una API externa. Con este método, usa 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:

Comparación de código

En los ejemplos de código, se muestra la diferencia de complejidad entre crear un evento de Calendar con el servicio avanzado y usar 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);

Para el método UrlFetchApp, especifica de forma manual los permisos de OAuth obligatorios 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

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

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