Esta página apresenta uma visão geral da API Google Workspace Events e explica como você pode 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 quando os recursos são criados, atualizados ou excluídos. Seu app pode ser assinante a um recurso do Google Workspace para receber os eventos relevantes interesse.
Como o app recebe eventos
Para permitir que seu app receba eventos do Google Workspace, use o a API Google Workspace Events para criar assinaturas no Google Workspace; do Google Cloud.
No exemplo abaixo, confira como a API Google Workspace Events oferece eventos em um app do Google Chat com uma assinatura:
- Um app do Chat se inscreve em um espaço do Chat.
- O espaço do Chat muda. Por exemplo, uma nova mensagem é postada no espaço.
- O Chat entrega um evento para um tema em
Google Cloud Pub/Sub,
que serve como o endpoint de notificação para a assinatura. O evento
que contém dados sobre o que mudou. Por exemplo, para um evento sobre um novo
for exibida, o evento vai conter detalhes sobre o recurso
Messageque está criados. - O app do Chat processa a solicitação do Google Cloud Mensagem do Pub/Sub que contém o evento e, se necessário, toma as medidas necessárias.
Terminologia importante
Veja a seguir uma lista de termos comuns usados no API Google Workspace Events:
- Evento do Google Workspace
Uma alteração em um recurso do Google Workspace. Os eventos são formatados usando CloudEvents especificação e pode ser um evento de assinatura ou Um evento do 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 detalhes que você quer receber sobre o recurso que foi alterado. Para mais detalhes, consulte Estrutura dos eventos do Google Workspace.
- Evento de ciclo de vida
- Um evento sobre sua assinatura do Google Workspace. Eventos de ciclo de vida notificar você sobre problemas e o estado de sua assinatura para que possa evitar a perda de eventos de assinatura. Por padrão, sua assinatura sempre recebe eventos de ciclo de vida. Para mais detalhes, consulte Eventos do ciclo de vida para assinaturas do Google Workspace.
- Assinatura do Google Workspace
Entidade nomeada que monitora um recurso de uma conta do Google Workspace. para o aplicativo. 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 e monitorar um recurso. Para saber quais recursos do Google Workspace o para a API Google Workspace Events. Consulte Eventos compatíveis do Google Workspace. - Tipos de evento
- Os tipos de alterações sobre as quais você quer receber notificações o recurso de destino. Por exemplo, se você assinou um espaço do Google Chat, escolha se quer receber eventos sobre o espaço e os recursos filhos, como associações e mensagens.
- Endpoint de notificação
- O endpoint A assinatura do Google Workspace recebe eventos. A 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 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 compatíveis
Os eventos que podem ser recebidos pelo app dependem do recurso de destino sua assinatura. A tabela a seguir exibe os eventos suportados para cada possível recurso de destino.
| Recurso de destino | Eventos compatíveis |
|---|---|
| Espaços do Google Chat |
|
| Usuários do Google Chat |
|
| Espaços para reuniões do Google Meet |
|
| Usuários do Google Meet |
|
Para saber mais, consulte os seguintes guias:
Estrutura de eventos do Google Workspace
Os eventos do Google Workspace seguem os CloudEvents especificação, que é uma maneira padrão do setor de descrever dados de eventos. Google Workspace. contêm o seguinte:
- Atributos do CloudEvent.
- Dados sobre o recurso do Google Workspace que mudou como resultado de o 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 itens obrigatórios Atributos do CloudEvents:
| Atributo | Descrição | Exemplo |
|---|---|---|
|
O tipo de dados que foi transmitido no evento. |
|
|
Um identificador do 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 da 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 de eventos
Os dados de eventos são um payload que representa uma mudança no destino da sua assinatura recurso, incluindo os filhos do recurso de destino. Em seu você pode especificar se 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,
pode receber eventos sobre novas mensagens no espaço. Para eventos sobre
novas mensagens, os dados do evento vão conter um payload com o
spaces.message recurso que foi criado.
Ao criar uma assinatura, é possível especificar a quantidade de dados de recursos incluídos nos eventos que o app recebe:
- Incluir dados de recursos: contém alguns ou todos os campos das alterações recurso. Se você optar por incluir dados de recursos, sua assinatura é limitada a 4 horas, ou 24 horas se você usar a configuração em todo o domínio delegação.
- Excluir dados do recurso: contém apenas o nome do alterado. recurso. A duração da sua assinatura é de até sete dias. Para obter detalhes sobre o evento, é possível consultá-lo usando o nome do recurso.
Essas opções para dados de eventos são representadas em payloadOptions
da sua assinatura.
Eventos como mensagens do Google Cloud Pub/Sub
As assinaturas da API Google Workspace Events usam o Google Cloud Pub/Sub tópicos como o endpoint de notificação que recebe o Google Workspace eventos. 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 o 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 ospaces.message, 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 no Google Cloud Pub/Sub consulte Vinculação de protocolo do Google Cloud Pub/Sub para CloudEvents.