Fazer a autenticação como um app do Google Chat

Neste guia, explicamos como configurar e usar uma conta de serviço para acessar a API Google Chat em nome de um app do Chat. Primeiro, você verá como criar uma conta de serviço. Depois, há uma demonstração de como escrever um script que usa a conta de serviço para se autenticar com a API Chat e postar uma mensagem em um espaço do Chat.

Os apps do Chat podem usar contas de serviço para autenticar ao chamar de forma assíncrona a API Google Chat. Assim, eles podem:

  • Envie mensagens ao Google Chat com spaces.messages.create para:
    • Notifique os usuários quando um job em segundo plano de longa duração for concluído.
    • Alertar os usuários de que um servidor ficou off-line.
    • Peça a um representante de suporte ao cliente para atender a um caso de cliente recém-aberto.
  • Atualize as mensagens enviadas anteriormente com spaces.messages.update para:
    • Alterar o status de uma operação em andamento.
    • Atualizar o responsável ou a data de conclusão de uma tarefa.
  • Listar os usuários em um espaço com spaces.members.list para:
    • Ver quem está em um espaço.
    • Verifique se a participação no espaço inclui todas as pessoas de uma equipe.

Quando autenticados com uma conta de serviço, os apps do Chat precisam participar do espaço para receber dados ou realizar ações em um espaço. Por exemplo, para listar participantes de um espaço ou criar uma mensagem, o app do Chat precisa ser participante do espaço.

Se o app do Chat precisar acessar dados do usuário ou executar ações em nome de um usuário, faça a autenticação como usuário.

Se você é um administrador de domínio, pode conceder a delegação de autoridade em todo o domínio para autorizar a conta de serviço de um aplicativo a acessar os dados dos seus usuários sem exigir o consentimento de cada um. Depois de configurar a delegação em todo o domínio, faça chamadas de API usando sua conta de serviço para representar uma conta de usuário. Embora uma conta de serviço seja usada para autenticação, a delegação em todo o domínio se passa por um usuário e, portanto, é considerada uma autenticação de usuário. Em qualquer funcionalidade que exija autenticação do usuário, é possível usar a delegação em todo o domínio.

Para saber quando os apps do Chat exigem autenticação e que tipo de autenticação usar, consulte Tipos de autenticação necessária na visão geral de autenticação e autorização da API Chat.

Pré-requisitos

Para executar o exemplo neste guia, você precisa dos seguintes pré-requisitos:

Além disso, você precisa dos seguintes pré-requisitos específicos da linguagem:

Java

  • JDK 1.7 ou mais recentes
  • A ferramenta de gerenciamento de pacotes Maven (em inglês)
  • Um projeto Maven inicializado. Para inicializar um novo projeto, execute o seguinte comando na interface de linha de comando:

    mvn archetype:generate -DgroupId=com.google.chat.app.authsample -DartifactId=auth-sample-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
    

Python

  • Python 3.6 ou superior
  • A ferramenta de gerenciamento de pacotes pip

Node.js

  • Node.js
  • A ferramenta de gerenciamento de pacotes npm
  • Um projeto Node.js inicializado. Para inicializar um novo projeto, crie e mude para uma nova pasta. Em seguida, execute o seguinte comando na interface de linha de comando:

    npm init
    

Apps Script

Etapa 1: criar uma conta de serviço no console do Google Cloud

Crie uma conta de serviço que o app do Chat possa usar para acessar as APIs do Google.

Crie uma conta de serviço

Para criar uma conta de serviço, siga estas etapas:

Console do Google Cloud

  1. No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.

    Acessar a página "Contas de serviço"

  2. Clique em Criar conta de serviço.
  3. Preencha os detalhes da conta de serviço e clique em Criar e continuar.
  4. Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do seu projeto do Google Cloud. Confira mais detalhes em Como conceder, alterar e revogar acesso a recursos.
  5. Clique em Continuar.
  6. Opcional: insira usuários ou grupos que podem gerenciar e realizar ações com essa conta de serviço. Para mais detalhes, consulte Como gerenciar a representação de uma conta de serviço.
  7. Clique em Concluído. Anote o endereço de e-mail da conta de serviço.

