Criar uma assinatura do Google Workspace

Nesta página, explicamos como usar a API Google Workspace Events para criar uma assinatura de um recurso do Google Workspace. Uma assinatura do Google Workspace permite que seu app receba informações sobre eventos do Google Workspace, que representam mudanças em um recurso do Google Workspace. Para saber quais recursos e tipos de evento são compatíveis com a API Google Workspace Events, consulte a visão geral da API Google Workspace Events.

Esta página inclui as seguintes etapas para criar uma assinatura do Google Workspace:

1. Prepare o ambiente.
2. Criar e se inscrever em um tópico do Google Cloud Pub/Sub. Use este documento como um endpoint para receber eventos do Google Workspace.
3. Chame o método create da API Google Workspace Events no recurso Subscription.
4. Teste sua assinatura do Google Workspace para verificar se o tópico do Pub/Sub recebe os eventos que você assinou.
5. Se quiser, configure como enviar eventos para um endpoint do seu app, para que ele possa processar o evento e, se necessário, entre em ação.

Pré-requisitos

Apps Script

• Para usar os comandos da CLI do Google Cloud neste guia:
  1. Instale a CLI do Google Cloud.
  2. Para inicializar a CLI gcloud, execute o seguinte código:

    gcloud init
    

• Um projeto do Apps Script:
  • Use seu projeto na nuvem do Google Cloud em vez do padrão criado automaticamente pelo Apps Script.
  • Para todos os escopos adicionados para configurar a tela de permissão OAuth, você também precisa adicionar os escopos ao arquivo appsscript.json no seu projeto do Apps Script. Por exemplo, se você especificou o escopo chat.messages, adicione o seguinte:

  "oauthScopes": [
    "https://www.googleapis.com/auth/chat.messages"
  ]
      

  • Ative o serviço avançado Google Workspace Events.

• Um projeto na nuvem do Google Cloud com o faturamento ativado. Para assinaturas do Chat, você também precisa ativar a API Chat no seu projeto na nuvem e configurar os campos Nome do app, URL do avatar e Descrição. Para mais detalhes, consulte Criar um app do Google Chat.
• Requer autenticação e um escopo de autorização apropriado para cada tipo de evento na assinatura:
  • Normalmente, exige a autenticação do usuário com a tela de permissão OAuth configurada para o app. Ao configurar a tela de permissão, é necessário especificar um escopo para aceitar cada tipo de evento da assinatura. Para configurar a tela de permissão e identificar os escopos necessários, consulte Escolher escopos.
  • Para se inscrever em um evento do Chat como um app do Chat, é necessário fazer a autenticação do app com aprovação única do administrador.

Python

• Python 3.6 ou mais recente
• A ferramenta de gerenciamento de pacotes pip
• As bibliotecas de cliente do Google mais recentes 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:
  1. Instale a CLI do Google Cloud.
  2. Para inicializar a CLI gcloud, execute o seguinte código:

    gcloud init
    

• Um projeto na nuvem do Google Cloud com o faturamento ativado. Para assinaturas do Chat, você também precisa ativar a API Chat no seu projeto na nuvem e configurar os campos Nome do app, URL do avatar e Descrição. Para mais detalhes, consulte Criar um app do Google Chat.
• Requer autenticação e um escopo de autorização apropriado para cada tipo de evento na assinatura:
  • Normalmente, exige a autenticação do usuário com a tela de permissão OAuth configurada para o app. Ao configurar a tela de permissão, é necessário especificar um escopo para aceitar cada tipo de evento da assinatura. Para configurar a tela de permissão e identificar os escopos necessários, consulte Escolher escopos.
  • Para se inscrever em um evento do Chat como um app do Chat, é necessário fazer a autenticação do app com aprovação única do administrador.

Configurar o ambiente

A seção a seguir explica como configurar seu ambiente antes de criar uma assinatura do Google Workspace.

Ativar 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 na nuvem do Google Cloud para seu app e ative as APIs Google Workspace Events e Pub/Sub:

Ativar as APIs

gcloud

1. No diretório de trabalho, faça login na sua Conta do Google:

   gcloud auth login

