Esta página foi traduzida pela API Cloud Translation.

Criar um app de chat com o Google Cloud Functions

Nesta página, explicamos como criar e interagir com um app de chat usando o Google Cloud Functions.

Para criar o app, você grava e implanta uma função do Cloud que o app usa para processar uma resposta a um evento da mensagem do Google Chat. A resposta é um cartão que exibe o nome do remetente e a imagem do avatar, conforme demonstrado na imagem a seguir:

App de chat respondendo com um card com o nome de exibição do remetente e a imagem
do avatar

Objetivos

Configurar o ambiente.
Criar e implantar uma função do Cloud
Publique o app no Google Chat.
Testar o app.

Pré-requisitos

Uma conta do Google Workspace com acesso ao Google Chat.
Um projeto do Google Cloud.
Ative o faturamento do seu projeto do Cloud. Saiba como verificar o status do faturamento dos seus projetos.

Configurar o ambiente

Antes de usar as APIs do Google, você precisa ativá-las em um projeto do Google Cloud. É possível ativar uma ou mais APIs em um único projeto do Google Cloud.

No console do Google Cloud, ative as APIs Google Chat, Cloud Build, Cloud Functions e Cloud Pub/Sub.

Ative as APIs

Crie e implemente uma Função do Cloud

Criar e implantar uma função do Cloud que gera um card do Chat com o nome de exibição e a imagem de avatar do remetente. Quando o app de chat recebe uma mensagem, ele executa a função e responde com o cartão.

Para criar e implantar a função para seu app de chat, siga estas etapas:

Node.js

No console do Google Cloud, acesse a página do Cloud Functions:

Acesse o Cloud Functions

Verifique se o projeto do app de chat está selecionado.
Clique em Criar função.
Na página "Criar função", configure sua função:
1. Em Nome da função, digite "QuickStartChatApp".
2. Em Tipo de acionador, selecione HTTP.
3. Em "Autenticação", selecione Permitir invocações não autenticadas.
  
  Para mais informações sobre a autenticação no Google Workspace, consulte Autenticar e autorizar apps de chat e solicitações de API.
4. Clique em Salvar.
5. Clique em Próxima.
Em Ambiente de execução, selecione Node.js 10.
Em Código-fonte, selecione Editor in-line.
Em Ponto de entrada, exclua o texto padrão e digite helloChat.

Substitua o conteúdo de index.js pelo seguinte código:

node/avatar-bot/index.js

Ver no GitHub

