Criar um app HTTP do Google Chat

Nesta página, explicamos como criar um app de chat HTTP. Há maneiras diferentes de implementar essa arquitetura. No Google Cloud, pode usar o Cloud Functions, o Cloud Run e o App Engine. Neste guia de início rápido, gravar e implantar um Função do Cloud que o app do Chat usa para responder à mensagem de um usuário.

Com esta arquitetura, você configura o Chat para integração Google Cloud ou um servidor local usando HTTP, conforme diagrama a seguir:

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

No diagrama anterior, um usuário interagindo com uma interface HTTP O app do Chat tem o seguinte fluxo de informações:

  1. Um usuário envia uma mensagem no Chat para App do Chat, seja em mensagem direta ou em uma Espaço do Chat.
  2. Uma solicitação HTTP é enviada para um servidor da Web que é uma nuvem ou sistema local que contém o app do Chat lógica.
  3. Opcionalmente, a lógica do app do Chat pode se integrar 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 projeto sistema de gerenciamento de projetos ou ferramenta de tiquetagem).
  4. O servidor da Web envia uma resposta HTTP Serviço de app do Chat no Chat.
  5. A resposta é entregue ao usuário.
  6. Opcionalmente, o app do Chat pode chamar a função a API Chat para postar mensagens de forma assíncrona ou realizar outras as operações.

Essa arquitetura oferece flexibilidade para usar bibliotecas e recursos componentes que já existem no sistema, porque eles Os apps de chat podem ser projetados com diferentes linguagens de programação.

Objetivos

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

Pré-requisitos

Configure 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 e Cloud Functions. API Cloud Pub/Sub, API Cloud Logging, API Artifact Registry e API Cloud Run.

    Ativar as APIs

Crie e implemente uma Função do Cloud

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

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

Node.js

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

    Acesse o Cloud Functions

    Verifique se o projeto do app de chat está selecionado.

  2. Clique em Criar função.

  3. Na página "Criar função", configure sua função:

    1. Em Ambiente, selecione 2ª geração.
    2. Em Nome da função, insira QuickStartChatApp.
    3. Em Região, selecione uma região.
    4. Em "Autenticação", selecione Exigir autenticação.
    5. Clique em Próxima.
  4. Em Ambiente de execução, selecione a versão mais recente do Node.js.

  5. Em Código-fonte, selecione Editor in-line.

  6. Em Ponto de entrada, exclua o texto padrão e insira avatarApp.

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

    node/avatar-app/index.js
    // The ID of the slash command "/about".
    // It's not enabled by default, set to the actual ID to enable it. You need to
    // use the same ID as set in the Google Chat API configuration.
    const ABOUT_COMMAND_ID = "";
    
    /**
     * Google Cloud Function that responds to messages sent from a
     * Google Chat space.
     *
     * @param {Object} req Request sent from Google Chat space
     * @param {Object} res Response to send back
     */
    exports.avatarApp = function avatarApp(req, res) {
      if (req.method === 'GET' || !req.body.message) {
        return res.send('Hello! This function is meant to be used ' +
          'in a Google Chat Space.');
      }
    
      // Stores the Google Chat event as a variable.
      const event = req.body;
    
      // Checks for the presence of a slash command in the message.
      if (event.message.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (event.message.slashCommand.commandId) {
          case ABOUT_COMMAND_ID:
            return res.send({
              privateMessageViewer: event.user,
              text: 'The Avatar app replies to Google Chat messages.'
            });
        }
      }
    
      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} avatarUrl the URL for the sender's avatar
     * @return {Object} a card with the user's avatar.
     */
    function createMessage(displayName, avatarUrl) {
      return {
        text: 'Here\'s your avatar',
        cardsV2: [{
          cardId: 'avatarCard',
          card: {
            name: 'Avatar Card',
            header: {
              title: `Hello ${displayName}!`,
            },
            sections: [{ widgets: [{
              textParagraph: { text: 'Your avatar picture: ' }
            }, {
              image: { imageUrl: avatarUrl }
            }]}]
          }
        }]
      };
    }

  8. Clique em Implantar.

