Diese Seite wurde von der Cloud Translation API übersetzt.

Mit einer Google Chat-App in den Urlaub fahren

1. Einführung

Google Chat-Apps bieten Dienste und Ressourcen direkt in Chat. Nutzer können so Informationen abrufen und Aktionen ausführen, ohne die Unterhaltung zu verlassen.

In diesem Codelab erfahren Sie, wie Sie eine Chat-App erstellen, die Abwesenheitsnotizen in Gmail einrichtet und Termine in Google Kalender plant. Wenn Sie die Attendance Chat App in Google Apps Script erstellen, können Sie problemlos auf andere Google-Dienste wie Drive, Gmail, Kalender, Docs und Tabellen zugreifen.

Lerninhalte

Handler in Ereignissen hinzufügen, die in Chat ausgelöst werden
Von Chat gesendete Ereignisobjekte parsen
Auf Google Chat mit Antworten in Kartenform reagieren
Benutzerdefinierte Aktionen für Klicks auf Schaltflächen in Karten definieren und darauf reagieren

Voraussetzungen

Zugriff auf das Internet und einen Webbrowser
Ein Google Workspace-Konto mit Zugriff auf Google Chat.
Grundkenntnisse in JavaScript: Google Apps Script unterstützt nur JavaScript.

2. Beispielcode abrufen

Sie können entweder eine ZIP-Datei herunterladen oder das GitHub-Repository klonen, um den Code für jeden Schritt in diesem Beispiel zu sehen.

Die step-NN-Ordner unter solutions/attendance-chat-app enthalten den gewünschten Endstatus jedes Schrittes dieses Codelabs. Sie sind als Referenz verfügbar.

Code herunterladen

Klicken Sie auf die folgende Schaltfläche, um den Code für dieses Codelab herunterzuladen:

Entpacken Sie die heruntergeladene ZIP-Datei. Dadurch wird ein Stammordner (apps-script-samples) entpackt, der unter solutions/attendance-chat-app einen Ordner für jeden Schritt dieses Codelabs enthält.

GitHub-Repository klonen

Führen Sie den folgenden Befehl aus, um das GitHub-Repository für dieses Codelab zu klonen:

git clone https://github.com/googleworkspace/apps-script-samples

3. Handler für Google Chat-Ereignisse erstellen

Apps Script-Projekt erstellen

So erstellen Sie ein Apps Script-Projekt:

Rufen Sie script.new auf.
Klicken Sie auf Unbenanntes Projekt.
Benennen Sie das Script Attendance Chat app um und klicken Sie auf Rename (Umbenennen).

Ereignisse in Google Chat

Die meisten Apps Script-Interaktionen mit Chat sind ereignisgesteuert. Normalerweise laufen sie zwischen dem Nutzer, der Chat App und Google Chat in der folgenden Reihenfolge ab:

Ein Nutzer leitet eine Aktion ein, fügt also z. B. einem Gruppenbereich eine Chat-App hinzu, sendet eine Direktnachricht (DN) an eine Chat-App oder entfernt eine Chat-App aus einem Gruppenbereich.
Die Aktion löst ein Ereignis aus, das an die Chat App in Google Chat gerichtet ist.
In Chat wird der entsprechende Event-Handler aufgerufen, der im Skript der Chat-App definiert ist.

Chat löst vier Ereignisse aus, die Ihre App beobachten kann:

ADDED_TO_SPACE: Dieses Ereignis tritt ein, wenn ein Nutzer einem Gruppenbereich oder einer Direktnachricht (DN) eine Chat-App hinzufügt. In Apps Script definieren Sie eine onAddToSpace()-Funktion, um dieses Ereignis zu verarbeiten.
REMOVED_FROM_SPACE: Dieses Ereignis tritt ein, wenn ein Nutzer die Chat App aus einem Chatbereich oder einer DN entfernt. Bei diesem Ereignis wird keine Antwort an Chat zurückgegeben. In Apps Script definieren Sie eine onRemoveFromSpace()-Funktion, um dieses Ereignis zu verarbeiten.
MESSAGE: Dieses Ereignis tritt ein, wenn ein Nutzer eine Nachricht an die Chat App sendet, entweder direkt in einer DN oder als @Erwähnung in einem Bereich. In Apps Script definieren Sie eine onMessage()-Funktion als Antwort auf dieses Ereignis.
CARD_CLICKED: Dieses Ereignis tritt ein, wenn der Nutzer auf eine Schaltfläche klickt, der eine benutzerdefinierte Aktion zugewiesen ist. In Apps Script definieren Sie eine onCardClick()-Funktion als Antwort auf dieses Ereignis.

