Esta página foi traduzida pela API Cloud Translation.

Inscrever-se em eventos usando a API Google Workspace Events

Nesta página, você terá uma visão geral da API Eventos do Google Workspace e explicará como usar a API 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 receber 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 de recursos do Google Workspace.

Ilustração de como a API Google Workspace Events envia eventos.

Confira como a API Google Workspace Events envia eventos para seu app por uma assinatura:

Seu app assina um recurso em um aplicativo do Google Workspace, como um espaço do Google Chat.
O recurso em que você se inscreveu muda.
O aplicativo do Google Workspace envia um evento a um tópico no Google Cloud Pub/Sub, que serve como endpoint de notificação para sua assinatura do Google Workspace. O evento contém dados sobre o que foi alterado no recurso.
Seu aplicativo processa a mensagem do Google Cloud 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 na API Events do Google Workspace:

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 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 os detalhes que quer receber sobre o recurso que foi alterado. Para mais detalhes, consulte Estrutura de 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 assinatura para evitar a ausência 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 são compatíveis com a API Google Workspace Events, consulte Eventos do Google Workspace compatíveis.
Tipos de evento: Os tipos de alterações 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 ele e seus recursos filhos, como associações e mensagens.
Endpoint de notificação: O endpoint em que a assinatura do Google Workspace recebe eventos. A API Events do Google Workspace oferece suporte aos 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 compatíveis com o Google Workspace

Os eventos em que seu app pode receber eventos dependem do recurso de destino da assinatura. A tabela a seguir mostra 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	`//chat.googleapis.com/spaces/SPACE_ID`	Mensagens Clubes dos canais Reações Espaço Veja mais detalhes em Inscrever-se em eventos do Google Chat.	O usuário do Google Chat que autoriza a assinatura precisa ser participante do espaço usando uma Conta do Google ou do Google Workspace.
Usuários do Google Chat	`//cloudidentity.googleapis.com/users/USER_ID`	Clubes dos canais Veja mais detalhes em Inscrever-se em eventos do Google Chat.	A assinatura só recebe eventos sobre o usuário que autorizou a assinatura. Um usuário não pode autorizar uma assinatura em nome de outros usuários.
Google Meet
Espaços para reuniões do Google Meet	`//meet.googleapis.com/spaces/SPACE_ID`	Conferências Sessões dos 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 dos participantes Gravações Transcrições Confira mais detalhes em Inscrever-se em eventos do Google Meet.	A assinatura recebe eventos sobre espaços de reunião em que o usuário é um dos seguintes: 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 foram alterados 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 foram transmitidos no evento.	`application/json`
`id`	Um identificador para o 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 alteração no recurso de destino da 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 em 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 você usar a delegação em todo o domínio.
Excluir dados do recurso: contém apenas o nome do recurso alterado. A assinatura tem duração de até sete dias. Para ver detalhes sobre o evento, consulte o recurso usando o nome do recurso.

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 aplicativo 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"
    }
}

Observe os seguintes campos:

attributes: atributos para o 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 mais sobre como os CloudEvents são especificados nas mensagens do Google Cloud Pub/Sub, consulte Vinculação de protocolo do Google Cloud Pub/Sub para CloudEvents.

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