Compila una app HTTP de Google Chat

En esta página, se explica cómo compilar un complemento de Google Workspace que funcione en Google Chat con un servicio HTTP.

En esta guía de inicio rápido, se muestra cómo compilar un servicio HTTP con los servicios de Google Cloud. Para compilar la app de Chat, escribirás e implementarás una función de Cloud Run que la app de Chat usará para responder al mensaje de un usuario.

Con una arquitectura HTTP, puedes configurar Chat para que se integre con Google Cloud o un servidor local a través de HTTP, como se muestra en el siguiente diagrama:

Arquitectura de una app de Chat que usa un servicio web en un servidor local.

En el diagrama anterior, un usuario que interactúa con una app de chat HTTP tiene el siguiente flujo de información:

  1. Un usuario envía un mensaje en Chat a una app de Chat, ya sea en un mensaje directo o en un espacio de Chat.
  2. Se envía una solicitud HTTP a un servidor web que es un sistema en la nube o local que contiene la lógica de la app de Chat.
  3. De manera opcional, la lógica de la app de Chat puede integrarse con los servicios de Google Workspace (como Calendar y Hojas de cálculo), otros servicios de Google (como Maps, YouTube y Vertex AI) o con otros servicios web (como un sistema de administración de proyectos o una herramienta de tickets).
  4. El servidor web envía una respuesta HTTP al servicio de la app de Chat en Chat.
  5. La respuesta se entrega al usuario.
  6. De manera opcional, la app de Chat puede llamar a la API de Chat para publicar mensajes de forma asíncrona o realizar otras operaciones.

Esta arquitectura te brinda la flexibilidad de usar bibliotecas y componentes existentes que ya se encuentran en tu sistema, ya que estas apps de chat se pueden diseñar con diferentes lenguajes de programación.

Objetivos

  • Configura el entorno.
  • Crea e implementa una función de Cloud Run.
  • Configura un complemento de Google Workspace para la app de Chat.
  • Prueba la app.

Requisitos previos

Configura el entorno

Antes de usar las APIs de Google, debes activarlas en un proyecto de Google Cloud. Puedes activar una o más APIs en un solo proyecto de Google Cloud.

  • En la consola de Google Cloud, habilita las APIs de Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry y Cloud Run.

    Habilitar las API

Crea e implementa una función de Cloud Run

Crea e implementa una función de Cloud Run que genere una tarjeta de chat con el nombre visible y la imagen de avatar del remitente. Cuando la app de Chat recibe un mensaje, ejecuta la función y responde con la tarjeta.

Para crear e implementar la función de tu app de Chat, completa los siguientes pasos:

Node.js

  1. En la consola de Google Cloud, ve a la página Cloud Run:

    Ir a Cloud Run

    Asegúrate de que esté seleccionado el proyecto de tu app de Chat.

  2. Haz clic en Escribe una función.

  3. En la página Crear servicio, configura tu función:

    1. En el campo Nombre del servicio, ingresa addonchatapp.
    2. En la lista Región, selecciona una región.
    3. En la lista Entorno de ejecución, selecciona la versión más reciente de Node.js.
    4. En la sección Autenticación, selecciona Autenticación obligatoria.
    5. Haz clic en Crear y espera a que Cloud Run cree el servicio. La consola te redireccionará a la pestaña Fuente.

  4. En la pestaña Fuente, haz lo siguiente:

    1. En Punto de entrada, borra el texto predeterminado y, luego, ingresa avatarApp.
    2. Reemplaza el contenido de index.js con el código que se muestra a continuación:
    node/chat/avatar-app/index.js
    import { http } from '@google-cloud/functions-framework';

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleMessage(event) {
  // Stores the Google Chat user as a variable.
  const chatUser = event.messagePayload.message.sender;
  const displayName = chatUser.displayName;
  const avatarUrl = chatUser.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 }
        }]}]
      }
    }]
  };
}
    1. Haz clic en Guardar y volver a implementar.

Python

  1. En la consola de Google Cloud, ve a la página Cloud Run:

    Ir a Cloud Run

    Asegúrate de que esté seleccionado el proyecto de tu app de Chat.

  2. Haz clic en Escribe una función.

  3. En la página Crear servicio, configura tu función:

    1. En el campo Nombre del servicio, ingresa addonchatapp.
    2. En la lista Región, selecciona una región.
    3. En la lista Entorno de ejecución, selecciona la versión más reciente de Python.
    4. En la sección Autenticación, selecciona Autenticación obligatoria.
    5. Haz clic en Crear y espera a que Cloud Run cree el servicio. La consola te redireccionará a la pestaña Fuente.

  4. En la pestaña Fuente, haz lo siguiente:

    1. En Punto de entrada, borra el texto predeterminado y, luego, ingresa avatar_app.
    2. Reemplaza el contenido de main.py con el código que se muestra a continuación:
    python/chat/avatar-app/main.py
    from typing import Any, Mapping

import flask
import functions_framework

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

