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 usar a API 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. O app pode se inscrever em um recurso do Google Workspace para receber eventos relevantes do seu interesse.

Como o 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 abaixo, confira como a API Google Workspace Events envia eventos para um app do Google Chat com uma assinatura:

1. Um app do Chat se inscreve em 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 para um tópico no Cloud Pub/Sub do Google, que serve como o endpoint de notificação da assinatura. O evento contém dados sobre o que mudou. Por exemplo, para um evento sobre uma nova mensagem, o evento contém detalhes sobre o recurso Message que é criado.
4. O app de 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 do 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. É possível especificar quanto detalhe você quer receber sobre o recurso alterado. Confira mais detalhes em Estrutura dos eventos do Google Workspace.

Evento do ciclo de vida

Um evento relacionado à sua assinatura do Google Workspace. Os eventos de ciclo de vida notificam você sobre problemas e o estado da sua assinatura para que você evite perder eventos de assinatura. Por padrão, a assinatura sempre recebe eventos do ciclo de vida. Confira mais detalhes em 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 do Google Workspace compatíveis.

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, como inscrições e mensagens.

Endpoint de notificação

O endpoint em que a assinatura do Google Workspace recebe eventos. A API Google Workspace Events oferece suporte aos tópicos do Cloud Pub/Sub do Google Cloud como um endpoint de notificação. Para saber mais sobre o uso do 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 os recursos alterados.

Eventos do Google Workspace com suporte

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

Para saber mais, consulte estes guias:

• Inscrever-se em eventos do Google Chat
• Assinar eventos do Google Meet

Estrutura dos eventos do Google Workspace

Os eventos do Google Workspace seguem a especificação do 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 para eventos do Google Workspace.

Atributos do CloudEvent

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

Dados de eventos

Os dados do evento são um payload que representa uma mudança no recurso de destino da sua assinatura, incluindo recursos filhos do recurso de destino. 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 são incluídos nos eventos que o app recebe:

• Incluir dados de recursos:contém alguns ou todos os campos do recurso alterado. Se você optar por incluir dados de recursos, a duração da assinatura será limitada a até quatro horas ou 24 horas se você 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 saber mais sobre o evento, consulte o recurso usando o nome dele.

Essas opções para 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 Pub/Sub do Google Cloud 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, que incluem 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, formatado 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 nas mensagens do Google Cloud Pub/Sub, consulte Vinculações de protocolo do Google Cloud Pub/Sub para CloudEvents.

Temas relacionados

• Inscrever-se em eventos do Google Chat
• Assinar eventos do Google Meet
• Eventos de ciclo de vida para assinaturas do Google Workspace
• Escolher escopos da API Google Workspace Events
• Criar uma assinatura do Google Workspace