Servicios avanzados de Google

Los servicios avanzados de 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. Sin embargo, debes habilitar un servicio avanzado antes de poder 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

Puedes habilitar un servicio avanzado con el editor de Apps Script o editando el manifiesto.

Método A: Usa el editor

1. Abre el proyecto de Apps Script.
2. A la izquierda, haz clic en 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

Puedes habilitar 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 predeterminado de Google Cloud (creado automáticamente por Apps Script), puedes omitir 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, también debes habilitar 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, pero las siguientes reglas explican 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 Google 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 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.

Existen algunas excepciones especiales que debes tener en cuenta:

• En el caso de los métodos que aceptan una carga de medios, el parámetro uploadType se establece automáticamente.
• Los métodos denominados 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

Supongamos que quieres crear un evento de calendario. 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 uno de los servicios de Google avanzados está asociado con una API pública de Google. En Apps Script, puedes acceder a estas APIs con servicios avanzados o realizar 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. Sin embargo, debes habilitar el servicio avanzado antes de poder 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, se pueden usar todos los aspectos de la API. Sin embargo, requiere que manejes 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 en la complejidad entre crear un evento de calendario 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);

Te recomendamos que uses un servicio avanzado siempre que sea posible y que solo uses 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, debes denunciarlo siguiendo las instrucciones de asistencia para la API subyacente.