Diese Seite wurde von der Cloud Translation API übersetzt.

Chat-App mit Apps Script entwickeln

Apps Script ist eine der schnellsten Methoden zum Erstellen einer Chat-App für Google Chat.

Sie können eine Anwendung in nur wenigen Minuten direkt in Ihrem Browser einrichten.
Sie müssen sich nicht um die Ausführung und Verwaltung von Servern, laufende Wartungs- oder Betriebskosten oder das Herunterladen und Einrichten einer Entwicklungsumgebung kümmern.
Es ist sehr einfach, Google APIs – insbesondereGoogle Workspace -APIs – aufzurufen, da es mit Apps Script keinen Download oder keine Einrichtung gibt, die Authentifizierung automatisch erfolgt und Google API-Aufrufe wie bei nativen Funktionsaufrufen funktionieren.

In diesem Leitfaden wird erläutert, wie Sie eine App mit Apps Script erstellen und registrieren.

Erste Schritte

In diesem Abschnitt erfahren Sie, wie Sie schnell eine Chat-App mit Apps Script erstellen.

Schritt 1: Apps Script-Vorlage kopieren

Am einfachsten erstellen Sie eine Apps Script-Anwendung mit der Chat-Vorlage. Dadurch wird ein Apps Script-Projekt mit den benötigten Methoden erstellt. Danach können Sie die Methoden nach Bedarf einfügen, um Ihre Anwendungslogik zu implementieren oder eine von Ihnen erstellte Anwendung zu integrieren. Der folgende Code zeigt ein Beispiel für die Vorlage einer einfachen Anwendung.

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  var name = "";

  if (event.space.type == "DM") {
    name = "You";
  } else {
    name = event.user.displayName;
  }
  var message = name + " said \"" + event.message.text + "\"";

  return { "text": message };
}

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAddToSpace(event) {
  var message = "";

  if (event.space.singleUserBotDm) {
    message = "Thank you for adding me to a DM, " + event.user.displayName + "!";
  } else {
    message = "Thank you for adding me to " +
        (event.space.displayName ? event.space.displayName : "this chat");
  }

  if (event.message) {
    // Bot added through @mention.
    message = message + " and you said: \"" + event.message.text + "\"";
  }

  return { "text": message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onRemoveFromSpace(event) {
  console.info("Bot removed from ",
      (event.space.name ? event.space.name : "this chat"));
}

Schritt 2: onMessage-Funktion bearbeiten

Standardmäßig gibt die Funktion onMessage in der Vorlage ein Message-Objekt zurück, das Text und eine einfache Karte enthält. Sie können diese Funktion so bearbeiten, dass Text oder bestimmte Kartenwidgets zurückgegeben werden.

function onMessage(e) {
  return { 'text': 'You said: \`' + e.message.text + '\`' };
}

Schritt 3: Bereitstellungs-ID abrufen

Bevor Sie Ihre Anwendung registrieren können, benötigen Sie die Deployment-ID für diese bestimmte Anwendung.

Klicken Sie auf Bereitstellen > Neue Bereitstellung.
Klicken Sie unter Typ auswählen auf Add-on.
Füllen Sie die Optionen aus und klicken Sie auf Bereitstellen.
Klicken Sie unter „Bereitstellungs-ID“ auf Kopieren.

Im Releaseverwaltungsleitfaden finden Sie Informationen zu empfohlenen Vorgehensweisen für die Verwendung von Bereitstellungs-IDs.

Schritt 4: App registrieren

Sie können Ihre Anwendung über die Google Cloud Console registrieren. Auf dem App-Registrierungsbildschirm geben Sie den Namen, die Avatar-URL und die Beschreibung der App ein. Zum Testen können Sie die Option „App kann direkt Nachrichten senden“ und „App funktioniert in Gruppenbereichen mit mehreren Nutzern“ aktivieren. Wählen Sie in den Verbindungseinstellungen „Apps Script“ aus und fügen Sie die Deployment-ID ein, die Sie im vorherigen Schritt kopiert haben.

Verbindungseinstellungen zum Registrieren Ihrer App.

Schritt 5: App testen

Zum Testen Ihrer App können Sie eine DN mit ihr starten oder sie in einem Gruppenbereich @erwähnen. Wenn Sie mit ihm sprechen, reagiert er auf die Antwort in Schritt 2. Fertig!

Konzepte von Apps Script

Veranstaltungen

Apps Script unterstützt mehrere Event-Handler-Funktionen, die in Ihrer App implementiert werden können. Jede Funktion verarbeitet einen anderen Ereignistyp und jede Funktion erhält ein einzelnes Argument e, bei dem es sich um ein Ereignisobjekt handelt.

onAddToSpace(e): Diese Funktion wird ausgeführt, wenn Ihre App einem Gruppenbereich hinzugefügt wird. Ihre Anwendung kann entweder direkt dem Gruppenbereich oder über eine @Erwähnung hinzugefügt werden. Im zweiten Fall hat das Ereignis e auch eine message-Property. Diese Funktion sollte ein Message-Objekt zurückgeben. Dies ist normalerweise eine Begrüßungsnachricht, mit der Endnutzer über Ihre Anwendung oder eine Antwort auf die @Erwähnung informiert werden.
onMessage(e): Diese Funktion wird aufgerufen, wenn sich deine App bereits im Gruppenbereich befindet und der Nutzer sie @erwähnt. Sie sollte ein Message-Objekt zurückgeben, das die Antwort deiner App enthält.
onRemoveFromSpace(e): Diese Funktion wird aufgerufen, wenn der Nutzer deine App aus der DN-Liste oder aus einem Gruppenbereich entfernt. Der Rückgabewert dieser Funktion wird ignoriert, da Ihre Anwendung entfernt wurde und keine weiteren Nachrichten mehr senden kann.

Im folgenden Beispiel werden onAddToSpace und onRemoveFromSpace implementiert:

// onAddToSpace() is invoked when the app is added to a space or when
// a user initiates / re-initiates a direct message with the app.
function onAddToSpace(e) {
  if (!e.space.singleUserBotDm) {
    return { 'text': 'Thanks for adding me to "' +
        (e.space.displayName ? e.space.displayName : "this chat") + '"!' };
  } else {
    return { 'text': 'Thanks for adding me to a DM!' };
  }
}
// onRemoveFromSpace() is invoked when app is removed from a space
// or when a user removes a direct message with the app.
function onRemoveFromSpace(e) {}

Beachten Sie, dass e.space.displayName in Direktnachrichten zwischen Menschen möglicherweise nicht vorhanden ist.

Interaktive Karten

Wie andere Apps können auch Apps Script-Karten interaktiv sein. In der Dokumentation zu interaktiven Karten erfahren Sie, wie Sie Karten interaktiv gestalten. Der Hauptunterschied bei Apps Script-Anwendungen besteht darin, dass sie eine bestimmte Methode angeben können, die ausgelöst werden soll, wenn das „ onClick“-Ereignis ausgelöst wird, indem sie Schlüssel/Wert-Paare von „action.actionMethodName“ und „action.parameters“ als Methodenparameter verwenden.

Autorisierung

Apps Script-Anwendungen, die auf geschützte Ressourcen zugreifen, müssen Nutzer bei der ersten Ausführung für jeden Nutzer um Autorisierung bitten. Dazu müssen Sie nichts weiter tun, aber den Nutzern wird bei der ersten Verwendung Ihrer Anwendung möglicherweise ein Autorisierungsdialog angezeigt.

Apps Script verarbeitet die Autorisierung auf Skriptebene. Anwendungen, die eine Autorisierung benötigen, können erst dann Aktionen ausführen, wenn der Endnutzer sie autorisiert hat. Wenn Ihre App eine Begrüßungsnachricht anzeigen soll, obwohl sie nicht autorisiert wurde, und sie einem Gruppenbereich direkt hinzugefügt wird, können Sie im Manifest eine Fallback-Nachricht angeben. Wenn Ihre Anwendung eine Initialisierungslogik erfordert, müssen Sie diese Logik möglicherweise in der Aktion onMessage duplizieren. Beispiel:

function onMessage(event) {
  var userProperties = PropertiesService.getUserProperties();
  if (!userProperties.getProperty('initialized')) {
    // handle the onAddToSpace initialization logic here.
    ...
    userProperties.setProperties({initialized: 'true'});
  }
  // Handle normal onMessage logic.
  ...
}

Asynchrone Nachrichten

Einige Anwendungen müssen Nachrichten möglicherweise aufgrund eines externen Triggers an Google Chat senden, z. B. einen zeitgesteuerten Trigger in Apps Script.

Für diesen Anwendungsfall planen wir, die Google Chat API nativ in Apps Script zu integrieren. In der Zwischenzeit kann dies derzeit nur über die externe HTTP API erreicht werden (siehe Dokumentation). Dazu ist die Verwendung eines Cloud-Dienstkontos (siehe Dokumentation) über die OAuth2-Bibliothek für Apps Script erforderlich.

Die folgende vollständige Beispiel-App, die jede Minute eine Nachricht in jedem Gruppenbereich postet, in dem sie sich befindet:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute via the
// "Edit > Current Project's Triggers" menu. When it runs, it will
// post in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

Manifestdatei

Das folgende Beispiel zeigt die Manifestdatei des Apps Script, die zusammen mit Ihrem Skript verwendet werden muss.

Wenn Sie Ihr Projekt nicht über die Chatvorlage gestartet haben, müssen Sie die Manifestdatei bearbeiten, um das Objekt "chat": {} hinzuzufügen.

Legen Sie in der Manifestdatei die Laufzeit auf Rhino fest: "runtimeVersion": "DEPRECATED_ES5". Chat-Apps unterstützen die Apps Script V8-Laufzeit nicht vollständig. Wenn Sie also "runtimeVersion": "V8" angeben, kann die Chat-App einen Fehler verursachen. Beispielsweise kann sich die JSON-Antwortstruktur auf unvorhersehbare Weise für Chat-Anwendungen ändern, die mit der V8-Laufzeit erstellt wurden.

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "chat": {
    "addToSpaceFallbackMessage": "Thank you for adding me!"
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "DEPRECATED_ES5"
}

Es ist möglich, dass ein Nutzer Ihre App einem Gruppenbereich hinzufügt, bevor er Ihre App autorisiert. In diesem Fall kann Ihre App nicht auf das Ereignis zum Hinzufügen von Gruppenbereichen reagieren. In diesem Fall können Sie im Feld addToSpaceFallbackMessage eine Willkommensnachricht eingeben.

Die Manifestdatei heißt appsscript.json und ist Teil Ihres Apps Script-Projekts. Wählen Sie Ansicht > Manifestdatei anzeigen aus, um die Manifestdatei im Apps Script-Editor anzusehen.