Python

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

    Acesse o Cloud Functions

    Verifique se o projeto do app de chat está selecionado.

  2. Clique em Criar função.

  3. Na página "Criar função", configure sua função:

    1. Em Ambiente, selecione 2ª geração.
    2. Em Nome da função, insira QuickStartChatApp.
    3. Em Região, selecione uma região.
    4. Em "Autenticação", selecione Exigir autenticação.
    5. Clique em Próxima.
  4. Em Ambiente de execução, selecione a versão mais recente do Python.

  5. Em Código-fonte, selecione Editor in-line.

  6. Em Ponto de entrada, exclua o texto padrão e digite avatar_app.

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

    python/avatar-app/main.py
    from typing import Any, Mapping
    
    import flask
    import functions_framework
    
    # The ID of the slash command "/about".
    # It's not enabled by default, set to the actual ID to enable it. You need to
    # use the same ID as set in the Google Chat API configuration.
    ABOUT_COMMAND_ID = ""
    
    @functions_framework.http
    def avatar_app(req: flask.Request) -> Mapping[str, Any]:
      """Google Cloud Function that handles requests from Google Chat
    
      Args:
          flask.Request: the request
    
      Returns:
          Mapping[str, Any]: the response
      """
      if req.method == "GET":
        return "Hello! This function must be called from Google Chat."
    
      request_json = req.get_json(silent=True)
    
      # Checks for the presence of a slash command in the message.
      if "slashCommand" in request_json["message"]:
        # Executes the slash command logic based on its ID.
        # Slash command IDs are set in the Google Chat API configuration.
        if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
          return {
            "privateMessageViewer": request_json["user"],
            "text": 'The Avatar app replies to Google Chat messages.'
          }
    
      display_name = request_json["message"]["sender"]["displayName"]
      avatar = request_json["message"]["sender"]["avatarUrl"]
      response = create_message(name=display_name, image_url=avatar)
      return response
    
    
    def create_message(name: str, image_url: str) -> Mapping[str, Any]:
      """Google Cloud Function that handles requests from Google Chat
    
      Args:
          str name: the sender's display name.
          str image_url: the URL for the sender's avatar.
    
      Returns:
          Mapping[str, Any]: a card with the user's avatar.
      """
      return {
        "text": "Here's your avatar",
        "cardsV2": [{
          "cardId": "avatarCard",
          "card": {
              "name": "Avatar Card",
              "header": { "title": f"Hello {name}!" },
              "sections": [{
                "widgets": [{
                  "textParagraph": { "text": "Your avatar picture:" }
                }, {
                  "image": { "imageUrl": image_url }
                }]
              }]
          }
        }]
      }

  8. Clique em Implantar.

Java

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

    Acesse o Cloud Functions

    Verifique se o projeto do seu app do Chat está selecionados.

  2. Clique em Criar função.

  3. Na página "Criar função", configure sua função:

    1. Em Ambiente, selecione 2ª geração.
    2. Em Nome da função, insira QuickStartChatApp.
    3. Em Região, selecione uma região.
    4. Em "Autenticação", selecione Exigir autenticação.
    5. Clique em Próxima.
  4. Em Ambiente de execução, selecione a versão mais recente do Java.

  5. Em Código-fonte, selecione Editor in-line.

  6. Em Ponto de entrada, exclua o texto padrão e insira App.

  7. O src/main/java/com/example/Example.java foi renomeado como src/main/java/App.java.

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

    java/avatar-app/src/main/java/App.java
    import java.util.List;
    
    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;
    
    public class App implements HttpFunction {
      private static final Gson gson = new Gson();
    
      // The ID of the slash command "/about".
      // It's not enabled by default, set to the actual ID to enable it. You need to
      // use the same ID as set in the Google Chat API configuration.
      private static final String ABOUT_COMMAND_ID = "";
    
      @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;
        }
    
        // Checks for the presence of a slash command in the message.
        if (body.getAsJsonObject("message").has("slashCommand")) {
          // Executes the slash command logic based on its ID.
          // Slash command IDs are set in the Google Chat API configuration.
          JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
          switch (slashCommand.get("commandId").getAsString()) {
            case ABOUT_COMMAND_ID:
            JsonObject aboutMessage = new JsonObject();
            aboutMessage.addProperty("text", "The Avatar app replies to Google Chat messages.");
            aboutMessage.add("privateMessageViewer", body.getAsJsonObject("user"));
              response.getWriter().write(gson.toJson(aboutMessage));
              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;
      }
    }

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

    java/avatar-app/pom.xml
    <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>com.google.chat</groupId>
      <artifactId>avatar-app</artifactId>
      <version>1.0-SNAPSHOT</version>
    
      <properties>
        <maven.compiler.target>17</maven.compiler.target>
        <maven.compiler.source>17</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>

  10. 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 serão substituídos por uma marca de seleção, sua função está implantado e pronto.

