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:

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

1. Um usuário envia uma mensagem no Chat para um app do Chat, seja em uma mensagem direta ou em um espaço do Chat.
2. Uma solicitação HTTP é enviada para um servidor da Web que é um sistema em nuvem ou local que contém a lógica do app do Chat.
3. Opcionalmente, a lógica do app Chat pode se integrar 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 venda de ingressos).
4. O servidor da Web envia uma resposta HTTP de volta ao serviço do app do Chat no Chat.
5. A resposta é entregue ao usuário.
6. 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 a flexibilidade de usar bibliotecas e componentes que já existem no sistema, já que esses apps do Chat podem ser projetados com diferentes linguagens de programação.

Objetivos

• Configurar o ambiente.
• Criar e implantar 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 de seus projetos.

configurar o ambiente

Antes de usar as APIs do Google, é preciso 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, 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 card.

Para criar e implantar a função do seu app do Chat, siga estas etapas:

Node.js

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

2. Clique em Criar função.

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

   1. Em Ambiente, selecione 2a geração.
   2. Em Nome da função, insira QuickStartChatApp.
   3. Em Região, selecione uma região.
   4. Em "Autenticação", selecione Permitir invocações não autenticadas.
   5. Clique em Próxima.

4. Em Ambiente de execução, selecione Node.js 20.

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

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

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

   node/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],
         }
       }],
     };
   }

8. Selecione Implantar.

Python

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

2. Clique em Criar função.

3. Na página "Criar função", configure a 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 Próxima.

4. Em Ambiente de execução, selecione Python 3.10.

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

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

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

8. Selecione Implantar.

Java

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

2. Clique em Criar função.

3. Na página "Criar função", configure a 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 Próxima.

4. Em Ambiente de execução, selecione Java 11.

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

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

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

8. 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;
     }
   }

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

10. Selecione Implantar.

A página de detalhes do Cloud Functions é aberta e sua função aparece com dois indicadores de progresso: um para a versão e outro para o serviço. Quando os dois indicadores de progresso desaparecem e são substituídos por uma marca de seleção, a função está implantada e pronta.

Publicar o app no Google Chat

Depois que o Cloud Function for implantado, siga estas etapas para transformá-lo 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 em 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, 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 seu domínio e digite seu endereço de e-mail.
   7. 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 do Chat

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

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

   Acessar o Google Chat

2. Clique em Novo chat.
3. No campo Adicionar uma ou mais pessoas, digite o nome do seu app do Chat.

4. Selecione o app do Chat nos resultados. Uma mensagem direta será aberta.

   Observação:se o app do Chat não estiver na lista de resultados, verifique se você incluiu sua conta do Google Workspace nas configurações Visibilidade da página Configuração da API Chat no console do Google Cloud.
5. Na nova mensagem direta com o app, digite Hello e pressione enter.

A resposta do app de chat contém uma mensagem em ficha de informações que exibe o nome do remetente e a imagem de avatar, conforme demonstrado na seguinte imagem:

Para adicionar trusted testers e saber mais sobre como testar recursos interativos, consulte Testar recursos interativos de apps do Google Chat.

Resolver problemas

Quando um app ou card do Google Chat retorna um erro, a interface do Chat mostra a mensagem "Ocorreu um erro" ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não mostra nenhuma mensagem de erro, mas o app ou card do Chat produz um resultado inesperado. Por exemplo, uma mensagem de card pode não aparecer.

Embora uma mensagem de erro não apareça 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 dos apps do Chat está ativado. Se precisar de ajuda para visualizar, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.

Limpar

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

Cuidado:excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para seguir este tutorial, a exclusão dele incluirá quaisquer outras ações feitas no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL em appspot.com, exclua os recursos selecionados dentro do projeto em vez de excluir o projeto inteiro.

Se você planeja conferir vários tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

1. No Console do Google Cloud, acesse a página Gerenciar recursos. Clique em Menu > IAM e administrador > 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 excluí-lo.

Temas relacionados

• Para adicionar mais recursos ao app do Chat, consulte:

  • Criar mensagens interativas no card
  • Responder a comandos de barra
  • Abrir e responder a caixas de diálogo

• Escolher uma arquitetura para o app do Chat