Esta página foi traduzida pela API Cloud Translation.

Inscrever-se em eventos usando a API Google Workspace Events

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 assinado 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.

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

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 Message que 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 Subscription recurso. 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 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	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 Assinaturas Reações Espaço . Veja mais detalhes em Inscrever-se em eventos do Google Chat.	O usuário do Google Chat que autorizar a assinatura precisa participar do espaço usando as credenciais do Google Workspace Conta.
Usuários do Google Chat	`//cloudidentity.googleapis.com/users/USER_ID`	Assinaturas . Veja mais detalhes em Inscrever-se 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 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 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
`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 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 o spaces.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.

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