Creare un'app Google Chat HTTP

Questa pagina spiega come creare un componente aggiuntivo di Google Workspace che funzioni in Google Chat utilizzando un servizio HTTP. In Google Chat, i componenti aggiuntivi vengono visualizzati dagli utenti come app Google Chat. Per saperne di più, consulta la panoramica di Estensione di Google Chat.

Questa guida rapida mostra come creare un servizio HTTP utilizzando i servizi Google Cloud. Per creare l'app Chat, scrivi ed esegui il deployment di una funzione Cloud che l'app Chat utilizza per rispondere al messaggio di un utente.

Con un'architettura HTTP, configuri Chat per l'integrazione con Google Cloud o un server on-premise utilizzando HTTP, come mostrato nel seguente diagramma:

Architettura di un'app di Chat che utilizza un servizio web in un server on-premise.

Nel diagramma precedente, un utente che interagisce con un'app HTTP Chat ha il seguente flusso di informazioni:

  1. Un utente invia un messaggio in Chat a un'app Chat, in un messaggio diretto o in uno spazio Chat.
  2. Una richiesta HTTP viene inviata a un server web che è un sistema cloud o on-premise contenente la logica dell'app Chat.
  3. Se vuoi, la logica dell'app Chat può essere integrata con i servizi Google Workspace (come Calendar e Fogli), con altri servizi Google (come Maps, YouTube e Vertex AI) o con altri servizi web (come un sistema di gestione dei progetti o uno strumento per la gestione dei ticket).
  4. Il server web invia una risposta HTTP al servizio dell'app Chat in Chat.
  5. La risposta viene inviata all'utente.
  6. Se vuoi, l'app Chat può chiamare l'API Chat per pubblicare messaggi in modo asincrono o eseguire altre operazioni.

Questa architettura ti offre la flessibilità di utilizzare librerie e componenti esistenti nel tuo sistema perché queste app di chat possono essere progettate utilizzando diversi linguaggi di programmazione.

Obiettivi

  • Configurare l'ambiente.
  • Crea ed esegui il deployment di una funzione Cloud.
  • Configura un componente aggiuntivo di Google Workspace per l'app Chat.
  • Testa l'app.

Prerequisiti

Configurare l'ambiente

Prima di utilizzare le API Google, devi attivarle in un progetto Google Cloud. Puoi attivare una o più API in un singolo progetto Google Cloud.

  • Nella console Google Cloud, abilita l'API Google Chat, l'API Cloud Build, l'API Cloud Functions, l'API Cloud Pub/Sub, l'API Cloud Logging, l'API Artifact Registry e l'API Cloud Run.

    Abilita le API

Crea ed esegui il deployment di una funzione Cloud

Crea ed esegui il deployment di una funzione Cloud che genera una scheda di Chat con il nome visualizzato e l'immagine dell'avatar del mittente. Quando l'app Chat riceve un messaggio, esegue la funzione e risponde con la scheda.

Per creare ed eseguire il deployment della funzione per la tua app di chat, completa i seguenti passaggi:

Node.js

  1. Nella console Google Cloud, vai alla pagina Cloud Functions:

    Vai a Cloud Functions

    Assicurati che il progetto per l'app Chat sia selezionato.

  2. Fai clic su Crea funzione.

  3. Nella pagina Crea funzione, configura la funzione:

    1. In Ambiente, seleziona Funzione Cloud Run.
    2. In Nome funzione, inserisci AddOnChatApp.
    3. In Regione, seleziona una regione.
    4. In Autenticazione, seleziona Richiedi l'autenticazione.
    5. Fai clic su Avanti.

  4. In Runtime, seleziona la versione più recente di Node.js.

  5. In Codice sorgente, seleziona Editor incorporato.

  6. In Punto di contatto, elimina il testo predefinito e inserisci avatarApp.

  7. Sostituisci i contenuti di index.js con il seguente codice:

    /**
 * 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.chat) {
        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 chatMessage = req.body.chat.messagePayload.message;

    // Replies with the sender's avatar in a card.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        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. Fai clic su Esegui il deployment.

Python

  1. Nella console Google Cloud, vai alla pagina Cloud Functions:

    Vai a Cloud Functions

    Assicurati che il progetto per l'app Chat sia selezionato.

  2. Fai clic su Crea funzione.

  3. Nella pagina Crea funzione, configura la funzione:

    1. In Ambiente, seleziona Funzione Cloud Run.
    2. In Nome funzione, inserisci AddOnChatApp.
    3. In Regione, seleziona una regione.
    4. In Autenticazione, seleziona Richiedi l'autenticazione.
    5. Fai clic su Avanti.

  4. In Runtime, seleziona la versione più recente di Python.

  5. In Codice sorgente, seleziona Editor incorporato.

  6. In Punto di contatto, elimina il testo predefinito e inserisci avatar_app.

  7. Sostituisci i contenuti di main.py con il seguente codice:

    from typing import Any, Mapping

import flask
import functions_framework

@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)

    # Stores the Google Chat event as a variable.
    chat_message = request_json["chat"]["messagePayload"]["message"]

    # Replies with the sender's avatar in a card.
    display_name = chat_message["sender"]["displayName"]
    avatar_url = chat_message["sender"]["avatarUrl"]
    return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
        "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 }
                    }]
                }]
            }
        }]
    }}}}}

  8. Fai clic su Esegui il deployment.

Java

  1. Nella console Google Cloud, vai alla pagina Cloud Functions:

    Vai a Cloud Functions

    Assicurati che il progetto per l'app Chat sia selezionato.

  2. Fai clic su Crea funzione.

  3. Nella pagina Crea funzione, configura la funzione:

    1. In Ambiente, seleziona Funzione Cloud Run.
    2. In Nome funzione, inserisci AddOnChatApp.
    3. In Regione, seleziona una regione.
    4. In Autenticazione, seleziona Richiedi l'autenticazione.
    5. Fai clic su Avanti.

  4. In Runtime, seleziona la versione più recente di Java.

  5. In Codice sorgente, seleziona Editor incorporato.

  6. In Punto di contatto, elimina il testo predefinito e inserisci AvatarApp.

  7. Rinomina il file Java predefinito in src/main/java/AvatarApp.java.

  8. Sostituisci i contenuti di AvatarApp.java con il seguente codice:

    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 AvatarApp 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("chat")) {
            response.getWriter().write("Hello! This function is meant to be used " +
                "in a Google Chat Space..");
            return;
        }

        // Stores the Google Chat event as a variable.
        JsonObject chatMessage = body.getAsJsonObject("chat")
            .getAsJsonObject("messagePayload").getAsJsonObject("message");

        // Replies with the sender's avatar in a card.
        String displayName = chatMessage.getAsJsonObject("sender").get("displayName").getAsString();
        String avatarUrl = chatMessage.getAsJsonObject("sender").get("avatarUrl").getAsString();
        Message message = createMessage(displayName, avatarUrl);

        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));
    }

    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("avatarCard");
        cardWithId.setCard(card);

        Message message = new Message();
        message.setText("Here's your avatar");
        message.setCardsV2(List.of(cardWithId));

        return message;
    }
}

  9. Sostituisci i contenuti di pom.xml con il seguente codice:

    <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.4</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 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. Fai clic su Esegui il deployment.

Si apre la pagina dei dettagli di Cloud Functions e la funzione viene visualizzata con due indicatori di avanzamento: uno per la compilazione e uno per il servizio. Quando entrambi gli indicatori di avanzamento scompaiono e vengono sostituiti da un segno di spunta, la funzione è dispiattata e pronta.

Autorizza Google Chat a richiamare la funzione

Per autorizzare il componente aggiuntivo Google Workspace a invocare la funzione, aggiungi l'account di servizio del componente aggiuntivo Google Workspace con il ruolo Cloud Run Invoker.

  1. Nella console Google Cloud, vai alla pagina Cloud Run:

    Vai a Cloud Run

  2. Nell'elenco dei servizi Cloud Run, seleziona la casella di controllo accanto alla funzione di ricezione. Non fare clic sulla funzione stessa.

  3. Fai clic su Autorizzazioni. Viene visualizzato il riquadro Autorizzazioni.

  4. Fai clic su Aggiungi entità.

  5. In Nuove entità, inserisci l'indirizzo email dell'account di servizio del componente aggiuntivo Google Workspace associato al tuo progetto.

  6. In Seleziona un ruolo, seleziona Cloud Run > Cloud Run Invoker.

  7. Fai clic su Salva.

Configurare il componente aggiuntivo

Dopo aver eseguito il deployment della funzione Cloud, segui questi passaggi per creare un componente aggiuntivo ed eseguire il deployment dell'app Google Chat:

  1. Nella console Google Cloud, fai clic su Menu > Cloud Functions.

    Vai a Cloud Functions

    Assicurati che il progetto per cui hai attivato Cloud Functions sia selezionato.

  2. Nell'elenco delle funzioni, fai clic su AddOnChatApp.

  3. Fai clic sulla scheda Attivatori.

  4. In HTTPS, copia l'URL.

  5. Cerca "API Google Chat" e fai clic su API Google Chat, poi fai clic su Gestisci.

    Vai all'API Chat

  6. Fai clic su Configurazione e configura l'app Google Chat:

    1. In Nome dell'app, inserisci Add-on Chat app.
    2. In URL avatar, inserisci https://developers.google.com/chat/images/quickstart-app-avatar.png.
    3. In Descrizione, inserisci Add-on Chat app.
    4. In Funzionalità, seleziona Ricevi messaggi 1:1 e Partecipa a spazi e conversazioni di gruppo.
    5. In Impostazioni di connessione, seleziona URL endpoint HTTP e incolla l'URL per l'attivatore della Funzione Cloud nella casella.
    6. In Authentication Audience (Pubblico di autenticazione), seleziona HTTP endpoint URL (URL endpoint HTTP).
    7. In Visibilità, seleziona Rendi disponibile questa app Google Chat a utenti e gruppi specifici nel tuo dominio e inserisci il tuo indirizzo email.
    8. In Log, seleziona Errori di log in Logging.

  7. Fai clic su Salva.

L'app Chat è pronta per ricevere e rispondere ai messaggi su Chat.

Testare l'app Chat

Per testare l'app Chat, apri uno spazio di messaggi diretti con l'app Chat e invia un messaggio:

  1. Apri Google Chat utilizzando l'account Google Workspace fornito quando hai aggiunto te stesso come tester attendibile.

    Vai a Google Chat

  2. Fai clic su Nuova chat.
  3. Nel campo Aggiungi 1 o più persone, digita il nome della tua app Chat.

  4. Seleziona l'app Chat dai risultati. Viene visualizzato un messaggio diretto.

  5. Nel nuovo messaggio diretto con l'app, digita Hello e premi enter.

Il messaggio dell'app Chat contiene una scheda che mostra il nome e l'immagine dell'avatar del mittente, come mostrato nell'immagine seguente:

App di chat che risponde con una scheda contenente il nome visualizzato e l&#39;immagine dell&#39;avatar del mittente

Per aggiungere Trusted Tester e scoprire di più sul test delle funzionalità interattive, consulta Testare le funzionalità interattive per le app Google Chat.

Risoluzione dei problemi

Quando un'app o una scheda di Google Chat restituisce un errore, l'interfaccia di Chat mostra il messaggio "Si è verificato un problema". o "Impossibile elaborare la tua richiesta". A volte l'interfaccia utente di Chat non mostra alcun messaggio di errore, ma l'app Chat o la scheda produce un risultato imprevisto; ad esempio, un messaggio della scheda potrebbe non essere visualizzato.

Sebbene un messaggio di errore potrebbe non essere visualizzato nell'interfaccia utente di Chat, sono disponibili messaggi di errore descrittivi e dati di log per aiutarti a correggere gli errori quando la registrazione degli errori per le app Chat è attivata. Per assistenza su come visualizzare, eseguire il debug e correggere gli errori, consulta la sezione Risolvere gli errori di Google Chat.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, ti consigliamo di eliminare il progetto Cloud.

  1. Nella console Google Cloud, vai alla pagina Gestisci risorse. Fai clic su Menu > IAM e amministrazione > Gestisci risorse.

    Vai a Resource Manager

  2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare e fai clic su Elimina .
  3. Nella finestra di dialogo, digita l'ID progetto e fai clic su Chiudi per eliminare il progetto.