2. Defina seu projeto como o projeto na nuvem para seu app:

   gcloud config set project PROJECT_ID

   Substitua PROJECT_ID pelo ID do projeto do projeto na nuvem para seu app.

3. Ative a API Google Workspace Events e a API Google Cloud Pub/Sub:

   gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com

Criar credenciais de ID do cliente OAuth

Observação: pule esta etapa se estiver usando o Apps Script.

Escolha o tipo de aplicativo para receber instruções específicas sobre como criar um ID do cliente OAuth:

Observação: para executar o exemplo de código neste guia, escolha App para computador e siga as instruções.

Aplicativo da Web

1. No console do Google Cloud, acesse Menu > Plataforma do Google Auth > Clientes.

   Acessar Clientes

2. Clique em Criar cliente.
3. Clique em Tipo de aplicativo > Aplicativo da Web.
4. No campo Nome, digite um nome para a credencial. Esse nome é mostrado apenas no console do Google Cloud.
5. 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 para usar nas solicitações do navegador. Identifica os domínios de onde o aplicativo pode enviar solicitações de API ao 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.
6. Opcional: se o app for um agente de IA que realiza ações em nome dos usuários, selecione Usar este cliente para um agente com tecnologia de IA. Se o app for compatível com fluxos de trabalho de agentes de IA e recursos de usuário padrão, crie clientes OAuth separados para cada um. Não é possível mudar essa configuração depois de criar o cliente.
7. Clique em Criar.

   A credencial recém-criada aparece em IDs do cliente OAuth 2.0.

   As chaves secretas do cliente não são usadas em aplicativos da Web.

Android

1. No console do Google Cloud, acesse Menu > Plataforma do Google Auth > Clientes.

   Acessar Clientes

2. Clique em Criar cliente.
3. Clique em Tipo de aplicativo > Android.
4. No campo Nome, digite um nome para a credencial. Esse nome é mostrado apenas no console do Google Cloud.
5. No campo Nome do pacote, insira o nome do pacote do arquivo AndroidManifest.xml.
6. No campo Impressão digital do certificado SHA-1, insira a impressão digital do certificado SHA-1 gerada.
7. Opcional: se o app for um agente de IA que realiza ações em nome dos usuários, selecione Usar este cliente para um agente com tecnologia de IA. Se o app for compatível com fluxos de trabalho de agentes de IA e recursos de usuário padrão, crie clientes OAuth separados para cada um. Não é possível mudar essa configuração depois de criar o cliente.
8. Clique em Criar.

   A credencial recém-criada aparece em "IDs do cliente OAuth 2.0".

iOS

1. No console do Google Cloud, acesse Menu > Plataforma do Google Auth > Clientes.

   Acesse Clientes

2. Clique em Criar cliente.
3. Clique em Tipo de aplicativo > iOS.
4. No campo Nome, digite um nome para a credencial. Esse nome é mostrado apenas no console do Google Cloud.
5. No campo ID do pacote, insira o identificador do pacote conforme listado no arquivo Info.plist do app.
6. Opcional: se o app estiver na App Store da Apple, insira o ID da App Store.
7. Opcional: no campo ID da equipe, insira a string exclusiva de 10 caracteres gerada pela Apple e atribuída à sua equipe.
8. Opcional: se o app for um agente de IA que realiza ações em nome dos usuários, selecione Usar este cliente para um agente com tecnologia de IA. Se o app for compatível com fluxos de trabalho de agentes de IA e recursos de usuário padrão, crie clientes OAuth separados para cada um. Não é possível mudar essa configuração depois de criar o cliente.
9. Clique em Criar.

   A credencial recém-criada aparece em "IDs do cliente OAuth 2.0".

App do Chrome

1. No console do Google Cloud, acesse Menu > Plataforma do Google Auth > Clientes.

   Acessar Clientes

2. Clique em Criar cliente.
3. Clique em Tipo de aplicativo > Extensão do Chrome.
4. No campo Nome, digite um nome para a credencial. Esse nome é mostrado apenas no console do Google Cloud.
5. No campo ID do item, insira a string de 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 de controle do desenvolvedor da Chrome Web Store.
6. Opcional: se o app for um agente de IA que realiza ações em nome dos usuários, selecione Usar este cliente para um agente com tecnologia de IA. Se o app for compatível com fluxos de trabalho de agentes de IA e recursos de usuário padrão, crie clientes OAuth separados para cada um. Não é possível mudar essa configuração depois de criar o cliente.
7. Clique em Criar.

   A credencial recém-criada aparece em "IDs do cliente OAuth 2.0".

