Criar uma assinatura do Google Workspace

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:

  1. Configurar o ambiente.
  2. 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.
  3. Chame o método create() da API Google Workspace Events no recurso Subscription.
  4. Teste sua assinatura do Google Workspace para garantir que seu tópico do Pub/Sub receba eventos em que você se inscreveu.
  5. 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:
    1. Instale o Google Cloud CLI.
    2. Para inicializar a CLI gcloud, execute o seguinte código:
      3.   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:
    1. Instale o Google Cloud CLI.
    2. Para inicializar a CLI gcloud, execute o seguinte código:
      3.   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:

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 do Cloud para seu aplicativo:

    gcloud config set project PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto do Cloud para seu app.

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

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > ID do cliente OAuth.
  3. Clique em Tipo de aplicativo > Aplicativo da Web.
  4. No campo Nome, digite um nome para a credencial. Ele só aparece 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 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.
  6. 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.

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

Android

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > ID do cliente OAuth.
  3. Clique em Tipo de aplicativo > Android.
  4. No campo "Nome", digite um nome para a credencial. Ele só aparece no console do Google Cloud.
  5. No campo "Package name", insira o nome do pacote do arquivo AndroidManifest.xml.
  6. No campo "Impressão digital do certificado SHA-1", digite a impressão digital do certificado SHA-1 gerada.
  7. Clique em Criar. A tela "Cliente OAuth criado" vai aparecer, mostrando seu novo ID do cliente.
  8. Clique em OK. A credencial recém-criada será exibida em "IDs do cliente OAuth 2.0".

iOS

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > ID do cliente OAuth.
  3. Clique em Tipo de aplicativo > iOS.
  4. No campo "Nome", digite um nome para a credencial. Ele só aparece 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 seu aplicativo aparecer na Apple App Store, digite 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. Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
  9. Clique em OK. A credencial recém-criada será exibida em "IDs do cliente OAuth 2.0".

App do Chrome

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > ID do cliente OAuth.
  3. Clique em Tipo de aplicativo > Aplicativo do Google Chrome.
  4. No campo "Nome", digite um nome para a credencial. Ele só aparece no console do Google Cloud.
  5. 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.
  6. Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
  7. Clique em OK. A credencial recém-criada será exibida em "IDs do cliente OAuth 2.0".

App para computador

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > ID do cliente OAuth.
  3. Clique em Tipo de aplicativo > App para computador.
  4. No campo Nome, digite um nome para a credencial. Ele só aparece no console do Google Cloud.
  5. Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
  6. Clique em OK. A credencial recém-criada aparece em IDs do cliente OAuth 2.0.

TVs e dispositivos de entrada limitada

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > ID do cliente OAuth.
  3. Clique em Tipo de aplicativo > TVs e dispositivos de entrada limitada.
  4. No campo "Nome", digite um nome para a credencial. Ele só aparece no console do Google Cloud.
  5. Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
  6. Clique em OK. A credencial recém-criada será exibida em "IDs do cliente OAuth 2.0".

Plataforma Universal do Windows (UWP)

  1. No console do Google Cloud, acesse Menu > APIs e serviços > Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais > ID do cliente OAuth.
  3. Clique em Tipo de aplicativo > Universal Windows Platform (UWP).
  4. No campo "Nome", digite um nome para a credencial. Ele só aparece no console do Google Cloud.
  5. 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.
  6. Clique em Criar. A tela cliente OAuth criado é exibida, mostrando seu novo ID e chave secreta do cliente.
  7. 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.

  1. No console do Google Cloud, 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 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

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

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

    1. Digite 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, por exemplo, 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 está formatado como projects/PROJECT_ID/topics/TOPIC_ID. Esse nome completo será usado 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 principais, adicione a conta de serviço do aplicativo do Google Workspace que envia eventos à sua assinatura:
      1. Para eventos do Chat, chat-api-push@system.gserviceaccount.com.
      2. Para eventos do Meet, meet-api-event-push@system.gserviceaccount.com.
    4. No menu Atribuir funções, selecione Pub/Sub Publisher.
    5. Clique em Salvar. A atualização das permissões do tópico pode levar alguns minutos.

gcloud

  1. 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, como workspace-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.

  2. 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 como projects/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.

    A atualização das permissões do seu tópico pode levar alguns minutos.

  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 a assinatura, como workspace-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

  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 Google Chat com o ID AAAABBBB, 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 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 quais campos são incluídos, adicione o campo fieldMask 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.

  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('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 ID AAAABBBB, 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 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 quais campos são incluídos, adicione o campo fieldMask 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.

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

  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 novas mensagens em um espaço do Chat, poste uma mensagem no espaço.

  2. No console do Google Cloud, acesse a página do Pub/Sub:

    Ir para o Pub/Sub

    Verifique se o projeto do Cloud para seu app está selecionado.

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

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

  5. Clique na guia Mensagens.

  6. Clique em Pull. Pode levar até alguns minutos para um evento gerar 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 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/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.