Esta página foi traduzida pela API Cloud Translation.

Inscrever-se em eventos usando a API Google Workspace Events

Nesta página, você encontra 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 alterações nos recursos do Google Workspace, como quando os recursos são criados, atualizados ou excluídos. Seu app pode se inscrever em um recurso do Google Workspace para que você receba eventos relevantes em que você tem 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 nos recursos do Google Workspace.

Ilustração de como a API Google Workspace Events transmite eventos. — **Figura 1.** Exemplo de como a API Google Workspace Events envia eventos para um app do Chat.

No exemplo a seguir, veja como a API Google Workspace Events envia eventos para um app do Google Chat usando 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 tópico no Google Cloud Pub/Sub, que atua como endpoint de notificação para a assinatura. O evento contém dados sobre o que foi alterado. Por exemplo, no caso de um evento sobre uma nova mensagem, ele contém detalhes sobre o recurso Message que foi criado.
O app do Chat processa a mensagem do Google Cloud Pub/Sub que contém o evento e, se necessário, toma as medidas necessárias.

Terminologia importante

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

Evento do Google Workspace

Uma alteração 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 alteração no recurso do Google Workspace que você está monitorando, como uma nova mensagem em um espaço do Google Chat. Você pode especificar quantos detalhes 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. Os eventos de ciclo de vida informam você sobre problemas e o estado da assinatura para que você 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 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 a API Google Workspace Events oferece suporte, consulte Eventos do Google Workspace compatíveis.
Tipos de evento: Os tipos de alterações sobre as quais você quer receber notificações no recurso de destino. Por exemplo, se você se inscreveu em um espaço do Google Chat, poderá escolher se quer receber eventos sobre ele 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 os recursos alterados.

Eventos do Google Workspace compatíveis

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

Recurso de destino	Formato	Eventos compatíveis	Limitações (se aplicável)
Google Chat
Espaços do Google Chat	Para se inscrever em um espaço específico, faça o seguinte: `//chat.googleapis.com/spaces/SPACE_ID` Para se inscrever em todos os espaços de que o usuário participa, siga estas etapas: `//chat.googleapis.com/spaces/-`	Mensagens Clubes dos canais Reações Espaço Confira mais detalhes em Fazer inscrição em eventos do Google Chat.	O usuário do Google Chat que autoriza a assinatura precisa ser membro do espaço usando a própria Conta do Google ou do Google Workspace.
Usuários do Google Chat	`//cloudidentity.googleapis.com/users/USER_ID`	Clubes dos canais Confira mais detalhes em Fazer inscrição em eventos do Google Chat.	A assinatura só recebe eventos sobre o usuário que a autorizou. Um usuário não pode autorizar uma assinatura em nome de outras pessoas.
Google Meet
Espaços para reuniões do Google Meet	`//meet.googleapis.com/spaces/SPACE_ID`	Conferências Sessões com participantes Gravações Transcrições Confira mais detalhes em Inscrever-se em eventos do Google Meet.
Usuários do Google Meet	`//cloudidentity.googleapis.com/users/USER_ID`	Conferências Sessões com participantes Gravações Transcrições Confira mais detalhes em Inscrever-se em eventos do Google Meet.	A assinatura recebe eventos sobre espaços para reuniões em que o usuário é uma das seguintes opções: O proprietário do espaço para reuniões. O organizador do evento do Google Agenda associado ao espaço da reunião.

Estrutura de 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 foi alterado como resultado do evento.

Na seção a seguir, explicamos a estrutura dos atributos e dados dos eventos do Google Workspace.

Atributos do CloudEvent

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

Atributo	Descrição	Exemplo
`datacontenttype`	O tipo de dados que foi transmitido no evento.	`application/json`
`id`	Um identificador do CloudEvent.	`spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO`
`source`	A origem do evento. Para eventos do Google Workspace, esse é o nome completo do recurso da assinatura.	`//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg`
`specversion`	A versão da especificação do CloudEvents usada para este evento.	`1.0`
`subject`	O recurso do Google Workspace em que o evento ocorreu.	`//chat.googleapis.com/spaces/AAAABBBBBBB`
`time`	É o carimbo de data/hora em que o evento ocorreu, no formato RFC 3339.	`2023-09-07T21:37:36.260127Z`
`type`	O tipo de evento do Google Workspace.	`google.workspace.chat.message.v1.created`

Dados de eventos

Os dados de eventos 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, 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, 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 serã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 quatro horas ou 24 horas se você usar a delegação em todo o domínio.
Excluir dados do recurso: contém apenas o nome do recurso alterado. A duração da sua assinatura é de até sete dias. Para detalhes sobre o evento, consulte o recurso usando o nome do recurso.

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 os 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, que incluem o tipo de evento. Nesse caso, o evento é sobre uma mensagem atualizada no espaço.
data: os dados de eventos 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 como o CloudEvents é especificado nas mensagens do Google Cloud Pub/Sub, consulte Vinculação do protocolo do Google Cloud Pub/Sub para CloudEvents.

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