def handle_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  # Stores the Google Chat user as a variable.
  chat_user = event["messagePayload"]["message"]["sender"]
  display_name = chat_user.get("displayName", "")
  avatar_url = chat_user.get("avatarUrl", "")
  return {
    "text": "Here's your avatar",
    "cardsV2": [{
      "cardId": "avatarCard",
      "card": {
        "name": "Avatar Card",
        "header": {
          "title": f"Hello {display_name}!"
        },
        "sections": [{ "widgets": [
          { "textParagraph": { "text": "Your avatar picture:" }},
          { "image": { "imageUrl": avatar_url }},
        ]}]
      }
    }]
  }
    1. Haz clic en Guardar y volver a implementar.

Java

  1. En la consola de Google Cloud, ve a la página Cloud Run:

    Ir a Cloud Run

    Asegúrate de que esté seleccionado el proyecto de tu app de Chat.

  2. Haz clic en Escribe una función.

  3. En la página Crear servicio, configura tu función:

    1. En el campo Nombre del servicio, ingresa addonchatapp.
    2. En la lista Región, selecciona una región.
    3. En la lista Entorno de ejecución, selecciona la versión más reciente de Java.
    4. En la sección Autenticación, selecciona Autenticación obligatoria.
    5. Haz clic en Crear y espera a que Cloud Run cree el servicio. La consola te redireccionará a la pestaña Fuente.

  4. En la pestaña Fuente, haz lo siguiente:

    1. En Punto de entrada, borra el texto predeterminado y, luego, ingresa App.
    2. Cambia el nombre del archivo Java predeterminado a src/main/java/com/google/chat/avatar/App.java.
    3. Reemplaza el contenido de App.java con el código que se muestra a continuación:
    java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java
    package com.google.chat.avatar;

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 App implements HttpFunction {
  // The ID of the slash command "/about".
  // You must use the same ID in the Google Chat API configuration.
  private static final int ABOUT_COMMAND_ID = 1;

  private static final Gson gson = new Gson();

  /**
   * Handle requests from Google Workspace add on
   * 
   * @param request the request sent by Google Chat
   * @param response the response to be sent back to Google Chat
   */
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
    JsonObject chatEvent = event.getAsJsonObject("chat");
    Message message;
    if (chatEvent.has("appCommandPayload")) {
      message = handleAppCommand(chatEvent);
    } else {
      message = handleMessage(chatEvent);
    }
    JsonObject createMessageAction = new JsonObject();
    createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
    JsonObject chatDataAction = new JsonObject();
    chatDataAction.add("createMessageAction", createMessageAction);
    JsonObject hostAppDataAction = new JsonObject();
    hostAppDataAction.add("chatDataAction", chatDataAction);
    JsonObject dataActions = new JsonObject();
    dataActions.add("hostAppDataAction", hostAppDataAction);
    response.getWriter().write(gson.toJson(dataActions));
  }

  /**
   * Handles an APP_COMMAND event in Google Chat.
   *
   * @param event the event object from Google Chat
   * @return the response message object.
   */
  private Message handleAppCommand(JsonObject event) throws Exception {
    switch (event.getAsJsonObject("appCommandPayload")
      .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
      case ABOUT_COMMAND_ID:
        return new Message()
          .setText("The Avatar app replies to Google Chat messages.");
      default:
        return null;
    }
  }

  /**
   * Handles a MESSAGE event in Google Chat.
   *
   * @param event the event object from Google Chat
   * @return the response message object.
   */
  private Message handleMessage(JsonObject event) throws Exception {
    // Stores the Google Chat user as a variable.
    JsonObject chatUser = event.getAsJsonObject("messagePayload").getAsJsonObject("message").getAsJsonObject("sender");
    String displayName = chatUser.has("displayName") ? chatUser.get("displayName").getAsString() : "";
    String avatarUrl = chatUser.has("avatarUrl") ? chatUser.get("avatarUrl").getAsString() : "";
    return new Message()
      .setText("Here's your avatar")
      .setCardsV2(List.of(new CardWithId()
        .setCardId("avatarCard")
        .setCard(new GoogleAppsCardV1Card()
          .setName("Avatar Card")
          .setHeader(new GoogleAppsCardV1CardHeader()
            .setTitle(String.format("Hello %s!", displayName)))
          .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
            new GoogleAppsCardV1Widget().setTextParagraph(new GoogleAppsCardV1TextParagraph()
              .setText("Your avatar picture:")),
            new GoogleAppsCardV1Widget()
              .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
  }
}

  5. Reemplaza el contenido de pom.xml con el código que se muestra a continuación:

    java/chat/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.1.4</version>
    </dependency>
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.9.1</version>
    </dependency>
    <dependency>
      <groupId>com.google.apis</groupId>
      <artifactId>google-api-services-chat</artifactId>
      <version>v1-rev20230115-2.0.0</version>
    </dependency>
  </dependencies>

  <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>
    1. Haz clic en Guardar y volver a implementar.

Se abrirá la página de detalles del servicio de Cloud Run. Espera a que se implemente la función.

Configura el complemento

Después de implementar la función de Cloud Run, sigue estos pasos para crear un complemento y, luego, implementar la app de Google Chat:

  1. En la consola de Google Cloud, ve a la página Cloud Run:

    Ir a Cloud Run

    Asegúrate de que el proyecto para el que habilitaste Cloud Run esté seleccionado.

  2. En la lista de funciones, haz clic en addonchatapp.

  3. En la página Detalles del servicio, copia la URL de la función. La URL termina en run.app.

  4. En el campo de búsqueda de Google Cloud, busca “API de Google Chat”, luego haz clic en API de Google Chat y, luego, en Administrar.

    Ir a la API de Chat

  5. Haz clic en Configuración y configura la app de Google Chat:

    1. En Nombre de la app, ingresa Add-on Chat app.
    2. En URL del avatar, ingresa https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
    3. En Descripción, ingresa Add-on Chat app.
    4. En Funcionalidad, selecciona Unirse a espacios y conversaciones grupales.
    5. En Configuración de la conexión, selecciona URL del extremo HTTP.
    6. Copia el correo electrónico de la cuenta de servicio. Necesitas este correo electrónico cuando autorizas a tu complemento para que invoque tu función.
    7. En Activadores, selecciona Usar una URL de extremo HTTP común para todos los activadores y pega la URL del activador de la función de Cloud Run en el cuadro.
    8. En Visibilidad, selecciona Hacer que esta app de Google Chat esté disponible para personas y grupos específicos de tu dominio y escribe tu dirección de correo electrónico.
    9. En Registros, selecciona Registrar errores en Logging.

  6. Haz clic en Guardar.

A continuación, autoriza la app de Chat para invocar la función de Cloud Run.

Autoriza a Google Chat para invocar tu función

Para autorizar el complemento de Google Workspace a invocar tu función, agrega la cuenta de servicio del complemento de Google Workspace con el rol de Invocador del servicio de Cloud Run.

  1. En la consola de Google Cloud, ve a la página Cloud Run:

    Ir a Cloud Run

  2. En la lista de servicios de Cloud Run, selecciona la casilla de verificación junto a la función receptora. (No hagas clic en la función).

  3. Haz clic en Permisos. Se abrirá el panel Permisos.

  4. Haz clic en Agregar principal.

  5. En Principales nuevas, ingresa la dirección de correo electrónico de la cuenta de servicio del complemento de Google Workspace asociada a tu app de Chat.

    La dirección de correo electrónico de la cuenta de servicio se encuentra en la página de configuración de la API de Chat, en Configuración de conexión > URL del extremo HTTP > Correo electrónico de la cuenta de servicio:

    Ir a la configuración de la API de Chat

  6. En Selecciona un rol, selecciona Cloud Run > Invocador del servicio de Cloud Run.

  7. Haz clic en Guardar.

La app de Chat está lista para recibir y responder mensajes en Chat.

Prueba tu app de Chat

Para probar tu app de Chat, abre un espacio de mensajes directos con la app de Chat y envía un mensaje:

  1. Abre Google Chat con la cuenta de Google Workspace que proporcionaste cuando te agregaste como verificador de confianza.

    Ir a Google Chat

  2. Haz clic en Nuevo chat.
  3. En el campo Agrega 1 o más personas, escribe el nombre de tu app de Chat.

  4. Selecciona tu app de Chat en los resultados. Se abrirá un mensaje directo.

  5. En el nuevo mensaje directo con la app, escribe Hello y presiona enter.

El mensaje de la app de Chat contiene una tarjeta que muestra el nombre y la imagen de avatar del remitente, como se muestra en la siguiente imagen:

App de chat que responde con una tarjeta en la que se muestran el nombre visible y la imagen de avatar del remitente

Para agregar verificadores de confianza y obtener más información sobre las pruebas de funciones interactivas, consulta Cómo probar funciones interactivas para apps de Google Chat.

Solucionar problemas

Cuando una app o una tarjeta de Google Chat muestra un error, la interfaz de Chat muestra un mensaje que dice "Se produjo un error". o "No se pudo procesar tu solicitud". A veces, la IU de Chat no muestra ningún mensaje de error, pero la app o la tarjeta de Chat producen un resultado inesperado. Por ejemplo, es posible que no aparezca un mensaje de la tarjeta.

Si bien es posible que no se muestre un mensaje de error en la IU de Chat, hay mensajes de error descriptivos y datos de registro disponibles para ayudarte a corregir errores cuando se activa el registro de errores para las apps de Chat. Para obtener ayuda para ver, depurar y corregir errores, consulta Soluciona y corrige errores de Google Chat.

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este instructivo, te recomendamos que borres el proyecto de Cloud.

  1. En la consola de Google Cloud, ve a la página Administrar recursos. Haz clic en Menú > IAM y administración > Administrar recursos.

    Ir al administrador de recursos

  2. En la lista de proyectos, selecciona el proyecto que deseas borrar y haz clic en Borrar .
  3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrarlo.