Auf dieser Seite wird beschrieben, wie Sie ein Google Workspace-Add-on erstellen, das in Google Chat mit einem HTTP-Dienst funktioniert. In Google Chat werden Add-ons für Nutzer als Google Chat-Apps angezeigt. Weitere Informationen finden Sie unter Google Chat erweitern – Übersicht.
In dieser Kurzanleitung erfahren Sie, wie Sie mit Google Cloud-Diensten einen HTTP-Dienst erstellen. Zum Erstellen der Chat-App schreiben und stellen Sie eine Cloud Functions-Funktion bereit, mit der die Chat-App auf die Nachricht eines Nutzers antwortet.
Bei einer HTTP-Architektur konfigurieren Sie Google Chat so, dass es über HTTP mit Google Cloud oder einem lokalen Server verbunden wird, wie im folgenden Diagramm dargestellt:
Im vorherigen Diagramm wird der Informationsfluss für einen Nutzer dargestellt, der mit einer HTTP-Chat-App interagiert:
- Ein Nutzer sendet eine Nachricht in Google Chat an eine Chat-App, entweder in einer Direktnachricht oder in einem Gruppenbereich.
- Eine HTTP-Anfrage wird an einen Webserver gesendet, der entweder ein Cloud- oder ein On-Premises-System ist, das die Logik der Chat-App enthält.
- Optional kann die Logik der Chat-App in Google Workspace-Dienste (z. B. Google Kalender und Google Tabellen), andere Google-Dienste (z. B. Google Maps, YouTube und Vertex AI) oder andere Webdienste (z. B. ein Projektverwaltungssystem oder ein Ticketsystem) eingebunden werden.
- Der Webserver sendet eine HTTP-Antwort an den Chat App-Dienst in Google Chat zurück.
- Die Antwort wird an den Nutzer gesendet.
- Optional kann die Chat-App die Chat API aufrufen, um asynchron Nachrichten zu posten oder andere Aktionen auszuführen.
Diese Architektur bietet Ihnen die Flexibilität, vorhandene Bibliotheken und Komponenten zu verwenden, die bereits in Ihrem System vorhanden sind, da diese Chat-Apps in verschiedenen Programmiersprachen entwickelt werden können.
Zielsetzungen
- die Umgebung einrichten
- Erstellen und bereitstellen Sie eine Cloud-Funktion.
- Konfigurieren Sie ein Google Workspace-Add-on für die Chat-App.
- Testen Sie die App.
Vorbereitung
- Ein Google Workspace-Konto für Unternehmen oder Organisationen mit Zugriff auf Google Chat.
- Google Cloud-Projekt mit aktivierter Abrechnungsfunktion. Wie Sie prüfen, ob für ein bestehendes Projekt die Abrechnung aktiviert ist, erfahren Sie unter Abrechnungsstatus Ihrer Projekte prüfen. Weitere Informationen zum Erstellen eines Projekts und zum Einrichten der Abrechnung finden Sie unter Google Cloud-Projekt erstellen.
Umgebung einrichten
Bevor Sie Google APIs verwenden können, müssen Sie sie in einem Google Cloud-Projekt aktivieren. Sie können eine oder mehrere APIs in einem einzelnen Google Cloud-Projekt aktivieren.Aktivieren Sie in der Google Cloud Console die Google Chat API, die Cloud Build API, die Cloud Functions API, die Cloud Pub/Sub API, die Cloud Logging API, die Artifact Registry API und die Cloud Run API.
Cloud Functions-Funktionen erstellen und bereitstellen
Erstellen und implementieren Sie eine Cloud Function, die eine Chatkarte mit dem Anzeigenamen und dem Avatarbild des Absenders generiert. Wenn die Chat-App eine Nachricht empfängt, führt sie die Funktion aus und antwortet mit der Karte.
So erstellen und implementieren Sie die Funktion für Ihre Chat-App:
Node.js
Wechseln Sie in der Google Cloud Console zur Seite Cloud Functions:
Achten Sie darauf, dass das Projekt für Ihre Chat-App ausgewählt ist.
Klicken Sie auf
Funktion erstellen.Richten Sie auf der Seite „Funktion erstellen“ Ihre Funktion ein:
- Wählen Sie unter Umgebung die Option Cloud Run-Funktion aus.
- Geben Sie unter Funktionsname
AddOnChatApp
ein. - Wählen Sie unter Region eine Region aus.
- Wählen Sie unter „Authentifizierung“ die Option Authentifizierung erforderlich aus.
- Klicken Sie auf Weiter.
Wählen Sie unter Laufzeit die neueste Version von Node.js aus.
Wählen Sie unter Quellcode die Option Inline-Editor aus.
Löschen Sie unter Einstiegspunkt den Standardtext und geben Sie
avatarApp
ein.Ersetzen Sie den Inhalt von
index.js
durch folgenden Code:/** * 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 } }] }] } }] }}}}}); };
Klicken Sie auf Bereitstellen.
Python
Wechseln Sie in der Google Cloud Console zur Seite Cloud Functions:
Achten Sie darauf, dass das Projekt für Ihre Chat-App ausgewählt ist.
Klicken Sie auf
Funktion erstellen.Richten Sie auf der Seite „Funktion erstellen“ Ihre Funktion ein:
- Wählen Sie unter Umgebung die Option Cloud Run-Funktion aus.
- Geben Sie unter Funktionsname
AddOnChatApp
ein. - Wählen Sie unter Region eine Region aus.
- Wählen Sie unter „Authentifizierung“ die Option Authentifizierung erforderlich aus.
- Klicken Sie auf Weiter.
Wählen Sie unter Laufzeit die neueste Version von Python aus.
Wählen Sie unter Quellcode die Option Inline-Editor aus.
Löschen Sie unter Einstiegspunkt den Standardtext und geben Sie
avatar_app
ein.Ersetzen Sie den Inhalt von
main.py
durch folgenden Code: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 } }] }] } }] }}}}}
Klicken Sie auf Bereitstellen.
Java
Wechseln Sie in der Google Cloud Console zur Seite Cloud Functions:
Achten Sie darauf, dass das Projekt für Ihre Chat-App ausgewählt ist.
Klicken Sie auf
Funktion erstellen.Richten Sie auf der Seite „Funktion erstellen“ Ihre Funktion ein:
- Wählen Sie unter Umgebung die Option Cloud Run-Funktion aus.
- Geben Sie unter Funktionsname
AddOnChatApp
ein. - Wählen Sie unter Region eine Region aus.
- Wählen Sie unter „Authentifizierung“ die Option Authentifizierung erforderlich aus.
- Klicken Sie auf Weiter.
Wählen Sie unter Laufzeit die neueste Version von Java aus.
Wählen Sie unter Quellcode die Option Inline-Editor aus.
Löschen Sie unter Einstiegspunkt den Standardtext und geben Sie
AvatarApp
ein.Benennen Sie die Standard-Java-Datei in
src/main/java/AvatarApp.java
um.Ersetzen Sie den Inhalt von
AvatarApp.java
durch folgenden Code: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; } }
Ersetzen Sie den Inhalt von
pom.xml
durch folgenden Code:<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>
Klicken Sie auf Bereitstellen.
Die Detailseite von Cloud Functions wird geöffnet. Ihre Funktion wird mit zwei Fortschrittsanzeigen angezeigt: eine für den Build und eine für den Dienst. Wenn beide Fortschrittsanzeigen verschwinden und durch ein Häkchen ersetzt werden, ist die Funktion bereitgestellt und einsatzbereit.
Google Chat zum Aufrufen Ihrer Funktion autorisieren
Wenn Sie das Google Workspace-Add-on zum Aufrufen Ihrer Funktion autorisieren möchten, fügen Sie dem Dienstkonto des Google Workspace-Add-ons die Rolle Cloud Run-Aufrufer hinzu.
Wechseln Sie in der Google Cloud Console zur Seite Cloud Run.
Klicken Sie in der Liste der Cloud Run-Dienste auf das Kästchen neben der empfangenden Funktion. (Klicken Sie nicht auf die Funktion selbst.)
Klicke auf Berechtigungen. Der Bereich Berechtigungen wird geöffnet.
Klicken Sie auf Hauptkonto hinzufügen.
Geben Sie unter Neue Hauptkonten die E-Mail-Adresse des Google Workspace-Add-on-Dienstkontos ein, das mit Ihrem Projekt verknüpft ist.
Wählen Sie unter Rolle auswählen die Option Cloud Run > Cloud Run Invoker aus.
Klicken Sie auf Speichern.
Add-on konfigurieren
Nachdem die Cloud-Funktion bereitgestellt wurde, gehen Sie so vor, um ein Add-on zu erstellen und die Google Chat-App bereitzustellen:
Klicken Sie in der Google Cloud Console auf das Dreistrich-Menü > Cloud Functions.
Achten Sie darauf, dass das Projekt ausgewählt ist, für das Sie Cloud Functions aktiviert haben.
Klicken Sie in der Liste der Funktionen auf AddOnChatApp.
Klicken Sie auf den Tab Trigger.
Kopieren Sie unter HTTPS die URL.
Suchen Sie nach „Google Chat API“, klicken Sie auf Google Chat API und dann auf Verwalten.
Klicken Sie auf Konfiguration und richten Sie die Google Chat App ein:
- Geben Sie unter App-Name
Add-on Chat app
ein. - Geben Sie unter Avatar-URL
https://developers.google.com/chat/images/quickstart-app-avatar.png
ein. - Geben Sie unter Beschreibung
Add-on Chat app
ein. - Wählen Sie unter Funktionsweise die Optionen 1:1-Nachrichten empfangen und Gruppenbereichen und Gruppenunterhaltungen beitreten aus.
- Wählen Sie unter Verbindungseinstellungen die Option HTTP-Endpunkt-URL aus und fügen Sie die URL für den Cloud Functions-Trigger in das Feld ein.
- Wählen Sie unter Authentifizierungsziel die Option HTTP-Endpunkt-URL aus.
- Wählen Sie unter Sichtbarkeit die Option Diese Google Chat-App bestimmten Personen und Gruppen in zur Verfügung stellen aus und geben Sie Ihre E-Mail-Adresse ein.
- Wählen Sie unter Protokolle die Option Fehler in Logging protokollieren aus.
- Geben Sie unter App-Name
Klicken Sie auf Speichern.
Die Chat App ist bereit, Nachrichten in Google Chat zu empfangen und darauf zu antworten.
Chat-App testen
Wenn Sie die Chat App testen möchten, öffnen Sie einen Direktnachrichtenbereich mit der Chat App und senden Sie eine Nachricht:
Öffnen Sie Google Chat mit dem Google Workspace-Konto, das Sie angegeben haben, als Sie sich als vertrauenswürdiger Tester hinzugefügt haben.
- Klicken Sie auf Neuer Chat.
- Geben Sie im Feld Eine oder mehrere Personen hinzufügen den Namen Ihrer Chat-App ein.
Wählen Sie in den Ergebnissen Ihre Chat-App aus. Eine Direktnachricht wird geöffnet.
- Geben Sie in der neuen Direktnachricht an die App
Hello
ein und drücken Sieenter
.
Die Nachricht in der Chat App enthält eine Karte mit dem Namen und dem Avatarbild des Absenders, wie in der folgenden Abbildung dargestellt:
Informationen zum Hinzufügen von Trusted Testern und zum Testen interaktiver Funktionen finden Sie unter Interaktive Funktionen für Google Chat-Apps testen.
Fehlerbehebung
Wenn eine Google Chat-App oder Karte einen Fehler zurückgibt, wird in der Chat-Benutzeroberfläche die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage konnte nicht verarbeitet werden“ Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, aber die Chat-App oder Karte führt zu einem unerwarteten Ergebnis. Beispielsweise wird möglicherweise keine Kartennachricht angezeigt.
Auch wenn in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt wird, sind beschreibende Fehlermeldungen und Protokolldaten verfügbar, die Ihnen bei der Fehlerbehebung helfen, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Informationen zum Ansehen, Entfernen und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben.
Bereinigen
Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, empfehlen wir Ihnen, das Cloud-Projekt zu löschen.
- Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten. Klicken Sie auf das Dreistrich-Menü > IAM & Verwaltung > Ressourcen verwalten.
- Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf Löschen .
- Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Beenden, um das Projekt zu löschen.