CLI da gcloud

  1. Crie a conta de serviço:
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
      --display-name="SERVICE_ACCOUNT_NAME"
  2. Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do seu projeto do Google Cloud. Confira mais detalhes em Como conceder, alterar e revogar acesso a recursos.

A conta de serviço aparece na página dela. Em seguida, crie uma chave privada para a conta de serviço.

Criar uma chave privada

Para criar e fazer o download de uma chave privada para a conta de serviço, siga estas etapas:

  1. No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.

    Acessar a página "Contas de serviço"

  2. Selecione sua conta de serviço.
  3. Clique em Chaves > Adicionar chave > Criar nova chave.
  4. Selecione JSON e clique em Criar.

    Seu novo par de chaves pública/privada é gerado e transferido por download para sua máquina como um novo arquivo. Salve o arquivo JSON salvo como credentials.json no diretório de trabalho. Esse arquivo é a única cópia desta chave. Para saber mais sobre como armazenar a chave com segurança, consulte Como gerenciar chaves de contas de serviço.

  5. Clique em Fechar.

Para mais informações sobre contas de serviço, consulte contas de serviço na documentação do Google Cloud IAM.

Etapa 2: instalar a biblioteca de cliente do Google e outras dependências

Instale a biblioteca de cliente do Google e outras dependências necessárias para o projeto.

Java

Para adicionar as bibliotecas de cliente do Google e outras dependências necessárias ao projeto Maven, edite o arquivo pom.xml no diretório do projeto e adicione as seguintes dependências:

<dependencies>
  <!-- ... existing dependencies ... -->
  <dependency>
    <groupId>com.google.apis</groupId>
    <artifactId>google-api-services-chat</artifactId>
    <version>v1-rev20230905-2.0.0</version>
  </dependency>
  <dependency>
    <groupId>com.google.auth</groupId>
    <artifactId>google-auth-library-oauth2-http</artifactId>
    <version>1.19.0</version>
  </dependency>
  <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.10.1</version>
  </dependency>
</dependencies>

Python

Se você ainda não instalou as bibliotecas de cliente do Google para Python, execute o seguinte comando na interface de linha de comando:

pip3 install --upgrade google-api-python-client google-auth

Node.js

Para adicionar as bibliotecas de cliente do Google ao seu projeto Node.js, mude para o diretório do projeto e execute o seguinte comando na interface de linha de comando:

npm install "@googleapis/chat"

Apps Script

Este exemplo usa a biblioteca OAuth2 para Apps Script para gerar um token JWT para autenticação de conta de serviço. Para adicionar a biblioteca ao seu projeto do Apps Script:

  1. À esquerda, clique em Editor .
  2. À esquerda, ao lado de Bibliotecas, clique em Adicionar uma biblioteca .
  3. Insira o ID do script 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
  4. Clique em Pesquisar e, depois, em Adicionar.

Neste exemplo, o serviço avançado do Chat é usado para chamar a API Google Chat. Se quiser ativar o serviço para seu projeto do Apps Script, faça o seguinte:

  1. À esquerda, clique em Editor .
  2. À esquerda, ao lado de Serviços, clique em Adicionar um serviço .
  3. Selecione API Google Chat.
  4. Em Versão, selecione v1.
  5. Clique em Adicionar.

É possível usar qualquer linguagem compatível com nossas bibliotecas de cliente.

Etapa 3: escrever um script que use a conta de serviço para fazer a autenticação com a API Chat

O código a seguir é autenticado na API Chat usando uma conta de serviço e, em seguida, posta uma mensagem em um espaço do Chat:

