Esta página foi traduzida pela API Cloud Translation.

Criar um app HTTP do Google Chat com o Cloud Functions

Nesta página, explicamos como criar um app HTTP Chat. Há maneiras diferentes de implementar essa arquitetura. No Google Cloud, é possível usar o Cloud Functions, o Cloud Run e o App Engine. Neste guia de início rápido, você escreve e implanta uma função do Cloud que o app do Chat usa para responder à mensagem de um usuário.

Com essa arquitetura, você configura o Chat para se integrar ao Google Cloud ou a um servidor local usando HTTP, conforme mostrado no diagrama a seguir:

Arquitetura de um app do Chat usando um serviço da Web em um servidor local.

No diagrama anterior, um usuário que interage com um app HTTP Chat tem o seguinte fluxo de informações:

Um usuário envia uma mensagem no Chat para um app do Chat em uma mensagem direta ou em um espaço.
Uma solicitação HTTP é enviada para um servidor da Web que é um sistema na nuvem ou no local que contém a lógica do app do Chat.
A lógica do app Chat pode ser integrada aos serviços do Google Workspace (como Agenda e Planilhas), outros Serviços do Google (como Maps, YouTube e Vertex AI) ou outros serviços da Web (como um sistema de gerenciamento de projetos ou ferramenta de tíquetes).
O servidor da Web envia uma resposta HTTP de volta ao serviço do app do Chat no Chat.
A resposta é entregue ao usuário.
Opcionalmente, o app do Chat pode chamar a API Chat para postar mensagens de forma assíncrona ou realizar outras operações.

Essa arquitetura oferece flexibilidade para usar bibliotecas e componentes que já existem no seu sistema, já que os apps do Chat podem ser projetados usando linguagens de programação diferentes.

Objetivos

Configurar o ambiente.
Crie e implante uma função do Cloud.
Publique o app no Chat.
Testar o app.

Pré-requisitos

Uma conta do Google Workspace com acesso ao Google Chat em uma organização do Google Workspace que permita invocações não autenticadas da função do Google Cloud.

Um projeto do Google Cloud.
Ative o faturamento do seu projeto do Cloud. Saiba como verificar o status de faturamento dos seus projetos.

Configurar o ambiente

Antes de usar as APIs do Google, elas precisam ser ativadas 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, Cloud Pub/Sub, Cloud Logging, Artifact Registry e Cloud Run.

Ativar as APIs

Crie e implemente uma Função do Cloud

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

Para criar e implantar a função do seu app do Chat, conclua as seguintes 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 do Chat está selecionado.
Clique em Criar função.
Na página "Criar função", configure sua função:
1. Em Ambiente, selecione 2a geração.
2. Em Nome da função, insira QuickStartChatApp.
3. Em Região, selecione uma opção.
4. Em "Autenticação", selecione Permitir invocações não autenticadas.
5. Clique em Next.
Em Ambiente de execução, selecione Node.js 20.
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:

nó/avatar-app/index.js

Ver no GitHub

/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google 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 Google 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 {
    text: 'Here\'s your avatar',
    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 do Chat está selecionado.
Clique em Criar função.
Na página "Criar função", configure sua função:
1. Em Nome da função, insira QuickStartChatApp.
2. Em Tipo de acionador, selecione HTTP.
3. Em "Autenticação", selecione Permitir invocações não autenticadas.
4. Clique em Salvar.
5. Clique em Next.
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-app/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) -> Mapping[str, Any]:
  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 = {
      "text": "Here's your avatar",
      "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 do Chat está selecionado.
Clique em Criar função.
Na página "Criar função", configure sua função:
1. Em Nome da função, insira QuickStartChatApp.
2. Em Tipo de acionador, selecione HTTP.
3. Em "Autenticação", selecione Permitir invocações não autenticadas.
4. Clique em Salvar.
5. Clique em Next.
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-app/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.setText("Here's your avatar");
    message.setCardsV2(List.of(cardWithId));

    return message;
  }
}

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

java/avatar-app/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 de detalhes do Cloud Functions é aberta e sua função aparece com dois indicadores de progresso: um para o build e outro para o serviço. Quando os dois indicadores de progresso desaparecerem e forem substituídos por uma marca de seleção, a função será implantada e estará pronta.

Publicar o app no Google Chat

Depois que a função do Cloud for implantada, siga estas etapas para transformá-la 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 Acionador.
Em URL do acionador, copie o URL.
Pesquise "API Google Chat", clique em API Google Chat e depois em Gerenciar.

Acessar a API Chat
Clique em Configuração e configure o app Google Chat:
1. Em Nome do app, insira Quickstart App.
2. No URL do avatar, digite https://developers.google.com/chat/images/quickstart-app-avatar.png.
3. Em Descrição, digite Quickstart app.
4. Em Funcionalidade, selecione Receber mensagens individuais e Participar de espaços e conversas em grupo.
5. Em Configurações de conexão, selecione URL do app e cole na caixa o URL do acionador da Função do Cloud.
6. Em Visibilidade, selecione Disponibilizar este app do Google Chat para pessoas e grupos específicos no domínio e digite seu endereço de e-mail.
7. Em Registros, selecione Registrar erros no Logging.
Clique em Salvar.

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

Testar seu app do Chat

Para testar o app do Chat, envie uma mensagem direta ao app:

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 Find apps, pesquise por Quickstart App.
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.

A resposta do app do Chat contém uma mensagem de cartão que exibe o nome do remetente e a imagem de avatar, conforme demonstrado na imagem a seguir:

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

Solucionar erros

Para resolver problemas e depurar seu app do Chat, consulte Resolver problemas e corrigir erros no app Google Chat.

Temas relacionados

Para adicionar mais recursos ao app do Chat, consulte o seguinte:
Escolher uma arquitetura de app do Chat