Nesta página, explicamos como usar a API Events do Google Workspace para criar uma assinatura em um recurso do Google Workspace. Uma assinatura do Google Workspace permite que seu app receba informações sobre eventos do Google Workspace, que representam alterações em um recurso do Google Workspace. Para saber com quais recursos e tipos de evento a API Events do Google Workspace oferece suporte, consulte Visão geral da API Google Workspace Events.
Esta página inclui as seguintes etapas para criar uma assinatura do Google Workspace:
- Configurar o ambiente.
- Criar e assinar um tópico do Google Cloud Pub/Sub. Você usa esse tópico como um endpoint para receber eventos do Google Workspace.
- Chame o método
create()
da API Google Workspace Events no recursoSubscription
. - Teste sua assinatura do Google Workspace para garantir que seu tópico do Pub/Sub receba eventos em que você se inscreveu.
- Como opção, configure como enviar eventos para um endpoint do seu app. Assim, ele pode processar o evento e, se necessário, tomar providências.
Pré-requisitos
Apps Script
- Para usar os comandos da CLI do Google Cloud neste guia:
- Instale o Google Cloud CLI.
- Para
inicializar a CLI
gcloud
, execute o seguinte código:
gcloud init
- Um recurso de destino para a assinatura:
- Para se inscrever em um espaço do Google Chat, um espaço do Chat em que o usuário autenticado é participante. O usuário precisa ser participante do espaço por meio do Google Workspace ou da Conta do Google. Não é possível participar de um espaço em um Grupo do Google.
- Para se inscrever em um espaço de reunião do Google Meet, um espaço para reuniões em que o usuário autenticado é o proprietário. Para criar um espaço, consulte Trabalhar com espaços de reunião na documentação do Google Meet.
- Para se inscrever em um usuário do Google Meet, o ID
user
da API Cloud Identity
- Um projeto do Google Cloud com faturamento ativado. Para assinaturas do Chat, você também precisa ativar a API Chat no projeto do Cloud e configurar os campos App name, Avatar URL e Description. Para saber mais, consulte Criar um app do Google Chat.
- Requer autenticação do usuário com a tela de permissão OAuth configurada para o app. Ao configurar a tela de consentimento, você precisa especificar um escopo para oferecer suporte a cada tipo de evento da assinatura. Para configurar a tela de consentimento e identificar os escopos necessários, consulte Escolher escopos.
- Um projeto do Apps Script:
- Use seu projeto do Google Cloud em vez do projeto padrão criado automaticamente pelo Apps Script.
- Para todos os escopos adicionados para configurar a tela de permissão OAuth, é preciso adicioná-los ao arquivo
appsscript.json
no seu projeto do Apps Script. Exemplo:
"oauthScopes": [ "https://www.googleapis.com/auth/chat.messages.readonly" ]
- Ative
o serviço avançado
Google Workspace Events
.
Python
- Python 3.6 ou superior
- A ferramenta de gerenciamento de pacotes pip
- As bibliotecas de cliente mais recentes do Google para Python. Para instalar ou atualizar, execute o seguinte
comando na interface de linha de comando:
pip3 install --upgrade google-api-python-client google-auth-oauthlib
- Para usar os comandos da CLI do Google Cloud neste guia:
- Instale o Google Cloud CLI.
- Para
inicializar a CLI
gcloud
, execute o seguinte código:
gcloud init
- Um recurso de destino para a assinatura:
- Para se inscrever em um espaço do Google Chat, um espaço do Chat em que o usuário autenticado é participante. O usuário precisa ser participante do espaço por meio do Google Workspace ou da Conta do Google. Não é possível participar de um espaço em um Grupo do Google.
- Para se inscrever em um espaço de reunião do Google Meet, um espaço para reuniões em que o usuário autenticado é o proprietário. Para criar um espaço, consulte Trabalhar com espaços de reunião na documentação do Google Meet.
- Para se inscrever em um usuário do Google Meet, o ID
user
da API Cloud Identity
- Um projeto do Google Cloud com faturamento ativado. Para assinaturas do Chat, você também precisa ativar a API Chat no projeto do Cloud e configurar os campos App name, Avatar URL e Description. Para saber mais, consulte Criar um app do Google Chat.
- Requer autenticação do usuário com a tela de permissão OAuth configurada para o app. Ao configurar a tela de consentimento, você precisa especificar um escopo para oferecer suporte a cada tipo de evento da assinatura. Para configurar a tela de consentimento e identificar os escopos necessários, consulte Escolher escopos.
Configurar o ambiente
A seção a seguir explica como configurar seu ambiente antes de criar uma assinatura do Google Workspace.
Ative a API Google Workspace Events e a API Google Cloud Pub/Sub
Antes de usar as APIs do Google, é preciso ativá-las em um projeto do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.Console do Google Cloud
No console do Google Cloud, abra o projeto do Google Cloud do seu app e ative a API Events do Google Workspace e a API Pub/Sub:
gcloud
No diretório de trabalho, faça login na sua Conta do Google:
gcloud auth login
Defina seu projeto como o projeto do Cloud para seu aplicativo:
gcloud config set project PROJECT_ID
Substitua
PROJECT_ID
pelo ID do projeto do Cloud para seu app.Ative a API Events do Google Workspace e a API Google Cloud Pub/Sub:
gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com
Criar credenciais de ID do cliente OAuth
Escolha seu tipo de aplicativo para ver instruções específicas sobre como criar um ID do cliente OAuth:
Aplicativo da Web
- No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
- Clique em Criar credenciais > ID do cliente OAuth.
- Clique em Tipo de aplicativo > Aplicativo da Web.
- No campo Nome, digite um nome para a credencial. Ele só aparece no console do Google Cloud.
- Adicione URIs autorizados relacionados ao seu app:
- Apps do lado do cliente (JavaScript): em Origens JavaScript autorizadas, clique em Adicionar URI. Em seguida, insira um URI a ser usado para solicitações do navegador. Isso identifica os domínios a partir dos quais seu aplicativo pode enviar solicitações de API para o servidor OAuth 2.0.
- Apps do lado do servidor (Java, Python e outros): em URIs de redirecionamento autorizados, clique em Adicionar URI. Em seguida, insira um URI de endpoint para o qual o servidor OAuth 2.0 possa enviar respostas.
- Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
Anote o ID do cliente. As chaves secretas do cliente não são usadas para aplicativos da Web.
- Clique em OK. A credencial recém-criada aparece em IDs do cliente OAuth 2.0.
Android
- No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
- Clique em Criar credenciais > ID do cliente OAuth.
- Clique em Tipo de aplicativo > Android.
- No campo "Nome", digite um nome para a credencial. Ele só aparece no console do Google Cloud.
- No campo "Package name", insira o nome do pacote do arquivo
AndroidManifest.xml
. - No campo "Impressão digital do certificado SHA-1", digite a impressão digital do certificado SHA-1 gerada.
- Clique em Criar. A tela "Cliente OAuth criado" vai aparecer, mostrando seu novo ID do cliente.
- Clique em OK. A credencial recém-criada será exibida em "IDs do cliente OAuth 2.0".
iOS
- No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
- Clique em Criar credenciais > ID do cliente OAuth.
- Clique em Tipo de aplicativo > iOS.
- No campo "Nome", digite um nome para a credencial. Ele só aparece no console do Google Cloud.
- No campo "ID do pacote", insira o identificador do pacote conforme listado no arquivo
Info.plist
do app. - Opcional: se o seu aplicativo aparecer na Apple App Store, digite o ID da App Store.
- Opcional: no campo "ID da equipe", insira a string exclusiva de 10 caracteres gerada pela Apple e atribuída à sua equipe.
- Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
- Clique em OK. A credencial recém-criada será exibida em "IDs do cliente OAuth 2.0".
App do Chrome
- No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
- Clique em Criar credenciais > ID do cliente OAuth.
- Clique em Tipo de aplicativo > Aplicativo do Google Chrome.
- No campo "Nome", digite um nome para a credencial. Ele só aparece no console do Google Cloud.
- No campo "ID do aplicativo", insira a string do ID exclusiva de 32 caracteres do seu app. Você encontra esse valor de ID no URL da Chrome Web Store do seu app e no Painel do desenvolvedor da Chrome Web Store.
- Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
- Clique em OK. A credencial recém-criada será exibida em "IDs do cliente OAuth 2.0".
App para computador
- No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
- Clique em Criar credenciais > ID do cliente OAuth.
- Clique em Tipo de aplicativo > App para computador.
- No campo Nome, digite um nome para a credencial. Ele só aparece no console do Google Cloud.
- Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
- Clique em OK. A credencial recém-criada aparece em IDs do cliente OAuth 2.0.
TVs e dispositivos de entrada limitada
- No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
- Clique em Criar credenciais > ID do cliente OAuth.
- Clique em Tipo de aplicativo > TVs e dispositivos de entrada limitada.
- No campo "Nome", digite um nome para a credencial. Ele só aparece no console do Google Cloud.
- Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
- Clique em OK. A credencial recém-criada será exibida em "IDs do cliente OAuth 2.0".
Plataforma Universal do Windows (UWP)
- No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
- Clique em Criar credenciais > ID do cliente OAuth.
- Clique em Tipo de aplicativo > Universal Windows Platform (UWP).
- No campo "Nome", digite um nome para a credencial. Ele só aparece no console do Google Cloud.
- No campo "ID da loja", insira o valor exclusivo de 12 caracteres do ID da Microsoft Store do seu app. Esse código pode ser encontrado no URL do seu app da Microsoft Store e na Central de parceiros.
- Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
- Clique em OK. A credencial recém-criada será exibida em "IDs do cliente OAuth 2.0".
Fazer o download do arquivo JSON da chave secreta do cliente
O arquivo de chave secreta do cliente é uma representação JSON das credenciais do ID do cliente OAuth que seu app pode referenciar ao fornecer credenciais.
No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.
Em IDs do cliente OAuth 2.0, clique no ID do cliente que você criou.
Clique em Fazer o download do JSON.
Salve o arquivo como
client_secrets.json
.
Criar e assinar um tópico do Pub/Sub
Nesta seção, você criará um tópico do Pub/Sub e uma assinatura para o tópico. O tópico do Pub/Sub serve como endpoint de notificação em que a assinatura do Google Workspace recebe eventos.
Para saber mais sobre como criar e gerenciar tópicos do Pub/Sub, consulte a documentação do Pub/Sub .
Para criar e assinar um tópico do Pub/Sub:
Console do Google Cloud
No console do Google Cloud, acesse a página do Pub/Sub:
Acessar o Google Cloud Pub/Sub
Verifique se o projeto do Cloud para seu app está selecionado.
Clique em
Criar tópico e faça o seguinte:- Digite um nome para o tópico, como
workspace-events-topic
. - Deixe a opção Adicionar uma assinatura padrão selecionada. O Pub/Sub nomeia essa
assinatura padrão de maneira semelhante ao nome do tópico, por exemplo,
workspace-events-topic-sub
. - Opcional: atualize ou configure outras propriedades para o tópico.
- Digite um nome para o tópico, como
Clique em Criar. O nome completo do tópico está formatado como
projects/PROJECT_ID/topics/TOPIC_ID
. Esse nome completo será usado em uma etapa posterior.Conceda acesso para publicar mensagens do Pub/Sub no seu tópico:
- Na página do tópico, acesse o painel lateral e abra a guia Permissões.
- Clique em Adicionar principal.
- No campo Adicionar principais, adicione a conta de serviço do
aplicativo do Google Workspace que envia eventos à sua
assinatura:
- Para eventos do Chat,
chat-api-push@system.gserviceaccount.com
. - Para eventos do Meet,
meet-api-event-push@system.gserviceaccount.com
.
- Para eventos do Chat,
- No menu Atribuir funções, selecione
Pub/Sub Publisher
. - Clique em Salvar. A atualização das permissões do tópico pode levar alguns minutos.
gcloud
No projeto do Cloud, crie um tópico executando o seguinte comando:
gcloud pubsub topics create TOPIC_ID
Substitua
TOPIC_ID
por um ID exclusivo para seu tópico, comoworkspace-events-topic
.A saída exibe o nome completo do tópico, formatado como
projects/PROJECT_ID/topics/TOPIC_ID
. Anote o nome e verifique se o valor de PROJECT_ID é o ID do projeto do Cloud do seu app. Você usará o nome do tópico na etapa a seguir e para criar a assinatura do Google Workspace posteriormente.Conceda acesso para publicar mensagens no seu tópico:
gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'
Substitua:
TOPIC_NAME
: o nome completo do tópico, que é a saída da etapa anterior. Formatado comoprojects/PROJECT_ID/topics/TOPIC_ID
.GOOGLE_WORKSPACE_APPLICATION
: o aplicativo do Google Workspace que precisa enviar eventos para sua assinatura:- Para receber eventos do Chat, use
chat-api-push@system.gserviceaccount.com
. - Para receber eventos do Meet, use
meet-api-event-push@system.gserviceaccount.com
.
- Para receber eventos do Chat, use
A atualização das permissões do seu tópico pode levar alguns minutos.
Crie uma assinatura do Pub/Sub para o tópico:
gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME
Substitua:
SUBSCRIPTION_NAME
: um nome para a assinatura, comoworkspace-events-subscription
.TOPIC_NAME
: o nome do tópico que você criou na etapa anterior.
Criar uma assinatura do Google Workspace
Nesta seção, você usa o método subscriptions.create()
da API Events
do Google Workspace para criar um
recurso
Subscription
. Especifique os seguintes campos:
targetResource
: um recurso do Google Workspace para monitorar eventos, como um espaço do Chat.eventTypes
: uma matriz de um ou mais tipos de evento que você quer receber sobre o recurso. Por exemplo, se o app só precisa saber sobre novas mensagens postadas em um espaço do Chat, ele pode apenas se inscrever em eventos sobre as mensagens criadas.notificationEndpoint
: um endpoint de notificação em que a assinatura do Google Workspace envia eventos. Use o tópico do Pub/Sub criado na seção anterior.payloadOptions
: opções para especificar quantos dados de recursos serão incluídos no payload do evento. Essa configuração afeta o prazo de validade da assinatura. Para saber mais, consulte Dados de eventos.
Para criar uma assinatura do Google Workspace, siga estas etapas:
Apps Script
No projeto do Apps Script, crie um novo arquivo de script chamado
createSubscription
e adicione o seguinte código:function createSubscription() { // The Google Workspace resource to monitor for events. const targetResource = 'TARGET_RESOURCE'; // The types of events to receive. const eventTypes = [EVENT_TYPES]; // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic. const pubsubTopic = 'TOPIC_NAME'; // Whether to include resource data or not. const resourceData = RESOURCE_DATA; // Call the Workspace Events API using the advanced service. const response = WorkspaceEvents.Subscriptions.create({ targetResource: targetResource, eventTypes: eventTypes, notificationEndpoint: { pubsubTopic: pubsubTopic, }, payloadOptions: { includeResource: resourceData } }); console.log(response); }
Substitua:
TARGET_RESOURCE
: o recurso do Google Workspace que você está assinando, formatado como o nome completo do recurso. Por exemplo, para se inscrever em um espaço do Google Chat com o IDAAAABBBB
, use//chat.googleapis.com/spaces/AAAABBBB
.EVENT_TYPES
: um ou mais tipos de eventos em que você quer se inscrever no recurso de destino. Formate como uma matriz de strings, como'google.workspace.chat.message.v1.created'
.TOPIC_NAME
: o nome completo do tópico do Pub/Sub que você criou no projeto do Cloud. Formatado comoprojects/PROJECT_ID/topics/TOPIC_ID
.RESOURCE_DATA
: um booleano que especifica se a assinatura inclui dados de recursos no payload:True
: inclui todos os dados de recursos. Para limitar quais campos são incluídos, adicione o campofieldMask
e especifique pelo menos um campo para o recurso alterado. Apenas as assinaturas de recursos do Chat oferecem suporte à inclusão de dados de recursos.False
: exclui dados de recursos.
Para criar a assinatura do Google Workspace, execute a função
createSubscription
no seu projeto do Apps Script.
Python
No diretório de trabalho, crie um arquivo chamado
create_subscription.py
e adicione o seguinte código:"""Create subscription.""" from google_auth_oauthlib.flow import InstalledAppFlow from googleapiclient.discovery import build # Specify required scopes. SCOPES = [SCOPES] # Authenticate with Google Workspace and get user authentication. flow = InstalledAppFlow.from_client_secrets_file('client_secrets.json', SCOPES) CREDENTIALS = flow.run_local_server() # The Google Workspace resource to monitor for events. TARGET_RESOURCE = 'TARGET_RESOURCE' # The types of events to receive. EVENT_TYPES = [EVENT_TYPES] # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic. TOPIC = 'TOPIC_NAME' # Call the Workspace Events API using the service endpoint. service = build( 'workspaceevents', 'v1', credentials=CREDENTIALS, ) BODY = { 'target_resource': TARGET_RESOURCE, 'event_types': EVENT_TYPES, 'notification_endpoint': {'pubsub_topic': TOPIC}, 'payload_options': {'include_resource': RESOURCE_DATA}, } response = service.subscriptions().create(body=BODY).execute() print(response)
Substitua:
SCOPES
: um ou mais escopos do OAuth compatíveis com cada tipo de evento para a assinatura. Formatado como uma matriz de strings. Para listar vários escopos, separe-os por vírgulas. Por exemplo,'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'
.TARGET_RESOURCE
: o recurso do Google Workspace que você está assinando, formatado como o nome completo do recurso. Por exemplo, para se inscrever em um espaço do Google Chat com o IDAAAABBBB
, use//chat.googleapis.com/spaces/AAAABBBB
.EVENT_TYPES
: um ou mais tipos de eventos em que você quer se inscrever no recurso de destino. Formate como uma matriz de strings, como'google.workspace.chat.message.v1.created'
.TOPIC_NAME
: o nome completo do tópico do Pub/Sub que você criou no projeto do Cloud. Formatado comoprojects/PROJECT_ID/topics/TOPIC_ID
.RESOURCE_DATA
: um booleano que especifica se a assinatura inclui dados de recursos no payload:True
: inclui todos os dados de recursos. Para limitar quais campos são incluídos, adicione o campofieldMask
e especifique pelo menos um campo para o recurso alterado. Apenas as assinaturas de recursos do Chat oferecem suporte à inclusão de dados de recursos.False
: exclui dados de recursos.
Para criar a assinatura do Google Workspace, execute o seguinte no seu terminal:
python3 create_subscription.py
A API Events do Google Workspace retorna uma operação
de longa duração concluída que contém a
instância do recurso Subscription
que você criou.
Testar sua assinatura do Google Workspace
Para testar se você está recebendo eventos do Google Workspace, acione um evento e envie mensagens para a assinatura do Pub/Sub.
Para testar sua assinatura do Google Workspace, faça o seguinte:
Console do Google Cloud
Acione um ou mais tipos de eventos no recurso de destino da sua assinatura do Google Workspace. Por exemplo, se você se inscreveu para novas mensagens em um espaço do Chat, poste uma mensagem no espaço.
No console do Google Cloud, acesse a página do Pub/Sub:
Verifique se o projeto do Cloud para seu app está selecionado.
No menu Pub/Sub, clique em Assinaturas.
Na tabela, encontre a assinatura do Pub/Sub do seu tópico e clique no nome da assinatura.
Clique na guia Mensagens.
Clique em Pull. Pode levar até alguns minutos para um evento gerar uma mensagem do Pub/Sub.
gcloud
Acione um ou mais tipos de eventos no recurso de destino da sua assinatura do Google Workspace. Por exemplo, se você se inscreveu para novas mensagens em um espaço do Chat, poste uma mensagem no espaço.
Execute este comando:
gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack
Substitua:
PUBSUB_SUBSCRIPTION_NAME
: o nome completo da sua assinatura do Pub/Sub, formatado comoprojects/SUBSCRIPTION_ID/subscriptions/SUBSCRIPTION_ID
.MESSAGE_COUNT
: o número máximo de mensagens do Pub/Sub que você quer receber.
Pode levar até alguns minutos para um evento gerar uma mensagem do Pub/Sub.
Para cada evento do Google Workspace acionado, uma mensagem é entregue à sua assinatura do Pub/Sub que contém o evento. Para mais detalhes, consulte Como receber eventos como mensagens do Google Cloud Pub/Sub.
Configure a forma como o app recebe eventos
A assinatura do Pub/Sub que você criou é baseada em pull. Depois de testar se sua assinatura do Pub/Sub, você pode atualizar o tipo de entrega para mudar a forma como seu app recebe eventos. Por exemplo, é possível configurar a assinatura do Pub/Sub para um tipo de entrega por push, de modo que o app possa receber eventos diretamente em um endpoint de app.
Para saber mais sobre como configurar uma assinatura do Pub/Sub, consulte a documentação do Pub/Sub.