Autorizar o Google Chat a invocar sua função

Para autorizar o Google Chat a invocar sua função, adicione a API conta de serviço com o papel Invocador do Cloud Run.

  1. No console do Google Cloud, acesse a página do Cloud Run:

    Acessar o Cloud Run

  2. Na lista de serviços do Cloud Run, marque a caixa de seleção ao lado da função de recebimento. (Não clique na função em si.)

  3. Clique em Permissões. O painel Permissões será aberto.

  4. Clique em Adicionar principal.

  5. Em Novos principais, digite chat@system.gserviceaccount.com.

  6. Em Selecionar papel, escolha Cloud Run > Invocador do Cloud Run.

  7. Clique em Salvar.

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:

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

    Acesse o Cloud Functions

    Verifique se o projeto para que você ativou o Cloud Functions está selecionado.

  2. Na lista de funções, clique em QuickStartChatApp.

  3. Clique na guia Gatilhos.

  4. Em HTTPS, copie o URL.

  5. Pesquise "API Google Chat" Clique em API Google Chat e em Gerenciar.

    Acessar a API Chat

  6. Clique em Configuração e configure o app Google Chat:

    1. Em Nome do app, digite Quickstart App.
    2. No URL do avatar, digite https://developers.google.com/chat/images/quickstart-app-avatar.png.
    3. Em Descrição, insira 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 endpoint HTTP e cole o URL do gatilho da função do Cloud na caixa.
    6. Em Segmento de autenticação, selecione URL do endpoint HTTP.
    7. Em Visibilidade, selecione Disponibilizar este app do Google Chat para pessoas e grupos no seu domínio e digite o endereço de e-mail.
    8. Em Registros, selecione Registrar erros no Logging.
  7. Clique em Salvar.

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

Testar o app Chat

Para testar o app do Chat, abra um espaço de mensagem direta com o app e envie uma mensagem:

  1. Abra o Google Chat usando a conta do Google Workspace que você fornecido quando você se adicionou como trusted tester.

    Acessar o Google Chat

  2. Clique em Nova conversa.
  3. No campo Adicionar uma ou mais pessoas, digite o nome da sua App Chat.
  4. Selecione seu app do Chat nos resultados. Uma mensagem direta é aberta.

  5. Na nova mensagem direta com o app, digite Hello e pressione enter.

A resposta do app Chat contém uma mensagem em card que mostra o nome e a imagem do avatar do remetente, conforme demonstrado na imagem a seguir:

App de chat respondendo com uma ficha de informações que mostra o nome de exibição e a imagem
do avatar do remetente

Para adicionar trusted testers e saber mais sobre como testar recursos interativos, consulte Teste os recursos interativos do Apps do Google Chat

Resolver problemas

Quando um app ou card retornar um erro, o A interface do chat mostra a mensagem "Algo deu errado". ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não exibe nenhuma mensagem de erro, mas o app do Chat ou produz um resultado inesperado; por exemplo, uma mensagem de cartão pode não aparecer.

Embora uma mensagem de erro possa não aparecer na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar a corrigir erros quando o registro de erros para apps de chat estiver ativado. Para receber ajuda com a visualização, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelo recursos usados neste tutorial, recomendamos que você exclua os do Google Cloud.

  1. No console do Google Cloud, acesse a página Gerenciar recursos. Clique em Cardápio &gt; IAM e Administrador &gt; Gerenciar recursos.

    Acessar o Resource Manager

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
  3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluir o projeto.