Autenticar como app de chat

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

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:

  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 à 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.
  5. Clique em Continuar.
  6. 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.
  7. 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:

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

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

  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 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)

  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.

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.