App para computador

1. No console do Google Cloud, acesse Menu > Plataforma do Google Auth > Clientes.

   Acessar Clientes

2. Clique em Criar cliente.
3. Clique em Tipo de aplicativo > App para computador.
4. No campo Nome, digite um nome para a credencial. Esse nome é mostrado apenas no console do Google Cloud.
5. Opcional: se o app for um agente de IA que realiza ações em nome dos usuários, selecione Usar este cliente para um agente com tecnologia de IA. Se o app for compatível com fluxos de trabalho de agentes de IA e recursos de usuário padrão, crie clientes OAuth separados para cada um. Não é possível mudar essa configuração depois de criar o cliente.
6. Clique em Criar.

   A credencial recém-criada aparece em "IDs do cliente OAuth 2.0".

TVs e dispositivos de entrada limitados

1. No console do Google Cloud, acesse Menu > Plataforma do Google Auth > Clientes.

   Acessar Clientes

2. Clique em Criar cliente.
3. Clique em Tipo de aplicativo > TVs e dispositivos de entrada limitada.
4. No campo Nome, digite um nome para a credencial. Esse nome é mostrado apenas no console do Google Cloud.
5. Opcional: se o app for um agente de IA que realiza ações em nome dos usuários, selecione Usar este cliente para um agente com tecnologia de IA. Se o app for compatível com fluxos de trabalho de agentes de IA e recursos de usuário padrão, crie clientes OAuth separados para cada um. Não é possível mudar essa configuração depois de criar o cliente.
6. Clique em Criar.

   A credencial recém-criada aparece em "IDs do cliente OAuth 2.0".

Plataforma Universal do Windows (UWP)

1. No Console de APIs do Google, acesse Menu > > Clientes.

   Acessar Clientes

2. Clique em Criar cliente.
3. Clique em Tipo de aplicativo > Plataforma Universal do Windows (UWP).
4. No campo "Nome", digite um nome para a credencial. Esse nome é mostrado apenas no Console de APIs do Google.
5. No campo "ID da loja", insira o ID exclusivo de 12 caracteres da Microsoft Store do seu app. Você encontra esse ID no URL da Microsoft Store do seu app e no Partner Center.
6. Opcional: se o app for um agente de IA que realiza ações em nome dos usuários, selecione Usar este cliente para um agente com tecnologia de IA. Se o app for compatível com fluxos de trabalho de agentes de IA e recursos de usuário padrão, crie clientes OAuth separados para cada um. Não é possível mudar essa configuração depois de criar o cliente.
7. Clique em Criar.

   A credencial recém-criada aparece em "IDs do cliente OAuth 2.0".

Fazer o download do arquivo JSON da chave secreta do cliente

Observação: pule esta etapa se estiver usando o Apps Script.

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.

1. No Console de APIs do Google, acesse Menu > APIs e serviços > Credenciais.

   Ir para Credenciais

2. Em IDs do cliente OAuth 2.0, clique no ID do cliente que você criou.

3. Clique em Fazer o download do JSON.

4. Salve o arquivo como credentials.json.

Criar e assinar um tópico do Pub/Sub

Nesta seção, você vai criar um tópico do Pub/Sub e uma assinatura para ele. O tópico do Pub/Sub serve como o endpoint de notificação em que sua 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.

Observação: a API Google Workspace Events usa chaves de ordenação para que seu app receba mensagens na ordem em que são publicadas. Recomendamos evitar o uso da política de armazenamento de mensagens. Os eventos publicados em tópicos com essas políticas provavelmente vão falhar, porque as regiões na política podem não corresponder à origem do evento.

Para criar e se inscrever em um tópico do Pub/Sub:

Console de APIs do Google

1. No Console de APIs do Google, acesse a página do Pub/Sub:

   Acessar o Google Cloud Pub/Sub

   Verifique se o projeto na nuvem do seu app está selecionado.