Java

  1. No diretório do projeto, abra o arquivo src/main/java/com/google/chat/app/authsample/App.java.
  2. Substitua o conteúdo em App.java pelo seguinte código:

    package com.google.chat.app.authsample;
    
    import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
    import com.google.api.client.http.HttpRequestInitializer;
    import com.google.api.client.json.gson.GsonFactory;
    import com.google.api.services.chat.v1.HangoutsChat;
    import com.google.api.services.chat.v1.model.Message;
    import com.google.auth.http.HttpCredentialsAdapter;
    import com.google.auth.oauth2.GoogleCredentials;
    
    /**
     * Authenticates with Chat API via service account credentials,
     * then creates a Chat message.
     */
    public class App {
        // Specify required scopes.
        private static final String CHAT_SCOPE = "https://www.googleapis.com/auth/chat.bot";
    
        // Specify service account details.
        private static final String PRIVATE_KEY_RESOURCE_URI = "/credentials.json";
    
        public static void main( String[] args ) {
            try {
                // Run app.
                Message response = App.createChatMessage();
                // Print details about the created message.
                System.out.println(response);
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    
        private static Message createChatMessage() throws Exception {
            // Build the Chat API client and authenticate with the service account.
            GoogleCredentials credentials = GoogleCredentials.fromStream(
                App.class.getResourceAsStream(PRIVATE_KEY_RESOURCE_URI))
                .createScoped(CHAT_SCOPE);
            HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);
            HangoutsChat chatService = new HangoutsChat.Builder(
                GoogleNetHttpTransport.newTrustedTransport(),
                GsonFactory.getDefaultInstance(),
                requestInitializer)
                .setApplicationName("auth-sample-app")
                .build();
    
            // The space to create the message in.
            //
            // Replace SPACE_NAME with a space name.
            // Obtain the space name from the spaces resource of Chat API,
            // or from a space's URL.
            String spaceName = "spaces/SPACE_NAME";
    
            // Create a Chat message.
            Message message = new Message().setText("Hello, world!");
            return chatService.spaces().messages().create(spaceName, message).execute();
        }
    }
    
  3. No código, substitua SPACE_NAME por um nome de espaço, que pode ser encontrado no método spaces.list na API Chat ou no URL de um espaço.

  4. Crie um novo subdiretório chamado resources no diretório do seu projeto.

  5. Verifique se o arquivo de chave privada da conta de serviço tem o nome credentials.json e copie-o para o subdiretório resources.

  6. Para que o Maven inclua o arquivo de chave privada no pacote do projeto, edite o arquivo pom.xml no diretório do projeto e adicione a seguinte configuração à seção <build>:

    <build>
      <!-- ... existing configurations ... -->
      <resources>
        <resource>
          <directory>resources</directory>
        </resource>
      </resources>
    </build>
    
  7. Para configurar o Maven para incluir as dependências no pacote do projeto e executar a classe principal do aplicativo, edite o arquivo pom.xml no diretório do projeto e adicione a seguinte configuração à seção <plugins>:

    <plugins>
      <!-- ... existing configurations ... -->
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <configuration>
          <archive>
            <manifest>
              <mainClass>com.google.chat.app.authsample.App</mainClass>
            </manifest>
          </archive>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
        </configuration>
      </plugin>
    </plugins>
    

Python

  1. No diretório de trabalho, crie um arquivo chamado chat_app_auth.py.
  2. Inclua o seguinte código em chat_app_auth.py:

    from apiclient.discovery import build
    from google.oauth2 import service_account
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = service_account.Credentials.from_service_account_file(
        'credentials.json', scopes=SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', credentials=CREDENTIALS)
    
    # Create a Chat message.
    result = chat.spaces().messages().create(
    
        # The space to create the message in.
        #
        # Replace SPACE_NAME with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE_NAME',
    
        # The message to create.
        body={'text': 'Hello, world!'}
    
    ).execute()
    
    # Prints details about the created message.
    print(result)
    
  3. No código, substitua SPACE_NAME por um nome de espaço, que pode ser encontrado no método spaces.list na API Chat ou no URL de um espaço. Confira se o arquivo de chave privada da conta de serviço tem o nome credentials.json.

Node.js

  1. No diretório do projeto, crie um arquivo chamado chat_app_auth.js.
  2. Inclua o seguinte código em chat_app_auth.js:

    const chat = require('@googleapis/chat');
    
    async function createMessage() {
      const auth = new chat.auth.GoogleAuth({
    
        // Specify service account details.
        keyFilename: 'credentials.json',
    
        // Specify required scopes.
        scopes: ['https://www.googleapis.com/auth/chat.bot']
    
      });
      const authClient = await auth.getClient();
    
      // Create the Chat API client and authenticate with the service account.
      const chatClient = await chat.chat({
        version: 'v1',
        auth: authClient
      });
    
      // Create a Chat message.
      const result = await chatClient.spaces.messages.create({
    
        // The space to create the message in.
        //
        // Replace SPACE_NAME with a space name.
        // Obtain the space name from the spaces resource of Chat API,
        // or from a space's URL.
        parent: 'spaces/SPACE_NAME',
    
        // The message to create.
        requestBody: { 'text': 'Hello, world!' }
    
      });
      return result;
    }
    
    // Execute function then print details about the created message.
    createMessage().then(console.log);
    
  3. No código, substitua SPACE_NAME por um nome de espaço, que pode ser encontrado no método spaces.list na API Chat ou no URL de um espaço. Confira se o arquivo de chave privada da conta de serviço tem o nome credentials.json.

Apps Script

  1. No editor do Apps Script, edite o arquivo appsscript.json e adicione o escopo do OAuth necessário para fazer solicitações externas e receber o token OAuth da conta de serviço:

      "oauthScopes": [
        "https://www.googleapis.com/auth/script.external_request"
      ]
    
  2. Salve o seguinte código em um arquivo chamado ChatAppAuth.gs no seu projeto do Apps Script:

    // Specify the contents of the file credentials.json.
    const CREDENTIALS = CREDENTIALS;
    
    const SCOPE = 'https://www.googleapis.com/auth/chat.bot';
    
    // The space to create the message in.
    //
    // Replace SPACE_NAME with a space name.
    // Obtain the space name from the spaces resource of Chat API,
    // or from a space's URL.
    const PARENT = 'spaces/SPACE_NAME'
    
    /**
     * Authenticates with Chat API via app credentials, then posts a message.
     */
    function createMessageWithAppCredentials() {
      try {
        const service = getService_();
        if (!service.hasAccess()) {
          console.error(service.getLastError());
          return;
        }
    
        // Specify the message to create.
        const message = {'text': 'Hello world!'};
    
        // Call Chat API with a service account to create a message.
        const result = Chat.Spaces.Messages.create(
            message,
            PARENT,
            {},
            // Authenticate with the service account token.
            {'Authorization': 'Bearer ' + service.getAccessToken()});
    
        // Log details about the created message.
        console.log(result);
    
      } catch (err) {
        // TODO (developer) - Handle exception.
        console.log('Failed to create message with error %s', err.message);
      }
    }
    
    /**
     * Configures the OAuth library to authenticate with the service account.
     */
    function getService_() {
      return OAuth2.createService(CREDENTIALS.client_email)
          .setTokenUrl('https://oauth2.googleapis.com/token')
          .setPrivateKey(CREDENTIALS.private_key)
          .setIssuer(CREDENTIALS.client_email)
          .setSubject(CREDENTIALS.client_email)
          .setScope(SCOPE)
          .setPropertyStore(PropertiesService.getScriptProperties());
    }
    
  3. No código, substitua CREDENTIALS pelo conteúdo do arquivo credentials.json.

  4. No código, substitua SPACE_NAME por um nome de espaço, que pode ser encontrado no método spaces.list na API Chat ou no URL de um espaço.

Etapa 4: executar o exemplo completo

No diretório de trabalho, crie e execute a amostra:

Java

mvn compile assembly:single
java -jar target/auth-sample-app-1.0-SNAPSHOT-jar-with-dependencies.jar

Python

python3 chat_app_auth.py

Node.js

node chat_app_auth.js

Apps Script

Abra o arquivo ChatAppAuth.gs no Editor do Apps Script e clique em Executar.

Seu script faz uma solicitação autenticada à API Chat, que responde postando uma mensagem em um espaço do Chat como um app do Chat.

Resolver problemas do exemplo

Nesta seção, descrevemos problemas comuns que podem ser encontrados ao tentar executar esta amostra.

Você não tem permissão para usar este app

Ao executar o script, talvez você receba o seguinte erro:

<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}/messages?alt=json returned "You are not permitted to use this app". Details: "You are not permitted to use this app">

Essa mensagem de erro significa que o app do Chat não tem permissão para criar mensagens no espaço especificado do Chat.

Para resolver o erro, adicione o app do Chat ao espaço do Chat especificado no script.

Saiba o que mais a API Chat pode fazer na documentação de referência dela.