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. Use a API Google Workspace Events para se inscrever em um recurso do Google Workspace e receber eventos relevantes.
Como o app recebe eventos
Para permitir que o app receba eventos do Google Workspace, use a API Google Workspace Events para criar assinaturas de recursos do Google Workspace.
O exemplo a seguir descreve como a API Google Workspace Events envia eventos para um app do Chat com uma assinatura:
- Um app do Chat se inscreve em um espaço do Google Chat.
- O espaço do Chat muda. Por exemplo, uma nova mensagem é postada no espaço.
- 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, para um evento sobre uma nova mensagem, ele contém detalhes sobre o recurso
Messagecriado. - O app do Chat processa a mensagem do Google Cloud Pub/Sub que contém o evento e, se necessário, toma medidas.
Terminologia importante
Os termos comuns usados na API Google Workspace Events incluem:
- 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 Chat. É possível especificar o nível de detalhe que você quer receber sobre o recurso que mudou. Para mais detalhes, consulte Estrutura dos eventos do Google Workspace.
- Evento de ciclo de vida
- Um evento sobre sua assinatura do Google Workspace. Os eventos de ciclo de vida notificam você 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 de 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
Subscriptionrecurso. Uma assinatura é definida pelas seguintes informações:- Recurso de destino
- O recurso do Google Workspace que você quer monitorar.
Esse recurso é representado no campo
targetResourceda 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 ser notificado para o recurso de destino. Por exemplo, se você se inscreveu em um espaço do Chat, pode escolher se quer receber eventos sobre o espaço e os recursos filhos dele, como assinaturas e mensagens.
- Endpoint de notificação
- O endpoint em que a assinatura do Google Workspace recebe eventos. A API Google Workspace Events oferece suporte a 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 sua assinatura. A tabela a seguir mostra os eventos compatíveis para cada recurso de destino possível.
| Recurso de destino | Eventos compatíveis |
|---|---|
| Espaços do Chat |
|
| Usuários do Chat |
|
| Arquivos do Google Drive ou arquivos de drives compartilhados |
|
| Espaços de reunião e usuários do Google Meet |
|
Para saber mais, consulte os seguintes guias:
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 dos eventos do Google Workspace.
Atributos do CloudEvent
Os eventos do Google Workspace contêm os seguintes atributos obrigatórios do CloudEvents:
| Atributo | Descrição | Exemplo |
|---|---|---|
|
O tipo de dados transmitidos no evento. |
|
|
Um identificador para o CloudEvent. |
|
|
A origem do evento. Para eventos do Google Workspace, esse é o nome completo do recurso da assinatura. |
//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
|
|
A versão de especificação do CloudEvents usada para este evento. |
|
|
O recurso do Google Workspace em que o evento ocorreu. |
|
|
O carimbo de data/hora em que o evento ocorreu, no formato RFC 3339. |
|
|
O tipo de evento do Google Workspace. |
|
Dados do evento
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, é possível especificar quantos dados de recursos são incluídos nos eventos que seu app recebe.
| Dados de recursos | Payload | Expiração da assinatura |
|---|---|---|
| Incluir dados de recursos | Contém alguns ou todos os campos do recurso alterado. | Até 4 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. | Até sete dias |
Essas opções de dados de eventos são representadas no
payloadOptions
campo 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 agir 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"
}
}
Este exemplo contém 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 recursospaces.messageatualizado, 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 em mensagens do Google Cloud Pub/Sub, consulte Vinculação de protocolo do Google Cloud Pub/Sub para CloudEvents.