2. Clique em Criar tópico e faça o seguinte:

   1. Insira um nome para o tópico, como workspace-events-topic.
   2. 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, como workspace-events-topic-sub.
   3. Opcional: atualize ou configure outras propriedades para o tópico.

3. Clique em Criar. O nome completo do tópico é formatado como projects/PROJECT_ID/topics/TOPIC_ID. Use esse nome completo em uma etapa posterior.

4. Conceda acesso para publicar mensagens do Pub/Sub no seu tópico:

   1. Na página do tópico, acesse o painel lateral e abra a guia Permissões.
   2. Clique em Adicionar principal.
   3. No campo Adicionar participantes, adicione a conta de serviço do aplicativo do Google Workspace que envia eventos para sua assinatura:
      1. Para eventos do Chat, [e-mail].
      2. Para eventos do Drive, [e-mail].
      3. Para eventos do Meet, [e-mail].
   4. No menu Atribuir papéis, selecione Pub/Sub Publisher.
   5. Clique em Salvar. Pode levar alguns minutos para atualizar as permissões do seu tópico.

gcloud

1. No seu projeto na nuvem, crie um tópico executando o seguinte comando:

   gcloud pubsub topics create TOPIC_ID

   Substitua TOPIC_ID por um ID exclusivo para o tópico, como workspace-events-topic.

   A saída mostra 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. Use o nome do tópico na etapa a seguir e para criar a assinatura do Google Workspace mais tarde.

2. Conceda acesso para publicar mensagens no 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 como projects/PROJECT_ID/topics/TOPIC_ID.

   • GOOGLE_WORKSPACE_APPLICATION: o aplicativo do Google Workspace que precisa entregar eventos para sua assinatura:

     • Para receber eventos do Chat, use uma das seguintes contas de serviço:
       • Para apps do Chat (criados como complementos do Google Workspace que estendem o Chat), use o e-mail da conta de serviço na página de configuração da API Chat. Para saber mais, consulte Criar um app do Google Chat que usa o Pub/Sub.
       • Para apps do Chat que não são complementos, use [e-mail]. Para saber mais, consulte Criar um app do Google Chat que usa o Pub/Sub.
     • Para receber eventos do Drive, use [e-mail].
     • Para receber eventos do Meet, use [e-mail].

   Pode levar alguns minutos para atualizar as permissões do seu tópico.

3. 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 sua assinatura, como workspace-events-subscription.
   • TOPIC_NAME: o nome do tópico que você criou na etapa anterior.

Observação:se você usa o VPC Service Controls, talvez seja necessário configurar uma regra de entrada no perímetro de serviço para permitir que a conta de serviço acesse o Pub/Sub. Para saber mais, consulte Regras de entrada e saída.

Assinar um recurso do Google Workspace

Nesta seção, você vai se inscrever no recurso do Google Workspace que quer monitorar para eventos.

Escolher e identificar o recurso de destino

Em uma assinatura do Google Workspace, o recurso de destino é o recurso do Google Workspace que você monitora para eventos. O recurso de destino é representado no campo targetResource da assinatura, formatado usando o nome completo do recurso. Por exemplo, para uma assinatura que monitora um espaço do Chat (spaces/AAAABBBBBBB), o valor de targetResource é //chat.googleapis.com/spaces/AAAABBBBBBB.

Observação: o tempo máximo de validade das assinaturas depende da inclusão de dados de recursos no payload do evento. Para saber mais sobre os prazos de validade, consulte Dados de eventos do Google Workspace.

Identificar um recurso de destino para o Chat