Ersetzen Sie den Inhalt der Datei Code.gs durch den folgenden Code, der Handler für die Ereignisse ADDED_TO_SPACE und REMOVE_FROM_SPACE definiert. (Die Handler für die Ereignisse MESSAGE und CARD_CLICKED fügen Sie später in diesem Codelab hinzu.)

Code.gs

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onAddToSpace(event) {
  console.info(event);
  var message = 'Thank you for adding me to ';
  if (event.space.type === 'DM') {
    message += 'a DM, ' + event.user.displayName + '!';
  } else {
    message += event.space.displayName;
  }
  return { text: message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onRemoveFromSpace(event) {
  console.info(event);
  console.log('Chat app removed from ', event.space.name);
}

4. Chat-App veröffentlichen und testen

Skriptmanifestdatei aktualisieren

Bevor Sie Ihre App in Chat veröffentlichen können, müssen Sie das Skriptmanifest aktualisieren.

Klicken Sie auf Projekteinstellungen .
Klicken Sie das Kästchen Manifestdatei „appsscript.json“ im Editor anzeigen an.
Klicke auf Editor .
Klicken Sie auf die Datei appsscript.json.
Fügen Sie die Zeile "chat": {} in Ihre Manifestdatei ein.

Die Manifestdatei sollte in etwa dem folgenden Beispiel entsprechen.

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "chat": {}
}

Google Cloud-Projekt erstellen

Bevor Sie die Chat-App ausführen und testen können, müssen Sie ein Google Cloud-Projekt erstellen, die Chat API aktivieren und konfigurieren und Ihre Chat-App in Ihrer Google Workspace-Organisation veröffentlichen.

Rufen Sie in der Google Cloud Console das Menü > IAM & Verwaltung> Projekt erstellen auf.
Geben Sie unter Projektname einen aussagekräftigen Namen ein.
Wählen Sie bei Aufforderung die Organisation und das Rechnungskonto aus.
Klicken Sie auf Erstellen.
Wenn das Projekt erstellt wurde, wird oben rechts auf der Seite eine Benachrichtigung angezeigt. Klicken Sie auf den Eintrag Projekt erstellen: <Projektname>, um das Projekt zu öffnen.
Klicken Sie auf das Menü > APIs & Dienste> Anmeldedaten.
Klicken Sie auf OAuth-Zustimmungsbildschirm.
Geben Sie als App-Name Attendance Chat app ein.
Geben Sie bei Aufforderung die E‑Mail-Adresse für den Nutzersupport und die Kontaktdaten des Entwicklers ein.
Klicken Sie auf Speichern und fortfahren.
Klicken Sie auf „Einstellungen und Dienstprogramme“ > Projekteinstellungen.
Kopieren Sie die Projektnummer.
Klicken Sie im App Script-Editor auf Projekteinstellungen .
Klicken Sie unter Google Cloud Platform-Projekt (GCP-Projekt) auf Projekt ändern.
Klicken Sie auf GCP-Projektnummer und geben Sie die Projektnummer ein.
Klicken Sie auf Projekt festlegen.

App in Google Chat veröffentlichen

So veröffentlichen Sie Ihre Chat-App in Google Chat:

Klicken Sie im Apps Script-Editor auf Bereitstellen > Neue Bereitstellung.
Klicken Sie neben Typ auswählen auf „Bereitstellungstypen aktivieren“ .
Wählen Sie Add-on aus und klicken Sie auf Bereitstellen.
Kopieren Sie die Deployment ID und klicken Sie auf Done (Fertig).
Rufen Sie in der Google Cloud Console das Menü > APIs & Dienste> Bibliothek auf.
Suchen Sie nach Google Chat API. Wählen Sie die API aus der Ergebnisliste aus.
Klicken Sie auf der Seite „Google Chat API“ auf Aktivieren.
Nachdem Sie die API aktiviert haben, klicken Sie auf Konfiguration. Ignorieren Sie alle Meldungen, in denen Sie zur Erstellung von Anmeldedaten aufgefordert werden.
Führen Sie auf der Seite Konfiguration folgende Schritte aus:

Deaktivieren Sie Diese Chat-App als Workspace-Add‑on erstellen und klicken Sie zur Bestätigung auf DEAKTIVIEREN.
Geben Sie als App-Name Attendance Chat app ein.
Geben Sie für Avatar-URL https://goo.gl/kv2ENA ein.
Geben Sie unter Beschreibung Apps Script-Codelab-Chat-App ein.
Wählen Sie unter Funktionsweise die Option Direktnachrichten erhalten aus.
Wählen Sie unter Verbindungseinstellungen die Option Apps Script-Projekt aus und fügen Sie die Bereitstellungs-ID Ihres Skripts in das Textfeld ein.
Wählen Sie unter Berechtigungen die Option Bestimmte Personen und Gruppen in Ihrer Domain aus. Geben Sie im Textfeld unter dem Drop-down-Menü die E‑Mail-Adresse ein, die mit Ihrer Google Workspace-Organisation verknüpft ist.
Klicken Sie auf Speichern.

Vergewissern Sie sich nach dem Speichern der Änderungen, dass auf der Google Chat API-Seite der App-Status als LIVE – für Nutzer verfügbar angezeigt wird.

Chat App testen

So testen Sie Ihre App in Google Chat:

Öffnen Sie Google Chat.
Senden Sie eine neue Direktnachricht an die Chat App, indem Sie auf „Chat starten“ > Apps suchen klicken.
Suchen Sie auf der Seite „Apps suchen“ nach der Attendance Chat App.
Klicken Sie neben Chat-App für die Teilnahme auf Hinzufügen> Chat.

Wenn die Direktnachrichtkonversation geöffnet wird, sollten Sie eine Nachricht von der Chat App sehen, in der sie sich bei Ihnen bedankt, dass Sie sie einer DN hinzugefügt haben. Dies ist in der folgenden Abbildung zu sehen.

5. Antworten in Kartenform definieren

Im vorherigen Schritt hat Ihre App auf Google Chat-Ereignisse mit einer einfachen Textantwort reagiert. In diesem Schritt aktualisieren Sie die App, um mit Karten zu antworten.

Kartenantworten

Google Chat unterstützt die Verwendung von Karten für Antworten. Karten sind visuelle Container, mit denen Sie Gruppen von Benutzeroberflächen-Widgets zusammenfassen können. Karten enthalten z. B. Titel, Textabsätze, Schaltflächen, Bilder und Schlüssel/Wert-Text. Für Ihre App können eine oder mehrere Karten in ihrer JSON-Antwort auf Google Chat definiert werden, die dann Ihre Antwort in die entsprechenden Benutzeroberflächenelemente übersetzt.

In der folgenden Abbildung ist eine Kartenantwort mit drei Abschnitten zu sehen, die einen Titel, ein Schlüssel/Wert-Widget, ein Bildwidget und eine Textschaltfläche enthält.

Wenn Sie auf Nutzernachrichten mit einer Karte antworten möchten, fügen Sie der Datei Code.gs Ihrer Chat-App den folgenden Code hinzu.

Code.gs

const DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
const HEADER = {
  header: {
    title : 'Attendance Chat app',
    subtitle : 'Log your vacation time',
    imageUrl : DEFAULT_IMAGE_URL
  }
};

/**
 * Creates a card-formatted response.
 * @param {object} widgets the UI components to send
 * @return {object} JSON-formatted response
 */
function createCardResponse(widgets) {
  return {
    cards: [HEADER, {
      sections: [{
        widgets: widgets
      }]
    }]
  };
}

/**
 * Responds to a MESSAGE event triggered
 * in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return JSON-formatted response
 */
function onMessage(event) {
  const userMessage = event.message.text;

  const widgets = [{
    "textParagraph": {
      "text": "You said: " + userMessage
    }
  }];

  return createCardResponse(widgets);
}

Mit der in diesem Schritt hinzugefügten Funktion onMessage() wird die ursprüngliche Nachricht des Nutzers gelesen und eine Antwort als einfaches TextParagragh-Widget erstellt. Über die Funktion onMessage() wird dann createCardResponse() aufgerufen, wodurch das TextParagraph-Widget in einen Abschnitt einer einzelnen Karte platziert wird. Die Chat-App gibt das mit der Kartenantwort erstellte JavaScript-Objekt an Google Chat zurück.

Chat App testen

Wenn Sie diese App testen möchten, kehren Sie einfach zu Ihrer Direktnachricht mit der App in Google Chat zurück und geben Sie eine beliebige Nachricht ein.

Der Event-Handler onMessage() parst das von Google Chat an ihn weitergegebene Ereignisobjekt, um die ursprüngliche Nachricht des Nutzers zu extrahieren. Sie können auch andere Informationen über das Ereignis abrufen, z. B. den Namen des Nutzers, der das Ereignis initiiert hat, seine E-Mail-Adresse, den Namen des Bereichs, in dem das Ereignis stattfand, und vieles mehr.

Weitere Informationen zur Struktur der von Google Chat gesendeten Ereignisobjekte finden Sie in der Referenz zu Ereignisformaten.

6. Auf Schaltflächenklicks in Karten reagieren

Im vorherigen Schritt hat Ihre Chat-App auf eine Nachricht von einem Nutzer, einem MESSAGE-Ereignis, mit einer einfachen Karte reagiert, die ein TextParagragh-Widget enthielt. In diesem Schritt erstellen Sie eine Antwort, die Schaltflächen enthält, für die jeweils eine benutzerdefinierte Aktion definiert ist.

Interaktive Karten

Kartenantworten können eine der beiden folgenden Schaltflächentypen enthalten: TextButton-Widgets, also Schaltflächen nur mit Text, sowie ImageButton-Widgets, die nur ein einfaches Symbol oder ein Bild ohne Text enthalten. Sowohl TextButton- als auch ImageButton-Widgets unterstützen eine von zwei onClick-Verhaltensweisen, die in der JSON-Antwort definiert ist, die an Google Chat zurückgesendet wird: openLink oder action. Wie der Name schon andeutet, öffnet openLink einen angegebenen Link in einem neuen Browsertab.

Das action-Objekt gibt eine benutzerdefinierte Aktion an, die bei einem Klick auf die Schaltfläche ausgeführt werden soll. Sie können im Aktionsobjekt mehrere beliebige Werte angeben, z. B. einen eindeutigen Namen über actionMethodName sowie einen Satz mit Schlüssel / Wert-Parameterpaaren.

Wenn Sie für eine Schaltfläche ein action-Objekt angeben, wird eine interaktive Karte erstellt. Wenn der Nutzer auf die Schaltfläche in der Nachricht klickt, löst Google Chat das Ereignis CARD_CLICKED aus und sendet eine Anfrage an die App zurück, die die ursprüngliche Nachricht gesendet hat. Die App muss dann das aus Google Chat hervorgegangene Ereignis verarbeiten und eine Antwort an den Bereich zurückgeben.

Ersetzen Sie die Funktion onMessage() in Code.gs durch den folgenden Code. Damit werden die beiden Schaltflächen Set vacation in Gmail (Abwesenheitsnotiz in Gmail einrichten) und Block out day in Calendar (Tag in Kalender reservieren) in der Karte erzeugt, die an Google Chat gesendet wird.

Code.gs

const REASON = {
  SICK: 'Out sick',
  OTHER: 'Out of office'
};
/**
 * Responds to a MESSAGE event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 */
function onMessage(event) {
  console.info(event);
  const reason = REASON.OTHER;
  const name = event.user.displayName;
  const userMessage = event.message.text;

  // If the user said that they were 'sick', adjust the image in the
  // header sent in response.
  if (userMessage.indexOf('sick') > -1) {
    // Hospital material icon
    HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
    reason = REASON.SICK;
  } else if (userMessage.indexOf('vacation') > -1) {
    // Spa material icon
    HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
  }

  const widgets = [{
    textParagraph: {
      text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
    }
  }, {
    buttons: [{
      textButton: {
        text: 'Set vacation in Gmail',
        onClick: {
          action: {
            actionMethodName: 'turnOnAutoResponder',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }, {
      textButton: {
        text: 'Block out day in Calendar',
        onClick: {
          action: {
            actionMethodName: 'blockOutCalendar',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }]
  }];
  return createCardResponse(widgets);
}

Wenn Sie das Ereignis CARD_CLICKED verarbeiten möchten, müssen Sie die Funktion onCardClick() zum Skript Ihrer Chat-App hinzufügen. Fügen Sie den folgenden Code hinzu, der die Funktion onCardClick() von Code.gs definiert.

Code.gs

/**
 * Responds to a CARD_CLICKED event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onCardClick(event) {
  console.info(event);
  let message = '';
  const reason = event.action.parameters[0].value;
  if (event.action.actionMethodName == 'turnOnAutoResponder') {
    turnOnAutoResponder(reason);
    message = 'Turned on vacation settings.';
  } else if (event.action.actionMethodName == 'blockOutCalendar') {
    blockOutCalendar(reason);
    message = 'Blocked out your calendar for the day.';
  } else {
    message = "I'm sorry; I'm not sure which button you clicked.";
  }
  return { text: message };
}

Als Antwort auf Klicks führt die Chat-App nun eine der beiden folgenden Aktionen aus: Sie richtet die Abwesenheitsnotiz des Nutzers in Gmail ein oder sie trägt einen ganztägigen Termin im Kalender des Nutzers ein. Dazu ruft die App den erweiterten Gmail-Dienst und den Kalenderdienst auf.

Fügen Sie Ihrem Skript den folgenden Code hinzu, um die Chat App in Gmail und Kalender zu integrieren.

Code.gs

const ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
 * Turns on the user's vacation response for today in Gmail.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function turnOnAutoResponder(reason) {
  let currentTime = (new Date()).getTime();
  Gmail.Users.Settings.updateVacation({
    enableAutoReply: true,
    responseSubject: reason,
    responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Chat app!</i>",
    restrictToContacts: true,
    restrictToDomain: true,
    startTime: currentTime,
    endTime: currentTime + ONE_DAY_MILLIS
  }, 'me');
}

/**
 * Places an all-day meeting on the user's Calendar.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function blockOutCalendar(reason) {
  CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}

Schließlich müssen Sie den erweiterten Gmail-Dienst im Projekt aktivieren. So aktivieren Sie die Gmail API:

Klicken Sie im Apps Script-Editor neben Dienste auf „Dienst hinzufügen“ .
Wählen Sie Gmail API aus.
Klicken Sie unten auf Google Cloud Platform API-Dashboard, um die Google Cloud Console zu öffnen.
Klicken Sie auf APIs und Dienste aktivieren.
Suchen Sie nach Gmail API und klicken Sie auf die Gmail API.
Klicken Sie auf der Seite „Gmail API“ auf Aktivieren.

Chat App testen

Wenn Sie diese Version Ihrer Chat-App testen möchten, öffnen Sie die DN, die Sie in den vorherigen Schritten in Google Chat begonnen haben, und geben Sie I'm going on vacation (Ich fahre in den Urlaub) ein. Die App sollte mit einer Karte antworten, die in etwa so aussieht:

Hinweis:Wenn Sie aufgefordert werden, Zugriff auf die App zu gewähren, müssen Sie Ihre Nachricht möglicherweise ein zweites Mal eingeben.

7. Glückwunsch!

Ihre Chat-App kann jetzt auf Nutzernachrichten reagieren, deren Abwesenheitsnotiz in Gmail einrichten und einen ganztägigen Termin in den Kalender eintragen.

Behandelte Themen

Sie haben eine Google Chat-App mit Apps Script erstellt und veröffentlicht.
Auf Nutzernachrichten mit einer einfachen Antwort reagiert
Interaktion mit anderen Google Workspace-Diensten im Namen des Nutzers über die Chat-App

Mit einer Google Chat-App in den Urlaub fahren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

1. Einführung

Lerninhalte

Voraussetzungen

2. Beispielcode abrufen

Code herunterladen

GitHub-Repository klonen

3. Handler für Google Chat-Ereignisse erstellen

Apps Script-Projekt erstellen

Ereignisse in Google Chat

Code.gs

4. Chat-App veröffentlichen und testen

Skriptmanifestdatei aktualisieren

appsscript.json

Google Cloud-Projekt erstellen

App in Google Chat veröffentlichen

Chat App testen

5. Antworten in Kartenform definieren

Kartenantworten

Code.gs

Chat App testen

6. Auf Schaltflächenklicks in Karten reagieren

Interaktive Karten

Code.gs

Code.gs

Code.gs

Chat App testen

7. Glückwunsch!

Behandelte Themen

Weitere Informationen

Mit einer Google Chat-App in den Urlaub fahren