Servicio avanzado de Eventos de Google Workspace

El servicio avanzado de eventos de Google Workspace te permite usar la API de Google Workspace Events en Apps Script. Con esta API, puedes suscribirte a recursos de Google Workspace para recibir eventos relevantes que te interesan. Los eventos representan cambios en los recursos, como cuando se crean, actualizan o borran recursos.

Requisitos previos

  • Un proyecto de Apps Script que usa un proyecto estándar de Google Cloud en lugar del predeterminado que crea automáticamente Apps Script.
  • Un tema de Pub/Sub creado en el mismo proyecto de Google Cloud para recibir eventos de suscripción. Para crear un tema de Pub/Sub, consulta Crea un tema de Pub/Sub y suscríbete a él.
  • Para suscribirte a los eventos de Chat, debes tener una app de Google Chat configurada en la página de configuración de la API de Chat en la consola de Google Cloud. Para crear una app de Google Chat, consulta Compila una app de Google Chat con Apps Script.

  • Los permisos de autorización necesarios se agregaron al archivo appsscript.json del proyecto de Apps Script. Los alcances necesarios dependen de los tipos de recursos y eventos de destino de las suscripciones. Para obtener más información, consulta Cómo elegir los alcances de la API de Google Workspace Events. Por ejemplo:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.readonly"
]

Referencia

Para obtener más información sobre este servicio, consulta la documentación de referencia de la API de Google Workspace Events. Al igual que todos los servicios avanzados de Apps Script, el servicio de Google Workspace Events usa los mismos objetos, métodos y parámetros que la API pública.

Código de muestra

En estos ejemplos, se muestra cómo realizar acciones comunes de la API de Google Workspace Events con el servicio avanzado.

Crea una suscripción

Para crear una suscripción a un recurso de Google Workspace, agrega la siguiente función al código del proyecto de Apps Script:

advanced/events.gs
/**
 * Creates a subscription to receive events about a Google Workspace resource.
 * For a list of supported resources and event types, see the
 * [Google Workspace Events API Overview](https://developers.google.com/workspace/events#supported-events).
 * For additional information, see the
 * [subscriptions.create](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/create)
 * method reference.
 * @param {!string} targetResource The full resource name of the Google Workspace resource to subscribe to.
 * @param {!string|!Array<string>} eventTypes The types of events to receive about the resource.
 * @param {!string} pubsubTopic The resource name of the Pub/Sub topic that receives events from the subscription.
 */
function createSubscription(targetResource, eventTypes, pubsubTopic) {
  try {
    const operation = WorkspaceEvents.Subscriptions.create({
      targetResource: targetResource,
      eventTypes: eventTypes,
      notificationEndpoint: {
        pubsubTopic: pubsubTopic,
      },
    });
    console.log(operation);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to create subscription with error %s', err.message);
  }
}

Enumerar suscripciones

Para enumerar las suscripciones filtradas por tipos de eventos y recursos de destino, agrega la siguiente función al código del proyecto de Apps Script:

advanced/events.gs
/**
 * Lists subscriptions created by the calling app filtered by one or more event types and optionally by a target resource.
 * For additional information, see the
 * [subscriptions.list](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/list)
 * method reference.
 * @param {!string} filter The query filter.
 */
function listSubscriptions(filter) {
  try {
    const response = WorkspaceEvents.Subscriptions.list({ filter });
    console.log(response);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to list subscriptions with error %s', err.message);
  }
}

Obtener suscripción

Para obtener información sobre una suscripción, agrega la siguiente función al código del proyecto de Apps Script:

advanced/events.gs
/**
 * Gets details about a subscription.
 * For additional information, see the
 * [subscriptions.get](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/get)
 * method reference.
 * @param {!string} name The resource name of the subscription.
 */
function getSubscription(name) {
  try {
    const subscription = WorkspaceEvents.Subscriptions.get(name);
    console.log(subscription);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to get subscription with error %s', err.message);
  }
}

Actualizar suscripción

Para actualizar o renovar una suscripción, agrega la siguiente función al código del proyecto de Apps Script:

advanced/events.gs
/**
 * Updates an existing subscription.
 * This can be used to renew a subscription that is about to expire.
 * For additional information, see the
 * [subscriptions.patch](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/patch)
 * method reference.
 * @param {!string} name The resource name of the subscription.
 */
function patchSubscription(name) {
  try {
    const operation = WorkspaceEvents.Subscriptions.patch({
      // Setting the TTL to 0 seconds extends the subscription to its maximum expiration time.
      ttl: '0s',
    }, name);
    console.log(operation);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to update subscription with error %s', err.message);
  }
}

Reactivar la suscripción

Para reactivar una suscripción, agrega la siguiente función al código del proyecto de Apps Script:

advanced/events.gs
/**
 * Reactivates a suspended subscription.
 * Before reactivating, you must resolve any errors with the subscription.
 * For additional information, see the
 * [subscriptions.reactivate](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/reactivate)
 * method reference.
 * @param {!string} name The resource name of the subscription.
 */
function reactivateSubscription(name) {
  try {
    const operation = WorkspaceEvents.Subscriptions.reactivate({}, name);
    console.log(operation);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to reactivate subscription with error %s', err.message);
  }
}

Borrar suscripción

Para borrar una suscripción, agrega la siguiente función al código del proyecto de Apps Script:

advanced/events.gs
/**
 * Deletes a subscription.
 * For additional information, see the
 * [subscriptions.delete](https://developers.google.com/workspace/events/reference/rest/v1/subscriptions/delete)
 * method reference.
 * @param {!string} name The resource name of the subscription.
 */
function deleteSubscription(name) {
  try {
    const operation = WorkspaceEvents.Subscriptions.remove(name);
    console.log(operation);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to delete subscription with error %s', err.message);
  }
}

Obtener operación

La mayoría de los métodos de la API de Google Workspace Events devuelven una operación de larga duración. Para determinar el estado de la operación, puedes usar el método operations.get().

Para obtener información sobre una operación, agrega la siguiente función al código del proyecto de Apps Script:

advanced/events.gs
/**
 * Gets details about an operation returned by one of the methods on the subscription
 * resource of the Google Workspace Events API.
 * For additional information, see the
 * [operations.get](https://developers.google.com/workspace/events/reference/rest/v1/operations/get)
 * method reference.
 * @param {!string} name The resource name of the operation.
 */
function getOperation(name) {
  try {
    const operation = WorkspaceEvents.Operations.get(name);
    console.log(operation);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to get operation with error %s', err.message);
  }
}

Para obtener el nombre de una operación, usa el valor del campo name que se muestra en uno de los métodos de la API de Google Workspace Events, como subscriptions.create() o subscriptions.patch().