Recurso de destino	Formato	Limitações
Espaço	//chat.googleapis.com/spaces/SPACE em que SPACE é o ID no nome do recurso da API Chat space. Você pode conseguir o ID no URL do espaço ou usando o método spaces.list().	O usuário ou app do Chat que autoriza a assinatura precisa ser membro do espaço pela Conta do Google Workspace ou Conta do Google. Compatível com: Autenticação de usuários Autenticação de apps com aprovação do administrador
Todos os espaços de um usuário	//chat.googleapis.com/spaces/-	A assinatura só recebe eventos dos espaços em que o usuário é membro pela Conta do Google ou do Google Workspace. Oferece suporte apenas à autenticação do usuário.
Usuário	//cloudidentity.googleapis.com/users/USER em que USER é o ID no nome do recurso do recurso user da API Chat. Para mais detalhes, consulte Identificar e especificar usuários 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. Oferece suporte apenas à autenticação do usuário.
Cliente ( prévia para desenvolvedores)	//admin.googleapis.com/customers/CUSTOMER em que CUSTOMER é o ID de cliente. Também é possível usar o alias my_customer para o domínio personalizado do cliente do app do Chat.	A assinatura recebe eventos de todos os espaços e usuários gerenciados pelo domínio do cliente. Só aceita a autenticação de apps com aprovação do administrador.

Identificar um recurso de destino para o Drive

Prévia para desenvolvedores:disponível como parte do Programa de Prévia para Desenvolvedores do Google Workspace, que concede acesso antecipado a determinados recursos.

Recurso de destino	Formato	Limitações (se aplicável)
Arquivo	//drive.googleapis.com/files/FILE em que FILE é o ID no nome do recurso da API Drive files. É possível conseguir o ID no URL do arquivo ou usando o método files.list.	O usuário que autoriza a assinatura precisa ter permissão no arquivo dentro da assinatura em relação ao evento de assinatura.
Drive compartilhado	//drive.googleapis.com/drives/DRIVE em que DRIVE é o ID no nome do recurso da API Drive drives. Você pode conseguir o ID no URL do drive ou usando o método drives.list.	A assinatura só recebe eventos de itens no drive compartilhado em que o usuário é membro com a Conta do Google Workspace ou Conta do Google.

Identificar um recurso de destino para o Meet

Recurso de destino	Formato	Limitações (se aplicável)
Espaço para reuniões	//meet.googleapis.com/spaces/SPACE em que SPACE é o ID no nome do recurso do recurso spaces da API REST do Meet. Para mais detalhes, consulte Como o Meet identifica um espaço para reuniões.
Usuário	//cloudidentity.googleapis.com/users/USER em que USER é o ID no campo signedinUser.user do recurso participants da API REST do Meet. Para mais detalhes, consulte Trabalhar com participantes.	A assinatura recebe eventos sobre todos os espaços para reuniões em que o usuário é o proprietário. Normalmente, o proprietário do espaço para reuniões também é o organizador do evento do Google Agenda associado ao espaço.

Criar uma assinatura do Google Workspace

Para criar uma assinatura, use o método subscriptions.create da API Google Workspace Events para criar um recurso Subscription. Especifique os seguintes campos:

• targetResource: um Google Workspace que você identificou na seção anterior, formatado usando o nome completo do recurso.
• 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 se inscrever em eventos sobre mensagens criadas.
• notificationEndpoint: um endpoint de notificação em que sua assinatura do Google Workspace envia eventos. Use o tópico do Pub/Sub que você criou na seção anterior.
• payloadOptions: opções para especificar quantos dados de recursos incluir no payload do evento. Essa configuração afeta o prazo de validade da sua assinatura. Para saber mais, consulte Dados de eventos.

Para criar uma assinatura do Google Workspace:

Apps Script

1. 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 Chat com o ID AAAABBBB, use //chat.googleapis.com/spaces/AAAABBBB.
   • EVENT_TYPES: um ou mais tipos de evento que você quer assinar 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 na nuvem. Formatado como projects/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 os campos incluídos, adicione o campo fieldMask e especifique pelo menos um campo para o recurso alterado. Somente as assinaturas de recursos do Chat permitem incluir dados de recursos.
     • False: exclui dados de recursos.

2. Para criar a assinatura do Google Workspace, execute a função createSubscription no seu projeto do Apps Script.

Python

