Erweiterter Chatdienst

Mit dem erweiterten Chat-Dienst können Sie die Google Chat API in Apps Script verwenden. Mit dieser API können Skripts Chat-Gruppenbereiche suchen, erstellen und ändern, Mitglieder zu Gruppenbereichen hinzufügen oder daraus entfernen sowie Nachrichten mit Text, Karten, Anhängen und Reaktionen lesen oder posten.

Vorbereitung

• Eine in der Google Cloud Console auf der Seite zur Chat API-Konfiguration konfigurierte Google Chat-App, die auf Apps Script basiert. Das Apps Script-Projekt der App muss ein Standard-Google Cloud-Projekt verwenden und nicht das Standardprojekt, das automatisch für Apps Script-Projekte erstellt wird. Informationen zum Erstellen einer kompatiblen Google Chat-App finden Sie unter Google Chat-App mit Google Apps Script erstellen.
• Für die Chat-App konfigurierte Authentifizierung. Wenn eine Aktion im Namen eines Nutzers ausgeführt werden soll, ist eine Nutzerauthentifizierung erforderlich. Wenn eine Aktion als Chat-App ausgeführt wird, ist eine App-Authentifizierung mit einem Dienstkonto erforderlich. Informationen dazu, welche Form der Authentifizierung von einer Chat API-Methode unterstützt wird, finden Sie unter Arten der erforderlichen Authentifizierung für Google Chat API-Aufrufe.

Referenz

Weitere Informationen zu diesem Dienst finden Sie in der Referenzdokumentation zur Chat API. Wie alle erweiterten Dienste in Apps Script verwendet der Chat-Dienst dieselben Objekte, Methoden und Parameter wie die öffentliche API.

Beispielcode

In diesen Beispielen wird gezeigt, wie Sie mit dem erweiterten Dienst häufige Google Chat API-Aktionen ausführen.

Nachricht mit Nutzeranmeldedaten posten

Das folgende Beispiel zeigt, wie Sie im Namen des Nutzers eine Nachricht in einem Chatbereich posten.

1. Fügen Sie der Datei appsscript.json des Apps Script-Projekts den Autorisierungsbereich chat.messages.create hinzu:

   "oauthScopes": [
     "https://www.googleapis.com/auth/chat.messages.create"
   ]
   

2. Fügen Sie dem Code des Apps Script-Projekts eine Funktion wie diese hinzu:

   advanced/chat.gs

   Auf GitHub ansehen
   /**
    * Posts a new message to the specified space on behalf of the user.
    * @param {string} spaceName The resource name of the space.
    */
   function postMessageWithUserCredentials(spaceName) {
     try {
       const message = {'text': 'Hello world!'};
       Chat.Spaces.Messages.create(message, spaceName);
     } catch (err) {
       // TODO (developer) - Handle exception
       console.log('Failed to create message with error %s', err.message);
     }
   }

Nachricht mit App-Anmeldedaten posten

Im folgenden Beispiel wird gezeigt, wie Sie im Namen der App eine Nachricht in einen Chat-Bereich posten. Wenn Sie den erweiterten Chat-Dienst mit einem Dienstkonto verwenden, müssen Sie keine Autorisierungsbereiche in appsscript.json angeben. Weitere Informationen zur Authentifizierung mit Dienstkonten finden Sie unter Als Google Chat-App authentifizieren.

/**
 * Posts a new message to the specified space on behalf of the app.
 * @param {string} spaceName The resource name of the space.
 */
function postMessageWithAppCredentials(spaceName) {
  try {
    // See https://developers.google.com/chat/api/guides/auth/service-accounts
    // for details on how to obtain a service account OAuth token.
    const appToken = getToken_();
    const message = {'text': 'Hello world!'};
    Chat.Spaces.Messages.create(
        message,
        spaceName,
        {},
        // Authenticate with the service account token.
        {'Authorization': 'Bearer ' + appToken});
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to create message with error %s', err.message);
  }
}

Gruppenbereich erstellen

Das folgende Beispiel zeigt, wie Sie Informationen zu einem Chatbereich abrufen.

1. Fügen Sie der Datei appsscript.json des Apps Script-Projekts den Autorisierungsbereich chat.spaces.readonly hinzu:

   "oauthScopes": [
     "https://www.googleapis.com/auth/chat.spaces.readonly"
   ]
   

