Veja neste guia como configurar e usar uma conta de serviço para acessar a API REST do Google Chat em nome de um app de chat. Primeiro, você verá como criar uma conta de serviço. Em seguida, ele demonstra como escrever um script que usa a conta de serviço para autenticar com a API Chat e postar uma mensagem em um espaço do Chat.
Os apps de chat podem usar contas de serviço para fazer autenticação ao chamar a API Google Chat REST 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.
- Alertar os usuários de que um servidor ficou off-line.
- Peça a uma pessoa de suporte ao cliente para tratar de um caso de cliente recém-aberto.
- Atualize as mensagens enviadas anteriormente com
spaces.messages.update
para:- Altere o status de em operação em andamento.
- Atualizar o responsável ou a data de conclusão de uma tarefa.
- Liste os usuários em um espaço com
spaces.members.list
para:- Veja quem está em um espaço.
- A verificação da associação ao espaço inclui todos os membros de uma equipe.
Quando autenticados com uma conta de serviço, para receber dados ou realizar ações em um espaço do Chat, os apps de chat precisam ter participação no espaço. Por exemplo, para listar participantes ou criar uma mensagem em um espaço, o app Chat precisa ser participante dele.
Se o app Chat precisar acessar dados do usuário ou realizar ações em nome dele, faça a autenticação como usuário.
Se você for um administrador de domínio, poderá conceder 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 que cada usuário autorize. Depois de configurar a delegação em todo o domínio, é possível fazer 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 personifica um usuário e, portanto, é considerada autenticação de usuário. Qualquer funcionalidade que exija autenticação do usuário pode ser usada com a delegação em todo o domínio.
Para saber mais sobre quando os apps de 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:
Python
- Python 3.6 ou superior
- a ferramenta de gerenciamento de pacotes pip;
As bibliotecas de cliente do Google para Python. Para instalá-los, execute o seguinte comando na interface de linha de comando:
pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client
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 Chat publicado com a participação em um espaço do Chat:
- Para criar e publicar um app de chat, consulte Criar um app do Google Chat com o Cloud Functions.
- Veja como adicionar um app de chat a um espaço do Chat em Adicionar apps a espaços ou conversas no Google Chat.
Etapa 1: criar uma conta de serviço no Console do Google Cloud
Crie uma conta de serviço que seu app de chat 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 à conta de serviço para conceder acesso aos recursos do projeto do Google Cloud. Para mais detalhes, consulte Como conceder, alterar e revogar o acesso a recursos.
- Clique em Continuar.
- Opcional: digite os 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 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 sua conta de serviço.
- Clique em Chaves > Adicionar chave > Criar nova chave.
- Selecione JSON e clique em Criar.
Seu novo par de chave pública/privada é gerado e o download é feito na máquina como um novo arquivo. Esse arquivo é a única cópia da chave. Para mais informações sobre como armazenar a chave com segurança, consulte Como gerenciar chaves da conta de serviço.
- Clique em Fechar.
Para mais informações sobre contas de serviço, consulte contas do serviço na documentação do Google Cloud IAM.
Etapa 2: criar um script que use a conta de serviço para fazer a autenticação com a API REST do Chat
O código a seguir é autenticado com a API REST do Chat usando uma conta de serviço e posta uma mensagem em um espaço do Chat:
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( 'service_account.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() 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.
Etapa 3: executar o exemplo completo
No diretório de trabalho, crie e execute o exemplo:
Python
python3 chat_app_auth.py
Seu script faz uma solicitação autenticada à API REST do Chat, que responde postando uma mensagem em um espaço do Chat como um app de chat.
Resolver problemas do exemplo
Nesta seção, descrevemos problemas comuns que você pode encontrar ao tentar executar esta amostra.
Você não tem permissão para usar este app
Ao executar chat_app_auth.py
, talvez você receba um erro que diz:
<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 Chat não tem permissão para postar mensagens do Chat no espaço do Chat em que está tentando postar.
Para resolver o erro, adicione o app Chat ao espaço do Chat especificado em chat_app_auth.py
.
Próxima etapa
Para saber o que mais a API Chat pode fazer, consulte a documentação de referência da API Chat.