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ê aprende a criar uma conta de serviço. Em seguida, mostramos como escrever um script que usa a conta de serviço para fazer a autenticação com a API do Chat e postar uma mensagem em um espaço do Chat.
Os apps de chat podem usar contas de serviço para fazer a autenticação ao chamar a API Google Chat de forma assíncrona. Assim, eles podem:
- Envie mensagens para o Google Chat com
spaces.messages.create
para:- Notifique os usuários quando um job em segundo plano de longa duração for concluído.
- Alerte os usuários de que um servidor ficou off-line.
- Pedir a um atendimento ao cliente para tratar de um caso de cliente recém-aberto.
- Atualize as mensagens enviadas anteriormente com
spaces.messages.update
para:- Mudar o status de uma operação em andamento.
- Atualizar o usuário atribuído ou a data de conclusão de uma tarefa.
- Liste os usuários em um espaço com
spaces.members.list
para:- Ver quem está em um espaço.
- Verifique se todos os participantes de uma equipe estão incluídos na participação no espaço.
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, é possível 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 usuários sem exigir o consentimento de cada um. Depois de configurar a delegação em todo o domínio, é possível fazer chamadas de API usando a conta de serviço para representar uma conta de usuário. A conta de serviço é usada para autenticação, mas a delegação em todo o domínio representa um usuário e, por isso, é considerada autenticação de usuário. Qualquer funcionalidade que exija autenticação do usuário pode usar a delegação em todo o domínio.
Para saber quando os apps de chat exigem autenticação e que tipo de autenticação usar, consulte Tipos de autenticação obrigató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:
- Uma conta do Google Workspace com acesso ao Google Chat .
- Um projeto do Google Cloud com a API Chat ativada. Para criar um projeto e ativar uma API, consulte Criar um projeto e ativar a API.
- Um app do Chat publicado com participação em um espaço do Chat:
- Para criar e publicar um app do Chat, consulte Criar um app do Google Chat com o Cloud Functions.
- Para adicionar um app do Chat a um espaço do Chat, consulte Adicionar apps a espaços ou conversas no Google Chat.
Além disso, você precisa dos seguintes pré-requisitos específicos da linguagem:
Java
- JDK 1.7 ou mais recente
- A ferramenta de gerenciamento de pacotes Maven
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 posterior
- A ferramenta de gerenciamento de pacotes PIP
Node.js
Etapa 1: criar uma conta de serviço no console do Google Cloud
Crie uma conta de serviço que seu app do Chat pode usar para acessar as APIs do Google.
Crie uma conta de serviço
Para criar uma conta de serviço, siga estas etapas:
- No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.
- Clique em Criar conta de serviço.
- Preencha os detalhes da conta de serviço e clique em Criar e continuar.
- Opcional: atribua papéis à sua conta de serviço para conceder acesso aos recursos do seu projeto do Google Cloud. Saiba mais em Como conceder, alterar e revogar acesso a recursos.
- Clique em Continuar.
- 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.
- Clique em Concluído. Anote o endereço de e-mail da conta de serviço.
A conta de serviço aparece na página da conta de serviço. 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:
- No console do Google Cloud, acesse Menu > IAM e administrador > Contas de serviço.
- Selecione a conta de serviço.
- Clique em Chaves > Adicionar chave > Criar nova chave.
- Selecione JSON e clique em Criar.
Seu novo par de chaves pública/privada é gerado e salvo na 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 da chave. Para mais informações sobre como armazenar a chave com segurança, consulte Como gerenciar chaves de contas de serviço. - Clique em Fechar.
Para saber mais 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 na interface de linha de comando:
pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client
Node.js
Para adicionar as bibliotecas de cliente do Google ao seu projeto Node.js, alterne para o diretório do projeto e execute o seguinte comando na interface de linha de comando:
npm install "@googleapis/chat"
Você pode 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
- No diretório do projeto, abra o arquivo
src/main/java/com/google/chat/app/authsample/App.java
. 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(); } }
No código, substitua
SPACE_NAME
por um nome de espaço, que pode ser encontrado no métodospaces.list
na API Chat ou no URL de um espaço.Crie um novo subdiretório chamado
resources
dentro do diretório do seu projeto.Confira se o arquivo de chave privada da conta de serviço tem o nome
credentials.json
e copie-o para o subdiretórioresources
.Para configurar o Maven para incluir 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>
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
- No diretório de trabalho, crie um arquivo chamado
chat_app_auth.py
. Inclua o seguinte código em
chat_app_auth.py
:from httplib2 import Http from oauth2client.service_account import ServiceAccountCredentials from apiclient.discovery import build # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name( 'credentials.json', SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http())) # 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)
No código, substitua
SPACE_NAME
por um nome de espaço, que pode ser encontrado no métodospaces.list
na API Chat ou no URL de um espaço. Confira se o arquivo de chave privada da conta de serviço é denominadocredentials.json
.
Node.js
- No diretório do projeto, crie um arquivo chamado
chat_app_auth.js
. 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);
No código, substitua
SPACE_NAME
por um nome de espaço, que pode ser encontrado no métodospaces.list
na API Chat ou no URL de um espaço. Confira se o arquivo de chave privada da conta de serviço é denominadocredentials.json
.
Etapa 4: executar o exemplo completo
No diretório de trabalho, crie e execute o exemplo:
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
Seu script faz uma solicitação autenticada para a 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 do Chat no espaço especificado.
Para resolver o erro, adicione o app do Chat ao espaço do Chat especificado no script.
Temas relacionados
Saiba o que mais a API Chat pode fazer na documentação de referência da API Chat.