/**
 * Google Cloud Function that responds to messages sent from a
 * Hangouts Chat room.
 *
 * @param {Object} req Request sent from Hangouts Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Hangouts Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Clique em Implantar.

Python

No console do Google Cloud, acesse a página do Cloud Functions:

Acesse o Cloud Functions

Verifique se o projeto do app de chat está selecionado.
Clique em Criar função.
Na página "Criar função", configure sua função:
1. Em Nome da função, digite "QuickStartChatApp".
2. Em Tipo de acionador, selecione HTTP.
3. Em "Autenticação", selecione Permitir invocações não autenticadas.
  
  Para mais informações sobre a autenticação no Google Workspace, consulte Autenticar e autorizar apps de chat e solicitações de API.
4. Clique em Salvar.
5. Clique em Próxima.
Em Ambiente de execução, selecione Python 3.10.
Em Código-fonte, selecione Editor in-line.
Em Ponto de entrada, exclua o texto padrão e digite hello_chat.

Substitua o conteúdo de main.py pelo seguinte código:

python/avatar-bot/main.py

Ver no GitHub

from typing import Any, Mapping

import flask
import functions_framework

# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request):
    if req.method == "GET":
        return "Hello! This function must be called from Google Chat."

    request_json = req.get_json(silent=True)

    display_name = request_json["message"]["sender"]["displayName"]
    avatar = request_json["message"]["sender"]["avatarUrl"]

    response = create_message(name=display_name, image_url=avatar)

    return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
    avatar_image_widget = {"image": {"imageUrl": image_url}}
    avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
    avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

    header = {"title": f"Hello {name}!"}

    cards = {
        "cardsV2": [
            {
                "cardId": "avatarCard",
                "card": {
                    "name": "Avatar Card",
                    "header": header,
                    "sections": [avatar_section],
                },
            }
        ]
    }

    return cards

Clique em Implantar.

Java

No console do Google Cloud, acesse a página do Cloud Functions:

Acesse o Cloud Functions

Verifique se o projeto do app de chat está selecionado.
Clique em Criar função.
Na página "Criar função", configure sua função:
1. Em Nome da função, digite "QuickStartChatApp".
2. Em Tipo de acionador, selecione HTTP.
3. Em "Autenticação", selecione Permitir invocações não autenticadas.
  
  Veja mais informações sobre a autenticação no Google Workspace em Autenticar e autorizar solicitações de API e app Chat.
4. Clique em Salvar.
5. Clique em Próxima.
Em Ambiente de execução, selecione Java 11.
Em Código-fonte, selecione Editor in-line.
Em Ponto de entrada, exclua o texto padrão e digite HelloChat.
O src/main/java/com/example/Example.java foi renomeado como src/main/java/HelloChat.java.

Substitua o conteúdo de HelloChat.java pelo seguinte código:

java/avatar-bot/src/main/java/HelloChat.java

Ver no GitHub

import com.google.api.services.chat.v1.model.CardWithId;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Card;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1CardHeader;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Image;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Section;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1TextParagraph;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Widget;
import com.google.api.services.chat.v1.model.Message;
import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import java.util.List;

public class HelloChat implements HttpFunction {
  private static final Gson gson = new Gson();

  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);

    if (request.getMethod().equals("GET") || !body.has("message")) {
      response.getWriter().write("Hello! This function must be called from Google Chat.");
      return;
    }

    JsonObject sender = body.getAsJsonObject("message").getAsJsonObject("sender");
    String displayName = sender.has("displayName") ? sender.get("displayName").getAsString() : "";
    String avatarUrl = sender.has("avatarUrl") ? sender.get("avatarUrl").getAsString() : "";
    Message message = createMessage(displayName, avatarUrl);

    response.getWriter().write(gson.toJson(message));
  }

  Message createMessage(String displayName, String avatarUrl) {
    GoogleAppsCardV1CardHeader cardHeader = new GoogleAppsCardV1CardHeader();
    cardHeader.setTitle(String.format("Hello %s!", displayName));

    GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
    textParagraph.setText("Your avatar picture: ");

    GoogleAppsCardV1Widget avatarWidget = new GoogleAppsCardV1Widget();
    avatarWidget.setTextParagraph(textParagraph);

    GoogleAppsCardV1Image image = new GoogleAppsCardV1Image();
    image.setImageUrl(avatarUrl);

    GoogleAppsCardV1Widget avatarImageWidget = new GoogleAppsCardV1Widget();
    avatarImageWidget.setImage(image);

    GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
    section.setWidgets(List.of(avatarWidget, avatarImageWidget));

    GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
    card.setName("Avatar Card");
    card.setHeader(cardHeader);
    card.setSections(List.of(section));

    CardWithId cardWithId = new CardWithId();
    cardWithId.setCardId("previewLink");
    cardWithId.setCard(card);

    Message message = new Message();
    message.setCardsV2(List.of(cardWithId));

    return message;
  }
}

Substitua o conteúdo de pom.xml pelo seguinte código:

java/avatar-bot/pom.xml.

Ver no GitHub

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>cloudfunctions</groupId>
  <artifactId>http-function</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.target>11</maven.compiler.target>
    <maven.compiler.source>11</maven.compiler.source>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.1</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.9.1</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.google.apis/google-api-services-chat -->
    <dependency>
      <groupId>com.google.apis</groupId>
      <artifactId>google-api-services-chat</artifactId>
      <version>v1-rev20230115-2.0.0</version>
    </dependency>
  </dependencies>

  <!-- Required for Java 11 functions in the inline editor -->
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
        <configuration>
          <excludes>
            <exclude>.google/</exclude>
          </excludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Clique em Implantar.

A página do Cloud Functions é aberta, e sua função aparece com um indicador de progresso de implantação ao lado do nome da função. Quando o indicador de progresso desaparecer e uma marca de seleção aparecer, a função será implantada.

Publicar o app no Google Chat

Depois que a Função do Cloud for implantada, siga estas etapas para a transformar em um app do Google Chat:

No console do Google Cloud, clique em Menu > Cloud Functions.

Acesse o Cloud Functions

Verifique se o projeto em que você ativou o Cloud Functions está selecionado.
Na lista de funções, clique em QuickStartChatApp.
Na página "Detalhes da função", clique em Acionar.
Em URL do acionador, copie o URL.
Pesquise "API Google Chat" e clique em API Google Chat.
Selecione Gerenciar.
Clique em Configuração e configure o app Google Chat:
1. Em Nome do app, insira Quickstart App.
2. Em URL do avatar, insira https://developers.google.com/chat/images/quickstart-app-avatar.png.
3. Em Descrição, digite Quickstart app.
4. Em Funcionalidade, selecione Receber mensagens individuais, Participar de espaços e conversas em grupo e Registrar erros no Cloud Logging.
5. Em Configurações de conexão, selecione URL do aplicativo e cole o URL do acionador do Cloud Functions na caixa.
6. Em Permissões, selecione Pessoas e grupos específicos no seu domínio e digite o endereço de e-mail.
Clique em Salvar.

O app está pronto para receber e responder a mensagens no Google Chat.

Testar o app de chat

Para testar o app de chat, envie uma mensagem direta para ele:

Abra o Google Chat.
Para enviar uma mensagem direta ao app, clique em Iniciar um chat e, na janela exibida, clique em Encontrar apps.
Na caixa de diálogo Encontrar apps, procure "App de início rápido".
Para abrir uma mensagem direta com o app, encontre o App de início rápido e clique em Adicionar > Chat.
Na mensagem direta, digite Hello e pressione enter.

O app retorna um card com seu nome de exibição e imagem de avatar.

Próximas etapas

Para resolver problemas e depurar o app de chat, consulte estas páginas:

À medida que você cria o app de chat, talvez seja necessário depurá-lo lendo os registros de erro do app. Para ler os registros, no console do Google Cloud, acesse o Explorador de registros.
Resolver problemas.

Para adicionar mais funcionalidades ao app Chat, consulte estes guias:

Criar cards interativos: as mensagens do cartão são compatíveis com um layout definido, elementos de IU interativos, como botões, e rich media, como imagens. Use mensagens de cartão para apresentar informações detalhadas, coletar informações dos usuários e orientá-los a avançar.
Suporte a comandos de barra: os comandos de barra permitem registrar e anunciar comandos específicos que os usuários podem fornecer ao app digitando um comando que começa com uma barra (/), como /help.
Caixas de diálogo de início: são caixas de diálogo baseadas em janelas que o app pode abrir para interagir com um usuário. Vários cartões podem ser conectados sequencialmente, o que ajuda os usuários a concluir processos de várias etapas, como o preenchimento de dados do formulário.

Para saber mais sobre a API Google Chat, consulte a documentação de referência.