Inscrever-se em eventos usando a API Google Workspace Events

Esta página oferece uma visão geral da API Google Workspace Events e explica como usá-la para se inscrever em eventos no Google Workspace.

Os eventos do Google Workspace representam mudanças nos recursos do Google Workspace, como a criação, atualização ou exclusão deles. Seu app pode assinar um recurso do Google Workspace para receber eventos relevantes do seu interesse.

Como seu app recebe eventos

Para permitir que seu app receba eventos do Google Workspace, use a API Google Workspace Events para criar assinaturas de recursos do Google Workspace.

No exemplo a seguir, veja como a API Google Workspace Events envia eventos para um app do Google Chat com uma assinatura:

1. Um app do Chat assina um espaço do Chat.
2. O espaço do Chat muda. Por exemplo, uma nova mensagem é postada no espaço.
3. O Chat envia um evento a um tópico no Google Cloud Pub/Sub, que serve como o endpoint de notificação da assinatura. O evento contém dados sobre o que mudou. Por exemplo, em um evento sobre uma nova mensagem, o evento contém detalhes sobre o recurso Message que é criado.
4. O app Chat processa a mensagem do Google Cloud Pub/Sub que contém o evento e, se necessário, toma medidas.

Terminologia importante

Confira a seguir uma lista de termos comuns usados na API Google Workspace Events:

Evento do Google Workspace

Uma mudança em um recurso do Google Workspace. Os eventos são formatados usando a especificação CloudEvents e podem ser um evento de assinatura ou um evento de ciclo de vida:

Evento de assinatura

Uma mudança no recurso do Google Workspace que você está monitorando, como uma nova mensagem em um espaço do Google Chat. Você pode especificar o nível de detalhes que quer receber sobre o recurso que mudou. Para mais detalhes, consulte Estrutura dos eventos do Google Workspace.

Evento do ciclo de vida

Um evento sobre sua assinatura do Google Workspace. Os eventos do ciclo de vida informam sobre problemas e o estado da sua assinatura para que você não perca eventos de assinatura. Por padrão, sua assinatura sempre recebe eventos do ciclo de vida. Para mais detalhes, consulte Eventos de ciclo de vida para assinaturas do Google Workspace.

Assinatura do Google Workspace

Uma entidade nomeada que monitora um recurso de um aplicativo do Google Workspace. Uma assinatura é representada por um recurso Subscription. Uma assinatura é definida pelas seguintes informações:

Recurso de destino

O recurso do Google Workspace que você quer monitorar. Esse recurso é representado no campo targetResource da assinatura do Google Workspace. Cada assinatura só pode monitorar um recurso. Para saber quais recursos do Google Workspace são compatíveis com a API Google Workspace Events, consulte Eventos compatíveis do Google Workspace.

Tipos de evento

Os tipos de mudanças sobre as quais você quer receber notificações para o recurso de destino. Por exemplo, se você se inscreveu em um espaço do Google Chat, pode escolher se quer receber eventos sobre o espaço e os recursos filhos dele, como associações e mensagens.

Endpoint de notificação

O endpoint em que a assinatura do Google Workspace recebe eventos. A API Google Workspace Events é compatível com tópicos do Google Cloud Pub/Sub como um endpoint de notificação. Para saber mais sobre como usar o Google Cloud Pub/Sub, consulte a documentação do Google Cloud Pub/Sub.

Opções de payload

Os dados de eventos que você quer receber sobre recursos alterados.

Eventos do Google Workspace compatíveis

Os eventos que seu app pode receber dependem do recurso de destino da assinatura. A tabela a seguir mostra os eventos compatíveis para cada recurso de destino possível.

Para saber mais, consulte os guias a seguir:

• Inscrever-se em eventos do Google Chat
• Inscrever-se nos eventos do Google Drive
• Inscrever-se em eventos do Google Meet

Estrutura dos eventos do Google Workspace

Os eventos do Google Workspace seguem a especificação CloudEvents, que é uma maneira padrão do setor de descrever dados de eventos. Os eventos do Google Workspace contêm o seguinte:

• Atributos do CloudEvent.
• Dados sobre o recurso do Google Workspace que mudou como resultado do evento

A seção a seguir explica a estrutura dos atributos e dados dos eventos do Google Workspace.

Atributos do CloudEvent

Os eventos do Google Workspace contêm os seguintes atributos de CloudEvents obrigatórios:

Dados do evento

Os dados de eventos são um payload que representa uma mudança no recurso de destino da sua assinatura, incluindo recursos filhos dele. Na sua assinatura, é possível especificar se você quer que o payload inclua dados sobre o recurso alterado ou apenas o nome dele.

Por exemplo, se você tiver uma assinatura de um espaço do Chat, poderá receber eventos sobre novas mensagens no espaço. Para eventos sobre novas mensagens, os dados do evento contêm um payload com o recurso spaces.message do Chat que foi criado.

Ao criar uma assinatura, você pode especificar quantos dados de recursos serão incluídos nos eventos que seu app recebe:

• Incluir dados de recursos:contém alguns ou todos os campos do recurso alterado. Se você incluir dados de recursos, a duração da assinatura será limitada a até 4 horas ou 24 horas se usar a delegação em todo o domínio.
• Excluir dados de recursos: contém apenas o nome do recurso alterado. A duração da assinatura é de até 7 dias. Para mais detalhes sobre o evento, consulte o recurso usando o nome dele.

Essas opções de dados de eventos são representadas no campo payloadOptions da sua assinatura.

Eventos como mensagens do Google Cloud Pub/Sub

As assinaturas da API Google Workspace Events usam tópicos do Google Cloud Pub/Sub como o endpoint de notificação que recebe eventos do Google Workspace. Os eventos são codificados como mensagens do Google Cloud Pub/Sub. Seu app pode processar a mensagem do Google Cloud Pub/Sub para realizar uma ação ou responder ao evento.

O exemplo a seguir mostra uma mensagem do Google Cloud Pub/Sub que contém um evento sobre uma mensagem atualizada em um espaço do Chat:

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

Observe os seguintes campos:

• attributes: atributos do CloudEvent, incluindo o tipo de evento. Nesse caso, o evento é sobre uma mensagem atualizada no espaço.
• data: os dados do evento com detalhes sobre o recurso spaces.message atualizado, formatados como uma string codificada em Base64.
• messageId: o identificador da mensagem do Google Cloud Pub/Sub.

Para saber mais sobre como os CloudEvents são especificados em mensagens do Google Cloud Pub/Sub, consulte Vinculação de protocolo do Google Cloud Pub/Sub para CloudEvents.

Temas relacionados

• Escolher escopos da API Google Workspace Events
• Criar uma assinatura do Google Workspace