Autenticar como app de chat

Neste guia, explicamos 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ê vai aprender a criar uma conta de serviço. Em seguida, você vai aprender a 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 a autenticação ao chamar a API REST do Google Chat de forma assíncrona:

  • 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.
    • 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:
    • Altera o status de em operação em andamento.
    • Atualizar o usuário atribuído a uma tarefa ou a data de conclusão.
  • 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 participantes de uma equipe.

Quando autenticado 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 uma associação no espaço. Por exemplo, para listar participantes ou criar uma mensagem em um espaço, o app Chat precisa ser membro dele.

Caso seu app de chat precise acessar dados do usuário ou realizar ações em nome dele, faça a autenticação como um usuário.

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 da 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 para seu app do Chat 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 seu projeto do Google Cloud. Para mais detalhes, consulte Como conceder, alterar e revogar o acesso a recursos.
  5. Clique em Continuar.
  6. Opcional: insira usuários ou grupos que possam 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.

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 para sua máquina como um novo arquivo. Esse arquivo é a única cópia da chave. Para informações sobre como armazenar sua chave com segurança, consulte Como gerenciar chaves de conta 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: criar um script que use a conta de serviço para fazer a autenticação com a API REST do Chat

O código abaixo é autenticado com a API REST do Chat usando uma conta de serviço e, em seguida, 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 acessado 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

Esta seção descreve problemas comuns que você pode encontrar ao tentar executar essa amostra.

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

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 no espaço em que ele 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.