2. Fügen Sie dem Code des Apps Script-Projekts eine Funktion wie diese hinzu:

   advanced/chat.gs

   Auf GitHub ansehen
   /**
    * Gets information about a Chat space.
    * @param {string} spaceName The resource name of the space.
    */
   function getSpace(spaceName) {
     try {
       const space = Chat.Spaces.get(spaceName);
       console.log('Space display name: %s', space.displayName);
       console.log('Space type: %s', space.spaceType);
     } catch (err) {
       // TODO (developer) - Handle exception
       console.log('Failed to get space with error %s', err.message);
     }
   }

Gruppenbereich erstellen

Im folgenden Beispiel wird gezeigt, wie Sie einen Chat-Gruppenbereich erstellen.

1. Fügen Sie der Datei appsscript.json des Apps Script-Projekts den Autorisierungsbereich chat.spaces.create hinzu:

   "oauthScopes": [
     "https://www.googleapis.com/auth/chat.spaces.create"
   ]
   

2. Fügen Sie dem Code des Apps Script-Projekts eine Funktion wie diese hinzu:

   advanced/chat.gs

   Auf GitHub ansehen
   /**
    * Creates a new Chat space.
    */
   function createSpace() {
     try {
       const space = {'displayName': 'New Space', 'spaceType': 'SPACE'};
       Chat.Spaces.create(space);
     } catch (err) {
       // TODO (developer) - Handle exception
       console.log('Failed to create space with error %s', err.message);
     }
   }

Mitgliedschaften auflisten

Im folgenden Beispiel wird gezeigt, wie Sie alle Mitglieder eines Chatbereichs auflisten.

1. Fügen Sie der Datei appsscript.json des Apps Script-Projekts den Autorisierungsbereich chat.memberships.readonly hinzu:

   "oauthScopes": [
     "https://www.googleapis.com/auth/chat.memberships.readonly"
   ]
   

2. Fügen Sie dem Code des Apps Script-Projekts eine Funktion wie diese hinzu:

   advanced/chat.gs

   Auf GitHub ansehen
   /**
    * Lists all the members of a Chat space.
    * @param {string} spaceName The resource name of the space.
    */
   function listMemberships(spaceName) {
     let response;
     let pageToken = null;
     try {
       do {
         response = Chat.Spaces.Members.list(spaceName, {
           pageSize: 10,
           pageToken: pageToken
         });
         if (!response.memberships || response.memberships.length === 0) {
           pageToken = response.nextPageToken;
           continue;
         }
         response.memberships.forEach((membership) => console.log(
             'Member resource name: %s (type: %s)',
             membership.name,
             membership.member.type));
         pageToken = response.nextPageToken;
       } while (pageToken);
     } catch (err) {
       // TODO (developer) - Handle exception
       console.log('Failed with error %s', err.message);
     }
   }

Fehlerbehebung

Wenn Sie auf Error 400: invalid_scope mit der Fehlermeldung Some requested scopes cannot be shown stoßen, haben Sie im Apps Script-Projekt in der Datei appsscript.json keine Autorisierungsbereiche angegeben. In den meisten Fällen ermittelt Apps Script automatisch, welche Bereiche ein Skript benötigt. Wenn Sie jedoch den erweiterten Chat-Dienst verwenden, müssen Sie die Autorisierungsbereiche, die Ihr Skript verwendet, manuell der Manifestdatei Ihres Apps Script-Projekts hinzufügen. Weitere Informationen finden Sie unter Explizite Bereiche festlegen.

Fügen Sie die entsprechenden Autorisierungsbereiche in die Datei appsscript.json des Apps Script-Projekts als Teil des Arrays oauthScopes ein, um den Fehler zu beheben. Wenn Sie beispielsweise die Methode spaces.messages.create aufrufen möchten, fügen Sie Folgendes hinzu:

"oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

Einschränkungen und Überlegungen

Der erweiterte Chatdienst unterstützt Folgendes nicht:

• Die Chat API-Methode media.download.
• Chat API-Methoden in der Entwicklervorschau verfügbar

Verwenden Sie stattdessen UrlFetchApp, um einen Nachrichtenanhang herunterzuladen oder eine Developer Preview-Methode aufzurufen.