1. 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('credentials.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 da 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 Chat com o ID AAAABBBB, use //chat.googleapis.com/spaces/AAAABBBB.
   • EVENT_TYPES: um ou mais tipos de evento que você quer assinar 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 na nuvem. Formatado como projects/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 os campos incluídos, adicione o campo fieldMask e especifique pelo menos um campo para o recurso alterado. Somente as assinaturas de recursos do Chat permitem incluir dados de recursos.
     • False: exclui dados de recursos.

2. Para criar a assinatura do Google Workspace, execute o seguinte no terminal:

   python3 create_subscription.py

A API Google Workspace Events 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 extraia mensagens para a assinatura do Pub/Sub.

Para testar sua assinatura do Google Workspace:

Console de APIs do Google

1. Acione um ou mais tipos de eventos no recurso de destino da sua assinatura do Google Workspace. Por exemplo, se você se inscreveu para receber novas mensagens em um espaço do Chat, poste uma mensagem no espaço.

2. No Console de APIs do Google, acesse a página do Pub/Sub:

   Ir para o Pub/Sub

   Verifique se o projeto na nuvem do seu app está selecionado.

3. No menu Pub/Sub, clique em Assinaturas.

4. Na tabela, encontre a assinatura do Pub/Sub para seu tópico e clique no nome dela.

5. Clique na guia Mensagens.

6. Clique em Pull. Pode levar alguns minutos para que um evento gere uma mensagem do Pub/Sub.

gcloud

1. Acione um ou mais tipos de eventos no recurso de destino da sua assinatura do Google Workspace. Por exemplo, se você se inscreveu para receber novas mensagens em um espaço do Chat, poste uma mensagem no espaço.

2. 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 como projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID.
   • MESSAGE_COUNT: o número máximo de mensagens do Pub/Sub que você quer extrair.

   Pode levar alguns minutos para que um evento gere uma mensagem do Pub/Sub.

Para cada evento do Google Workspace que você acionou, uma mensagem é enviada à sua assinatura do Pub/Sub que contém o evento. Para mais detalhes, consulte Como receber eventos como mensagens do Google Cloud Pub/Sub.

Configurar como o app recebe eventos

A assinatura do Pub/Sub que você criou é baseada em pull. Depois de testar sua assinatura do Pub/Sub, é possível atualizar o tipo de entrega para mudar como o app recebe eventos. Por exemplo, é possível configurar a assinatura do Pub/Sub para um tipo de entrega por push, para que seu app possa receber eventos diretamente em um endpoint do app.

Para saber como configurar uma assinatura do Pub/Sub, consulte a documentação do Pub/Sub.

Observação: não é possível definir um projeto do Apps Script como um endpoint de entrega por push no Pub/Sub. Para enviar mensagens do Pub/Sub para um projeto do Apps Script, publique o script como um app da Web.

Inscrever-se em eventos de espaço do Chat como um app do Google Chat

Você pode se inscrever em eventos do Chat como um app do Chat em um espaço em que o app do Chat é membro. Os apps do Chat não podem se inscrever em eventos de usuário.

Escrever um script que chama a API Google Workspace Events

Veja como criar uma assinatura de eventos de espaço do Chat com autenticação de app e aprovação do administrador:

1. Se necessário, crie um app do Chat.

2. Inscrever-se em um recurso do Chat, mas:

   1. Em vez da autenticação do usuário, faça a autenticação como um app do Chat com aprovação única do administrador.

   2. Especifique os escopos de autorização que permitem que o app do Chat se inscreva em eventos do Chat. Esses escopos de autorização sempre começam com chat.app e incluem o seguinte:

      • https://www.googleapis.com/auth/chat.app.memberships: assinar eventos de participantes do espaço do Chat.
      • https://www.googleapis.com/auth/chat.app.memberships.readonly: assinar eventos de participantes do espaço do Chat.
      • https://www.googleapis.com/auth/chat.app.messages.readonly: inscreva-se para receber eventos de mensagens e reações em espaços do Chat.
      • https://www.googleapis.com/auth/chat.app.spaces: inscrever-se em eventos de espaço do Chat.
      • https://www.googleapis.com/auth/chat.app.spaces.readonly: inscrever-se em eventos de espaço do Chat.

O exemplo de código a seguir se inscreve em eventos de mensagem em um espaço do Chat especificado:

Python

  """Create subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = ['https://www.googleapis.com/auth/chat.app.messages.readonly']

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # The Google Workspace resource to monitor for events.
  TARGET_RESOURCE = '//chat.googleapis.com/spaces/SPACE_ID'

  # The types of events to receive.
  EVENT_TYPES = [
                  'google.workspace.chat.message.v1.created',
                  'google.workspace.chat.message.v1.updated',
                  'google.workspace.chat.message.v1.deleted',
                ]

  # 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:

• SPACE_ID: o nome do espaço, que pode ser obtido no método spaces.list na API Chat ou no URL de um espaço.
• TOPIC_NAME: o nome completo do tópico do Pub/Sub que você criou no projeto na nuvem. Formatado como projects/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 os campos incluídos, adicione o campo fieldMask e especifique pelo menos um campo para o recurso alterado. Somente as assinaturas de recursos do Chat permitem incluir dados de recursos.
  • False: exclui dados de recursos.

Inscrever-se em todos os eventos do Chat em uma organização do Google Workspace como um app do Google Chat

Prévia para desenvolvedores:disponível como parte do Programa de Prévia para Desenvolvedores do Google Workspace, que concede acesso antecipado a determinados recursos.

Uma assinatura de cliente permite que seu app do Chat monitore eventos de espaço e de usuário em toda uma organização do Google Workspace.

Para saber como os eventos são entregues para as assinaturas de clientes, incluindo a entrega de eventos em espaços gerenciados por organizações externas, consulte Limitações de assinatura de clientes e comportamentos de entrega.

Requisitos e limitações

• Autenticação: autenticar como um app do Chat com aprovação única do administrador
• SKU: a organização do Google Workspace precisa ter pelo menos uma licença de SKU Enterprise. Esse requisito não é obrigatório durante a fase do Programa de Prévia para Desenvolvedores, mas será no futuro (a ser anunciado separadamente).
• Exclusividade: um app do Chat só pode criar uma assinatura de cliente para uma determinada organização do Google Workspace. Uma organização do Google Workspace pode ter até cinco assinaturas de clientes no total (criadas por diferentes apps do Chat).
• Escopos: requer um ou mais dos seguintes escopos, dependendo dos tipos de evento que você quer receber:
  • https://www.googleapis.com/auth/chat.app.all.spaces.readonly: para receber eventos sobre espaços.
  • https://www.googleapis.com/auth/chat.app.all.memberships.readonly: para receber eventos sobre assinaturas.
  • https://www.googleapis.com/auth/chat.app.all.messages.readonly: para receber eventos sobre mensagens e reações.
  • https://www.googleapis.com/auth/chat.app.all.users.readstate.readonly ( prévia para desenvolvedores): para receber eventos sobre os estados de leitura dos usuários.

Criar uma assinatura de cliente

Para criar uma assinatura de cliente, chame o método subscriptions.create.

O exemplo de código Python a seguir cria uma assinatura de cliente:

Python

"""Create a customer subscription."""

from google.oauth2 import service_account
from apiclient.discovery import build

# Specify required scopes.
# Replace with the scopes needed for the event types you want to receive.
SCOPES = ['https://www.googleapis.com/auth/chat.app.all.messages.readonly']

# Specify service account details.
CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
)

# Monitor all events for the Google Workspace organization.
TARGET_RESOURCE = '//admin.googleapis.com/customers/CUSTOMER_ID'

# The types of events to receive.
EVENT_TYPES = [
    'google.workspace.chat.message.v1.created',
    'google.workspace.chat.message.v1.updated',
    'google.workspace.chat.message.v1.deleted',
]

# The endpoint to deliver events to.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API.
# Note: Use the v1beta endpoint for Developer Preview features.
service = build(
    'workspaceevents',
    'v1beta',
    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:

• CUSTOMER_ID: o ID de cliente. Também é possível usar o alias my_customer para a organização do Google Workspace do app do Chat.
• TOPIC_NAME: o nome completo do tópico do Pub/Sub que você criou no projeto na nuvem. Formatado como projects/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 os campos incluídos, adicione o campo fieldMask e especifique pelo menos um campo para o recurso alterado. Somente as assinaturas de recursos do Chat aceitam a inclusão de dados de recursos.
  • False: exclui dados de recursos.

Temas relacionados

• Tutorial: observar eventos de reunião com o Python e a API REST do Meet
• Quer assinar?
• Listar assinaturas
• Atualizar ou renovar uma assinatura
• Corrigir erros e reativar uma assinatura
• Excluir uma assinatura