Serviço avançado de eventos do Google Workspace

Com o serviço Advanced Google Workspace Events, é possível usar a API Google Workspace Events no Apps Script. Essa API permite que você se inscreva nos recursos do Google Workspace para receber eventos relevantes do seu interesse. Os eventos representam alterações nos recursos, como quando eles são criados, atualizados ou excluídos.

Pré-requisitos

  • Um projeto do Apps Script usando um projeto padrão do Google Cloud em vez daquele criado automaticamente pelo Apps Script.
  • Um tópico do Pub/Sub criado no mesmo projeto do Google Cloud para receber eventos de assinatura. Para criar um tópico do Pub/Sub, consulte Criar e assinar um tópico do Pub/Sub.
  • Para se inscrever em eventos do Chat, você precisa ter um app do Google Chat configurado na página de configuração da API Chat no console do Google Cloud. Para criar um app do Google Chat, consulte Criar um app do Google Chat com o Apps Script.

  • Os escopos de autorização necessários foram adicionados ao arquivo appsscript.json do projeto do Apps Script. Os escopos necessários dependem dos tipos de recursos e eventos de destino das assinaturas. Para mais detalhes, consulte Escolher escopos da API Events do Google Workspace. Exemplo:

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

Referência

Para mais informações sobre esse serviço, consulte a documentação de referência da API Google Workspace Events. Assim como todos os serviços avançados no Apps Script, o serviço de eventos do Google Workspace usa os mesmos objetos, métodos e parâmetros que a API pública.

Exemplo de código

Nestes exemplos, mostramos como executar ações comuns da API Eventos do Google Workspace usando o serviço avançado.

Crie uma assinatura

Para criar uma assinatura de um recurso do Google Workspace, adicione a seguinte função ao código do projeto do 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);
  }
}

Listar assinaturas

Para listar assinaturas filtradas por tipos de evento e recurso de destino, adicione a seguinte função ao código do projeto do 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);
  }
}

Acessar assinatura

Para ver informações sobre uma assinatura, adicione a seguinte função ao código do projeto do 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);
  }
}

Atualizar assinatura

Para atualizar ou renovar uma assinatura, adicione a seguinte função ao código do projeto do 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);
  }
}

Reativar assinatura

Para reativar uma assinatura, adicione a seguinte função ao código do projeto do 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);
  }
}

Excluir assinatura

Para excluir uma assinatura, adicione a seguinte função ao código do projeto do 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);
  }
}

Receber operação

A maioria dos métodos da API Events do Google Workspace retorna uma operação de longa duração. Para determinar o status da operação, use o método operations.get().

Para receber informações sobre uma operação, adicione a seguinte função ao código do projeto do 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 ver o nome de uma operação, use o valor do campo name retornado de um dos métodos da API Events do Google Workspace, como subscriptions.create() ou subscriptions.patch().