Google Workspace-Abo erstellen

Auf dieser Seite wird beschrieben, wie Sie mit der Google Workspace Events API ein Abo für eine Google Workspace-Ressource erstellen. Mit einem Google Workspace-Abo kann Ihre App Informationen zu Google Workspace-Ereignissen empfangen, die Änderungen an einer Google Workspace-Ressource darstellen. Informationen dazu, welche Ressourcen und Ereignistypen die Google Workspace Events API unterstützt, finden Sie in der Übersicht über die Google Workspace Events API.

Diese Seite enthält die folgenden Schritte zum Erstellen eines Google Workspace-Abos:

  1. die Umgebung einrichten
  2. Google Cloud Pub/Sub-Thema erstellen und abonnieren Verwenden Sie dieses Dokument als Endpunkt, um Google Workspace-Ereignisse zu empfangen.
  3. Rufen Sie die Methode create der Google Workspace Events API für die Ressource Subscription auf.
  4. Testen Sie Ihr Google Workspace-Abo, um zu prüfen, ob Ihr Pub/Sub-Thema Ereignisse empfängt, die Sie abonniert haben.
  5. Optional können Sie konfigurieren, wie Ereignisse an einen Endpunkt für Ihre App gesendet werden, damit Ihre App das Ereignis verarbeiten und gegebenenfalls Maßnahmen ergreifen kann.

Vorbereitung

Apps Script

  • So verwenden Sie die Google Cloud CLI-Befehle in dieser Anleitung:
    1. Installieren Sie die Google Cloud CLI.
    2. Führen Sie den folgenden Code aus, um die gcloud-Befehlszeile zu initialisieren:
      3.   gcloud init
  • Ein Apps Script-Projekt:
    • Verwenden Sie Ihr Google Cloud-Projekt anstelle des Standardprojekts, das automatisch von Apps Script erstellt wird.
    • Alle Bereiche, die Sie zur Konfiguration des OAuth-Zustimmungsbildschirms hinzugefügt haben, müssen Sie auch der Datei appsscript.json in Ihrem Apps Script-Projekt hinzufügen. Wenn Sie beispielsweise den Bereich chat.messages angegeben haben, fügen Sie Folgendes hinzu: 
      • "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages"
]
    • Aktivieren Sie den erweiterten Dienst Google Workspace Events.
  • Ein Google Cloud-Projekt mit aktivierter Abrechnung. Für Abos für Google Chat müssen Sie außerdem die Chat API in Ihrem Cloud-Projekt aktivieren und die Felder App-Name, Avatar-URL und Beschreibung konfigurieren. Weitere Informationen finden Sie unter Google Chat-App erstellen.
  • Erfordert eine Authentifizierung und einen geeigneten Autorisierungsbereich für jeden Ereignistyp im Abo:
    • In der Regel ist eine Nutzerauthentifizierung mit dem für die App konfigurierten OAuth-Zustimmungsbildschirm erforderlich. Wenn Sie den Zustimmungsbildschirm konfigurieren, müssen Sie einen Bereich angeben, der jeden Ereignistyp für das Abo unterstützt. Informationen zum Konfigurieren des Zustimmungsbildschirms und zum Identifizieren der erforderlichen Bereiche finden Sie unter Bereiche auswählen.
    • Für das Abonnieren eines Chat-Ereignisses als Chat-App ist eine App-Authentifizierung mit einmaliger Administratorgenehmigung erforderlich.

Python

  • Python 3.6 oder höher
  • Das Paketverwaltungstool pip
  • Die neuesten Google-Clientbibliotheken für Python. Führen Sie den folgenden Befehl in Ihrer Befehlszeile aus, um sie zu installieren oder zu aktualisieren: 
      pip3 install --upgrade google-api-python-client google-auth-oauthlib
  • So verwenden Sie die Google Cloud CLI-Befehle in dieser Anleitung:
    1. Installieren Sie die Google Cloud CLI.
    2. Führen Sie den folgenden Code aus, um die gcloud-Befehlszeile zu initialisieren:
      3.   gcloud init
  • Ein Google Cloud-Projekt mit aktivierter Abrechnung. Für Abos für Google Chat müssen Sie außerdem die Chat API in Ihrem Cloud-Projekt aktivieren und die Felder App-Name, Avatar-URL und Beschreibung konfigurieren. Weitere Informationen finden Sie unter Google Chat-App erstellen.
  • Erfordert eine Authentifizierung und einen entsprechenden Autorisierungsbereich für jeden Ereignistyp im Abo:
    • In der Regel ist eine Nutzerauthentifizierung mit dem für die App konfigurierten OAuth-Zustimmungsbildschirm erforderlich. Wenn Sie den Zustimmungsbildschirm konfigurieren, müssen Sie einen Bereich angeben, der jeden Ereignistyp für das Abo unterstützt. Informationen zum Konfigurieren des Zustimmungsbildschirms und zum Identifizieren der erforderlichen Bereiche finden Sie unter Bereiche auswählen.
    • Für das Abonnieren eines Chat-Ereignisses als Chat-App ist eine App-Authentifizierung mit einmaliger Administratorgenehmigung erforderlich.

Umgebung einrichten

Im folgenden Abschnitt wird erläutert, wie Sie Ihre Umgebung einrichten, bevor Sie ein Google Workspace-Abo erstellen.

Google Workspace Events API und Google Cloud Pub/Sub API aktivieren

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.

Google Cloud Console

Öffnen Sie in der Google Cloud Console das Google Cloud-Projekt für Ihre Anwendung und aktivieren Sie die Google Workspace Events API und die Pub/Sub API:

APIs aktivieren

gcloud

  1. Melden Sie sich in Ihrem Arbeitsverzeichnis in Ihrem Google-Konto an:

    gcloud auth login

  2. Legen Sie das Cloud-Projekt für Ihre Anwendung fest:

    gcloud config set project PROJECT_ID

    Ersetzen Sie PROJECT_ID durch die Projekt-ID des Cloud-Projekts für Ihre Anwendung.

  3. Aktivieren Sie die Google Workspace Events API und die Google Cloud Pub/Sub API:

    gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com

OAuth-Client-ID-Anmeldedaten erstellen

Wählen Sie Ihren Anwendungstyp aus, um eine Anleitung zum Erstellen einer OAuth-Client-ID zu erhalten:

Webanwendung

  1. Öffnen Sie in der Google Cloud Console das Menü  > Google Auth-Plattform > Clients.

    Zu „Clients“

  2. Klicken Sie auf Client erstellen.
  3. Klicken Sie auf Anwendungstyp > Webanwendung.
  4. Geben Sie im Feld Name einen Namen für die Anmeldedaten ein. Dieser Name wird nur in der Google Cloud Console angezeigt.
  5. Fügen Sie autorisierte URIs für Ihre App hinzu:
    • Clientseitige Anwendungen (JavaScript): Klicken Sie unter Autorisierte JavaScript-Quellen auf URI hinzufügen. Geben Sie dann einen URI für Browseranfragen ein. Damit werden die Domains identifiziert, von denen Ihre Anwendung API-Anfragen an den OAuth 2.0-Server senden kann.
    • Serverseitige Apps (Java, Python usw.): Klicken Sie unter Autorisierte Weiterleitungs-URIs auf URI hinzufügen. Geben Sie dann einen Endpunkt-URI ein, an den der OAuth 2.0-Server Antworten senden kann.
  6. Optional: Wenn Ihre App ein KI-Agent ist, der Aktionen im Namen von Nutzern ausführt, wählen Sie Diesen Client für einen KI-basierten Agenten verwenden aus. Wenn Ihre App sowohl KI-Agent-Workflows als auch Standardnutzerfunktionen unterstützt, erstellen Sie für jeden einen separaten OAuth-Client. Sie können diese Einstellung nach dem Erstellen des Clients nicht mehr ändern.
  7. Klicken Sie auf Erstellen.

    Die neu erstellten Anmeldedaten werden unter OAuth 2.0-Client-IDs angezeigt.

    Clientschlüssel werden nicht für Webanwendungen verwendet.

Android

  1. Öffnen Sie in der Google Cloud Console das Menü  > Google Auth-Plattform > Clients.

    Zu „Clients“

  2. Klicken Sie auf Client erstellen.
  3. Klicken Sie auf Anwendungstyp > Android.
  4. Geben Sie im Feld Name einen Namen für die Anmeldedaten ein. Dieser Name wird nur in der Google Cloud Console angezeigt.
  5. Geben Sie im Feld Paketname den Paketnamen aus der Datei AndroidManifest.xml ein.
  6. Geben Sie im Feld SHA-1-Zertifikat-Fingerabdruck den generierten SHA-1-Zertifikat-Fingerabdruck ein.
  7. Optional: Wenn Ihre App ein KI-Agent ist, der Aktionen im Namen von Nutzern ausführt, wählen Sie Diesen Client für einen KI-basierten Agenten verwenden aus. Wenn Ihre App sowohl KI-Agent-Workflows als auch Standardnutzerfunktionen unterstützt, erstellen Sie für jeden einen separaten OAuth-Client. Sie können diese Einstellung nach dem Erstellen des Clients nicht mehr ändern.
  8. Klicken Sie auf Erstellen.

    Die neu erstellten Anmeldedaten werden unter „OAuth 2.0-Client-IDs“ angezeigt.

iOS

  1. Öffnen Sie in der Google Cloud Console das Menü  > Google Auth-Plattform > Clients.

    Zu „Clients“

  2. Klicken Sie auf Client erstellen.
  3. Klicken Sie auf Anwendungstyp > iOS.
  4. Geben Sie im Feld Name einen Namen für die Anmeldedaten ein. Dieser Name wird nur in der Google Cloud Console angezeigt.
  5. Geben Sie im Feld Paket-ID den Paket-Identifikator ein, der in der Datei Info.plist der App aufgeführt ist.
  6. Optional: Wenn Ihre App im Apple App Store verfügbar ist, geben Sie die App Store-ID ein.
  7. Optional: Geben Sie im Feld Team-ID den eindeutigen 10-stelligen String ein, der von Apple generiert und Ihrem Team zugewiesen wurde.
  8. Optional: Wenn Ihre App ein KI-Agent ist, der Aktionen im Namen von Nutzern ausführt, wählen Sie Diesen Client für einen KI-basierten Agenten verwenden aus. Wenn Ihre App sowohl KI-Agent-Workflows als auch Standardnutzerfunktionen unterstützt, erstellen Sie für jeden einen separaten OAuth-Client. Sie können diese Einstellung nach dem Erstellen des Clients nicht mehr ändern.
  9. Klicken Sie auf Erstellen.

    Die neu erstellten Anmeldedaten werden unter „OAuth 2.0-Client-IDs“ angezeigt.

Chrome App

  1. Öffnen Sie in der Google Cloud Console das Menü  > Google Auth-Plattform > Clients.

    Zu „Clients“

  2. Klicken Sie auf Client erstellen.
  3. Klicken Sie auf Anwendungstyp > Chrome-Erweiterung.
  4. Geben Sie im Feld Name einen Namen für die Anmeldedaten ein. Dieser Name wird nur in der Google Cloud Console angezeigt.
  5. Geben Sie im Feld Artikel-ID die eindeutige 32-stellige ID-Zeichenfolge Ihrer App ein. Sie finden diese ID in der Chrome Web Store-URL Ihrer App und im Chrome Web Store-Entwickler-Dashboard.
  6. Optional: Wenn Ihre App ein KI-Agent ist, der Aktionen im Namen von Nutzern ausführt, wählen Sie Diesen Client für einen KI-basierten Agenten verwenden aus. Wenn Ihre App sowohl KI-Agent-Workflows als auch Standardnutzerfunktionen unterstützt, erstellen Sie für jeden einen separaten OAuth-Client. Sie können diese Einstellung nach dem Erstellen des Clients nicht mehr ändern.
  7. Klicken Sie auf Erstellen.

    Die neu erstellten Anmeldedaten werden unter „OAuth 2.0-Client-IDs“ angezeigt.

Desktop-Anwendung

  1. Öffnen Sie in der Google Cloud Console das Menü  > Google Auth-Plattform > Clients.

    Zu „Clients“

  2. Klicken Sie auf Client erstellen.
  3. Klicken Sie auf Anwendungstyp > Desktop-Anwendung.
  4. Geben Sie im Feld Name einen Namen für die Anmeldedaten ein. Dieser Name wird nur in der Google Cloud Console angezeigt.
  5. Optional: Wenn Ihre App ein KI-Agent ist, der Aktionen im Namen von Nutzern ausführt, wählen Sie Diesen Client für einen KI-basierten Agenten verwenden aus. Wenn Ihre App sowohl KI-Agent-Workflows als auch Standardnutzerfunktionen unterstützt, erstellen Sie für jeden einen separaten OAuth-Client. Sie können diese Einstellung nach dem Erstellen des Clients nicht mehr ändern.
  6. Klicken Sie auf Erstellen.

    Die neu erstellten Anmeldedaten werden unter „OAuth 2.0-Client-IDs“ angezeigt.

Fernsehgeräte und Geräte mit begrenzter Eingabe

  1. Öffnen Sie in der Google Cloud Console das Menü  > Google Auth-Plattform > Clients.

    Zu „Clients“

  2. Klicken Sie auf Client erstellen.
  3. Klicken Sie auf Anwendungstyp > Fernseher und Geräte mit eingeschränkter Eingabe.
  4. Geben Sie im Feld Name einen Namen für die Anmeldedaten ein. Dieser Name wird nur in der Google Cloud Console angezeigt.
  5. Optional: Wenn Ihre App ein KI-Agent ist, der Aktionen im Namen von Nutzern ausführt, wählen Sie Diesen Client für einen KI-basierten Agenten verwenden aus. Wenn Ihre App sowohl KI-Agent-Workflows als auch Standardnutzerfunktionen unterstützt, erstellen Sie für jeden einen separaten OAuth-Client. Sie können diese Einstellung nach dem Erstellen des Clients nicht mehr ändern.
  6. Klicken Sie auf Erstellen.

    Die neu erstellten Anmeldedaten werden unter „OAuth 2.0-Client-IDs“ angezeigt.

Universal Windows Platform (UWP)

  1. Öffnen Sie in der Google API Console das Menü  > > Clients.

    Zu „Clients“

  2. Klicken Sie auf Client erstellen.
  3. Klicken Sie auf Anwendungstyp > Universelle Windows-Plattform (UWP).
  4. Geben Sie im Feld „Name“ einen Namen für die Anmeldedaten ein. Dieser Name wird nur in der Google API Console angezeigt.
  5. Geben Sie im Feld „Store-ID“ die eindeutige 12-stellige Microsoft Store-ID Ihrer App ein. Sie finden diese ID in der Microsoft Store-URL Ihrer App und im Partnercenter.
  6. Optional: Wenn Ihre App ein KI-Agent ist, der Aktionen im Namen von Nutzern ausführt, wählen Sie Diesen Client für einen KI-basierten Agenten verwenden aus. Wenn Ihre App sowohl KI-Agent-Workflows als auch Standardnutzerfunktionen unterstützt, erstellen Sie für jeden einen separaten OAuth-Client. Sie können diese Einstellung nach dem Erstellen des Clients nicht mehr ändern.
  7. Klicken Sie auf Erstellen.

    Die neu erstellten Anmeldedaten werden unter „OAuth 2.0-Client-IDs“ angezeigt.

JSON-Datei mit dem Clientschlüssel herunterladen

Die Clientschlüsseldatei ist eine JSON-Darstellung der Anmeldedaten für die OAuth-Client-ID, auf die Ihre Anwendung beim Bereitstellen von Anmeldedaten verweisen kann.

  1. Öffnen Sie in der Google API Console das Menü  > APIs und Dienste > Anmeldedaten.

    Zu den Anmeldedaten

  2. Klicken Sie unter OAuth 2.0-Client-IDs auf die von Ihnen erstellte Client-ID.

  3. Klicken Sie auf JSON herunterladen.

  4. Speichern Sie die Datei als credentials.json.

Pub/Sub-Thema erstellen und abonnieren

In diesem Abschnitt erstellen Sie ein Pub/Sub-Thema und ein Abo für das Thema. Ihr Pub/Sub-Thema dient als Benachrichtigungsendpunkt, an dem Ihr Google Workspace-Abo Ereignisse empfängt.

Weitere Informationen zum Erstellen und Verwalten von Pub/Sub-Themen finden Sie in der Pub/Sub-Dokumentation.

So erstellen und abonnieren Sie ein Pub/Sub-Thema:

Google API-Konsole

  1. Rufen Sie in der Google API Console die Pub/Sub-Seite auf:

    Zu Google Cloud Pub/Sub

    Achten Sie darauf, dass das Cloud-Projekt für Ihre App ausgewählt ist.

  2. Klicken Sie auf Thema erstellen und gehen Sie so vor:

    1. Geben Sie einen Namen für das Thema ein, z. B. workspace-events-topic.
    2. Lassen Sie die Option Standardabo hinzufügen ausgewählt. Pub/Sub benennt dieses Standardabo ähnlich wie Ihr Thema, z. B. workspace-events-topic-sub.
    3. Optional: Aktualisieren oder konfigurieren Sie zusätzliche Attribute für Ihr Thema.

  3. Klicken Sie auf Erstellen. Der vollständige Themenname hat das Format projects/PROJECT_ID/topics/TOPIC_ID. Verwenden Sie diesen vollständigen Namen in einem späteren Schritt.

  4. Gewähren Sie Zugriff, um Pub/Sub-Nachrichten in Ihrem Thema zu veröffentlichen:

    1. Rufen Sie auf der Seite Ihres Themas die Seitenleiste auf und öffnen Sie den Tab Berechtigungen.
    2. Klicken Sie auf Hauptkonto hinzufügen.
    3. Fügen Sie im Feld Hauptkonten hinzufügen das Dienstkonto für die Google Workspace-Anwendung hinzu, die Ereignisse an Ihr Abo liefert:
      1. Für Chat-Ereignisse: chat-api-push@system.gserviceaccount.com.
      2. Für Drive-Ereignisse: drive-api-event-push@system.gserviceaccount.com.
      3. Für Meet-Ereignisse: meet-api-event-push@system.gserviceaccount.com.
    4. Wählen Sie im Menü Rollen zuweisen die Option Pub/Sub Publisher aus.
    5. Klicken Sie auf Speichern. Es kann einige Minuten dauern, bis die Berechtigungen für Ihr Thema aktualisiert sind.

gcloud

  1. Erstellen Sie in Ihrem Cloud-Projekt ein Thema, indem Sie den folgenden Befehl ausführen:

    gcloud pubsub topics create TOPIC_ID

    Ersetzen Sie TOPIC_ID durch eine eindeutige ID für Ihr Thema, z. B. workspace-events-topic.

    In der Ausgabe wird der vollständige Themenname im Format projects/PROJECT_ID/topics/TOPIC_ID angezeigt. Notieren Sie sich den Namen und achten Sie darauf, dass der Wert für PROJECT_ID die Cloud-Projekt-ID für Ihre App ist. Verwenden Sie den Themennamen im folgenden Schritt und erstellen Sie später das Google Workspace-Abo.

  2. Gewähren Sie Zugriff zum Veröffentlichen von Nachrichten in Ihrem Thema:

    gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'

    Ersetzen Sie Folgendes:

    • TOPIC_NAME: Der vollständige Themenname, der die Ausgabe des vorherigen Schritts ist. Formatiert als projects/PROJECT_ID/topics/TOPIC_ID.

    • GOOGLE_WORKSPACE_APPLICATION: Die Google Workspace-Anwendung, die Ereignisse an Ihr Abo senden muss:

      • Verwenden Sie eines der folgenden Dienstkonten, um Ereignisse von Google Chat zu erhalten:
      • Verwenden Sie drive-api-event-push@system.gserviceaccount.com, um Ereignisse von Drive zu empfangen.
      • Verwenden Sie meet-api-event-push@system.gserviceaccount.com, um Ereignisse von Meet zu empfangen.

    Es kann einige Minuten dauern, bis die Berechtigungen für Ihr Thema aktualisiert sind.

  3. Erstellen Sie ein Pub/Sub-Abo für das Thema:

     gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

    Ersetzen Sie Folgendes:

    • SUBSCRIPTION_NAME: Ein Name für Ihr Abo, z. B. workspace-events-subscription.
    • TOPIC_NAME: Der Name des Themas, das Sie im vorherigen Schritt erstellt haben.

Google Workspace-Ressource abonnieren

In diesem Abschnitt abonnieren Sie die Google Workspace-Ressource, die Sie auf Ereignisse überwachen möchten.

Zielressource auswählen und identifizieren

In einem Google Workspace-Abo ist die Zielressource die Google Workspace-Ressource, die Sie auf Ereignisse überwachen. Die Zielressource wird im Feld targetResource des Abos dargestellt und mit dem vollständigen Ressourcennamen formatiert. Bei einem Abo, das einen Chatbereich (spaces/AAAABBBBBBB) überwacht, ist der Wert von targetResource beispielsweise //chat.googleapis.com/spaces/AAAABBBBBBB.

Zielressource für Chat identifizieren

Zielressource Format Einschränkungen
Leerzeichen

//chat.googleapis.com/spaces/SPACE

Dabei ist SPACE die ID im Ressourcennamen der Chat API-Ressource space. Sie können die ID aus der URL des Gruppenbereichs oder mit der Methode spaces.list() abrufen.

 Der Chat-Nutzer oder die Chat-App, die das Abo autorisiert, muss über sein Google Workspace- oder Google-Konto Mitglied des Gruppenbereichs sein. Unterstützt:
Alle Spaces für einen Nutzer

//chat.googleapis.com/spaces/-

 Das Abo empfängt nur Ereignisse für die Gruppenbereiche, in denen der Nutzer über sein Google Workspace- oder Google-Konto Mitglied ist. Unterstützt nur die Nutzerauthentifizierung.
Nutzer

//cloudidentity.googleapis.com/users/USER

Dabei ist USER die ID im Ressourcennamen der Chat API-Ressource user. Weitere Informationen finden Sie unter Google Chat-Nutzer identifizieren und angeben.

Das Abo empfängt nur Ereignisse zu dem Nutzer, der das Abo autorisiert hat. Ein Nutzer kann ein Abo nicht im Namen anderer Nutzer autorisieren. Unterstützt nur die Nutzerauthentifizierung.
Kunde ( Entwicklervorschau)

//admin.googleapis.com/customers/CUSTOMER

Dabei ist CUSTOMER die Kundennummer. Sie können auch den Alias my_customer für die benutzerdefinierte Domain der Chat-App verwenden.

Das Abo empfängt Ereignisse für alle Gruppenbereiche und Nutzer, die von der Kundendomain verwaltet werden. Unterstützt nur die App-Authentifizierung mit Administratorgenehmigung.

Zielressource für Drive identifizieren

Zielressource Format Einschränkungen (falls zutreffend)
Datei //drive.googleapis.com/files/FILE

Dabei ist FILE die ID im Ressourcennamen der Drive API-Ressource files. Sie können die ID aus der URL der Datei oder mit der Methode files.list abrufen.

Der Nutzer, der das Abo autorisiert, muss die Berechtigung für die Datei im Abo haben, die sich auf das Ereignis bezieht, das abonniert werden soll.
Geteilte Ablage //drive.googleapis.com/drives/DRIVE

Dabei ist DRIVE die ID im Ressourcennamen der Drive API-Ressource drives. Sie können die ID über die URL des Laufwerks oder mit der Methode drives.list abrufen.

Das Abo empfängt nur Ereignisse für Elemente in der geteilten Ablage, in der der Nutzer über sein Google Workspace-Konto oder Google-Konto Mitglied ist.

Zielressource für Meet identifizieren

Zielressource Format Einschränkungen (falls zutreffend)
Konferenzraum //meet.googleapis.com/spaces/SPACE

Dabei ist SPACE die ID im Ressourcennamen der Meet REST API-Ressource spaces. Weitere Informationen finden Sie unter So identifiziert Meet einen Konferenzraum.
Nutzer //cloudidentity.googleapis.com/users/USER

Dabei ist USER die ID im Feld signedinUser.user der Meet REST API-Ressource participants. Weitere Informationen finden Sie unter Mit Teilnehmern arbeiten.

Das Abo empfängt Ereignisse zu allen Konferenzräumen, deren Inhaber der Nutzer ist. In der Regel ist der Inhaber des Konferenzraums auch der Organisator des Google Kalender-Termins, der mit dem Konferenzraum verknüpft ist.

Google Workspace-Abo erstellen

Wenn Sie ein Abo erstellen möchten, verwenden Sie die Methode subscriptions.create der Google Workspace Events API, um eine Subscription-Ressource zu erstellen. Geben Sie die folgenden Felder an:

  • targetResource: Ein Google Workspace, den Sie im vorherigen Abschnitt identifiziert haben, formatiert mit dem vollständigen Ressourcennamen.
  • eventTypes: Ein Array mit einem oder mehreren Ereignistypen, die Sie für die Ressource erhalten möchten. Wenn Ihre App beispielsweise nur über neue Nachrichten in einem Chatbereich informiert werden muss, kann sie einfach Ereignisse zu erstellten Nachrichten abonnieren.
  • notificationEndpoint: Ein Benachrichtigungsendpunkt, an den Ihr Google Workspace-Abo Ereignisse liefert. Verwenden Sie das Pub/Sub-Thema, das Sie im vorherigen Abschnitt erstellt haben.
  • payloadOptions: Optionen, mit denen Sie angeben können, wie viele Ressourcendaten in die Ereignisnutzlast aufgenommen werden sollen. Diese Konfiguration wirkt sich auf die Ablaufzeit Ihres Abos aus. Weitere Informationen finden Sie unter Ereignisdaten.

So erstellen Sie ein Google Workspace-Abo:

Apps Script

  1. Erstellen Sie in Ihrem Apps Script-Projekt eine neue Skriptdatei mit dem Namen createSubscription und fügen Sie den folgenden Code hinzu:

    function createSubscription() {
  // The Google Workspace resource to monitor for events.
  const targetResource = 'TARGET_RESOURCE';

  // The types of events to receive.
  const eventTypes = [EVENT_TYPES];

  // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  const pubsubTopic = 'TOPIC_NAME';

  // Whether to include resource data or not.
  const resourceData = RESOURCE_DATA;

  // Call the Workspace Events API using the advanced service.
  const response = WorkspaceEvents.Subscriptions.create({
    targetResource: targetResource,
    eventTypes: eventTypes,
    notificationEndpoint: {
      pubsubTopic: pubsubTopic,
    },
    payloadOptions: {
      includeResource: resourceData
    }
  });
  console.log(response);
}

    Ersetzen Sie Folgendes:

    • TARGET_RESOURCE: Die Google Workspace-Ressource, die Sie abonnieren, formatiert als vollständiger Ressourcenname. Wenn Sie beispielsweise einen Chatbereich mit der Bereichs-ID AAAABBBB abonnieren möchten, verwenden Sie //chat.googleapis.com/spaces/AAAABBBB.
    • EVENT_TYPES: Ein oder mehrere Ereignistypen, die Sie in der Zielressource abonnieren möchten. Formatieren Sie sie als Array von Strings, z. B. 'google.workspace.chat.message.v1.created'.
    • TOPIC_NAME: Der vollständige Name des Pub/Sub-Themas, das Sie in Ihrem Cloud-Projekt erstellt haben. Formatiert als projects/PROJECT_ID/topics/TOPIC_ID.

    • RESOURCE_DATA: Ein boolescher Wert, der angibt, ob das Abo Ressourcendaten in der Nutzlast enthält:

      • True: Enthält alle Ressourcendaten. Wenn Sie die enthaltenen Felder einschränken möchten, fügen Sie das Feld fieldMask hinzu und geben Sie mindestens ein Feld für die geänderte Ressource an. Nur Abos für Chat-Ressourcen unterstützen das Einbeziehen von Ressourcendaten.
      • False: Schließt Ressourcendaten aus.

  2. Führen Sie die Funktion createSubscription in Ihrem Apps Script-Projekt aus, um das Google Workspace-Abo zu erstellen.

Python

  1. Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen create_subscription.py und fügen Sie den folgenden Code hinzu:

    """Create subscription."""

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [SCOPES]

# Authenticate with Google Workspace and get user authentication.
flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
CREDENTIALS = flow.run_local_server()

# The Google Workspace resource to monitor for events.
TARGET_RESOURCE = 'TARGET_RESOURCE'

# The types of events to receive.
EVENT_TYPES = [EVENT_TYPES]

# The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API using the service endpoint.
service = build(
    'workspaceevents',
    'v1',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}
response = service.subscriptions().create(body=BODY).execute()
print(response)

    Ersetzen Sie Folgendes:

    • SCOPES: Ein oder mehrere OAuth-Bereiche, die jeden Ereignistyp für das Abo unterstützen. Formatiert als Stringarray. Wenn Sie mehrere Bereiche auflisten möchten, trennen Sie sie durch Kommas. Beispiel: 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'
    • TARGET_RESOURCE: Die Google Workspace-Ressource, die Sie abonnieren, formatiert als vollständiger Ressourcenname. Wenn Sie beispielsweise einen Chatbereich mit der Bereichs-ID AAAABBBB abonnieren möchten, verwenden Sie //chat.googleapis.com/spaces/AAAABBBB.
    • EVENT_TYPES: Ein oder mehrere Ereignistypen, die Sie in der Zielressource abonnieren möchten. Formatieren Sie sie als Array von Strings, z. B. 'google.workspace.chat.message.v1.created'.
    • TOPIC_NAME: Der vollständige Name des Pub/Sub-Themas, das Sie in Ihrem Cloud-Projekt erstellt haben. Formatiert als projects/PROJECT_ID/topics/TOPIC_ID.

    • RESOURCE_DATA: Ein boolescher Wert, der angibt, ob das Abo Ressourcendaten in der Nutzlast enthält:

      • True: Enthält alle Ressourcendaten. Wenn Sie die enthaltenen Felder einschränken möchten, fügen Sie das Feld fieldMask hinzu und geben Sie mindestens ein Feld für die geänderte Ressource an. Nur Abos für Chat-Ressourcen unterstützen das Einbeziehen von Ressourcendaten.
      • False: Schließt Ressourcendaten aus.

  2. Führen Sie in Ihrem Terminal den folgenden Befehl aus, um das Google Workspace-Abo zu erstellen:

    python3 create_subscription.py

Die Google Workspace Events API gibt einen abgeschlossenen Vorgang mit langer Ausführungszeit zurück, der die von Ihnen erstellte Instanz der Subscription-Ressource enthält.

Google Workspace-Abo testen

Wenn Sie testen möchten, ob Sie Google Workspace-Ereignisse empfangen, können Sie ein Ereignis auslösen und Nachrichten an das Pub/Sub-Abo senden.

So testen Sie Ihr Google Workspace-Abo:

Google API-Konsole

  1. Lösen Sie einen oder mehrere Ereignistypen in der Zielressource Ihres Google Workspace-Abos aus. Wenn Sie beispielsweise neue Nachrichten in einem Chatbereich abonniert haben, posten Sie eine Nachricht im Bereich.

  2. Rufen Sie in der Google API Console die Pub/Sub-Seite auf:

    Zu Pub/Sub

    Achten Sie darauf, dass das Cloud-Projekt für Ihre App ausgewählt ist.

  3. Klicken Sie im Pub/Sub-Menü auf Abos.

  4. Suchen Sie in der Tabelle das Pub/Sub-Abo für Ihr Thema und klicken Sie auf den Abonamen.

  5. Klicken Sie auf den Tab Nachrichten.

  6. Klicken Sie auf Pull. Es kann einige Minuten dauern, bis ein Ereignis eine Pub/Sub-Nachricht generiert.

gcloud

  1. Lösen Sie einen oder mehrere Ereignistypen in der Zielressource Ihres Google Workspace-Abos aus. Wenn Sie beispielsweise neue Nachrichten in einem Chatbereich abonniert haben, posten Sie eine Nachricht im Bereich.

  2. Führen Sie dazu diesen Befehl aus:

    gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack

    Ersetzen Sie Folgendes:

    • PUBSUB_SUBSCRIPTION_NAME: Der vollständige Name Ihres Pub/Sub-Abos im Format projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID.
    • MESSAGE_COUNT: Die maximale Anzahl von Pub/Sub-Nachrichten, die Sie abrufen möchten.

    Es kann einige Minuten dauern, bis ein Ereignis eine Pub/Sub-Nachricht generiert.

Für jedes von Ihnen ausgelöste Google Workspace-Ereignis wird eine Nachricht mit dem Ereignis an Ihr Pub/Sub-Abo gesendet. Weitere Informationen finden Sie unter Ereignisse als Google Cloud Pub/Sub-Nachrichten empfangen.

Konfigurieren, wie Ihre App Ereignisse empfängt

Das von Ihnen erstellte Pub/Sub-Abo ist pull-basiert. Nachdem Sie Ihr Pub/Sub-Abo getestet haben, können Sie den Übermittlungstyp aktualisieren, um zu ändern, wie Ihre App Ereignisse empfängt. Sie können das Pub/Sub-Abo beispielsweise für einen Push-Zustellungstyp konfigurieren, damit Ihre Anwendung Ereignisse direkt an einen Anwendungsendpunkt empfangen kann.

Informationen zum Konfigurieren eines Pub/Sub-Abos finden Sie in der Pub/Sub-Dokumentation.

Als Google Chat-App Ereignisse in Chatbereichen abonnieren

Sie können Chat-Ereignisse als Chat-App aus einem Gruppenbereich abonnieren, in dem die Chat-App Mitglied ist. Chat-Apps können keine Nutzerereignisse abonnieren.

Script schreiben, das die Google Workspace Events API aufruft

So erstellen Sie ein Abo für Chatbereichsereignisse mit App-Authentifizierung und Administratorgenehmigung:

  1. Erstellen Sie bei Bedarf eine Chat-App.

  2. Abonnieren Sie eine Chat-Ressource, aber:

    1. Authentifizieren Sie sich stattdessen als Chat-App mit einmaliger Administratorgenehmigung.

    2. Geben Sie Autorisierungsbereiche an, mit denen die Chat-App Chat-Ereignisse abonnieren kann. Diese Autorisierungsbereiche beginnen immer mit chat.app und umfassen Folgendes:

      • https://www.googleapis.com/auth/chat.app.memberships: Abonnieren Sie Ereignisse für Mitglieder des Chatbereichs.
      • https://www.googleapis.com/auth/chat.app.memberships.readonly: Abonnieren Sie Ereignisse für Mitglieder von Chatbereichen.
      • https://www.googleapis.com/auth/chat.app.messages.readonly: Abonnieren Sie Nachrichten- und Reaktionsereignisse in Chatbereichen.
      • https://www.googleapis.com/auth/chat.app.spaces: Abonnieren Sie Ereignisse in Google Chat-Bereichen.
      • https://www.googleapis.com/auth/chat.app.spaces.readonly: Abonnieren Sie Ereignisse in Google Chat-Bereichen.

Im folgenden Codebeispiel werden Nachrichtenereignisse in einem bestimmten Chatbereich abonniert:

Python 

  """Create subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = ['https://www.googleapis.com/auth/chat.app.messages.readonly']

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # The Google Workspace resource to monitor for events.
  TARGET_RESOURCE = '//chat.googleapis.com/spaces/SPACE_ID'

  # The types of events to receive.
  EVENT_TYPES = [
                  'google.workspace.chat.message.v1.created',
                  'google.workspace.chat.message.v1.updated',
                  'google.workspace.chat.message.v1.deleted',
                ]

  # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  TOPIC = 'TOPIC_NAME'

  # Call the Workspace Events API using the service endpoint.
  service = build(
      'workspaceevents',
      'v1',
      credentials=CREDENTIALS,
  )

  BODY = {
      'target_resource': TARGET_RESOURCE,
      'event_types': EVENT_TYPES,
      'notification_endpoint': {'pubsub_topic': TOPIC},
      'payload_options': {'include_resource': RESOURCE_DATA},
  }
  response = service.subscriptions().create(body=BODY).execute()
  print(response)

Ersetzen Sie Folgendes:

  • SPACE_ID: Der Name des Gruppenbereichs, den Sie über die Methode spaces.list in der Chat API oder über die URL eines Gruppenbereichs abrufen können.
  • TOPIC_NAME: Der vollständige Name des Pub/Sub-Themas, das Sie in Ihrem Cloud-Projekt erstellt haben. Formatiert als projects/PROJECT_ID/topics/TOPIC_ID.

  • RESOURCE_DATA: Ein boolescher Wert, der angibt, ob das Abo Ressourcendaten in der Nutzlast enthält:

    • True: Enthält alle Ressourcendaten. Wenn Sie die enthaltenen Felder einschränken möchten, fügen Sie das Feld fieldMask hinzu und geben Sie mindestens ein Feld für die geänderte Ressource an. Nur Abos für Chat-Ressourcen unterstützen das Einbeziehen von Ressourcendaten.
    • False: Schließt Ressourcendaten aus.

Als Google Chat-App alle Chat-Ereignisse in einer Google Workspace-Organisation abonnieren

Mit einem Kundenabo kann Ihre Chat-App Gruppenbereichs- und Nutzerereignisse in einer gesamten Google Workspace-Organisation im Blick behalten.

Weitere Informationen dazu, wie Ereignisse für Kundenabos bereitgestellt werden, einschließlich der Ereignisbereitstellung in Bereichen, die von externen Organisationen verwaltet werden, finden Sie unter Einschränkungen und Bereitstellungsverhalten für Kundenabos.

Anforderungen und Einschränkungen

  • Authentifizierung: Als Chat-App mit einmaliger Administratorgenehmigung authentifizieren
  • SKU: Die Google Workspace-Organisation muss mindestens eine Enterprise-SKU-Lizenz haben. Diese Anforderung wird während der Entwicklervorschau nicht strikt durchgesetzt, wird aber in Zukunft durchgesetzt (wird separat angekündigt).
  • Eindeutigkeit: Eine Chat-App kann nur ein Kundenabo für eine bestimmte Google Workspace-Organisation erstellen. Eine Google Workspace-Organisation kann insgesamt bis zu fünf Kundenabos haben, die von verschiedenen Chat-Apps erstellt wurden.
  • Bereiche: Je nach den Ereignistypen, die Sie empfangen möchten, sind ein oder mehrere der folgenden Bereiche erforderlich:
    • https://www.googleapis.com/auth/chat.app.all.spaces.readonly: Zum Empfangen von Ereignissen zu Gruppenbereichen.
    • https://www.googleapis.com/auth/chat.app.all.memberships.readonly: Zum Empfangen von Ereignissen zu Mitgliedschaften.
    • https://www.googleapis.com/auth/chat.app.all.messages.readonly: Zum Empfangen von Ereignissen zu Nachrichten und Reaktionen.
    • https://www.googleapis.com/auth/chat.app.all.users.readstate.readonly (-Entwicklervorschau): Zum Empfangen von Ereignissen zum Lesestatus von Nutzern.

Kundenabo erstellen

Rufen Sie die Methode subscriptions.create auf, um ein Kundenabo zu erstellen.

Im folgenden Python-Codebeispiel wird ein Kundenabo erstellt:

Python 

"""Create a customer subscription."""

from google.oauth2 import service_account
from apiclient.discovery import build

# Specify required scopes.
# Replace with the scopes needed for the event types you want to receive.
SCOPES = ['https://www.googleapis.com/auth/chat.app.all.messages.readonly']

# Specify service account details.
CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
)

# Monitor all events for the Google Workspace organization.
TARGET_RESOURCE = '//admin.googleapis.com/customers/CUSTOMER_ID'

# The types of events to receive.
EVENT_TYPES = [
    'google.workspace.chat.message.v1.created',
    'google.workspace.chat.message.v1.updated',
    'google.workspace.chat.message.v1.deleted',
]

# The endpoint to deliver events to.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API.
# Note: Use the v1beta endpoint for Developer Preview features.
service = build(
    'workspaceevents',
    'v1beta',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}

response = service.subscriptions().create(body=BODY).execute()
print(response)

Ersetzen Sie Folgendes:

  • CUSTOMER_ID: Die Kundennummer. Sie können auch den Alias my_customer für die Google Workspace-Organisation der Chat-App verwenden.
  • TOPIC_NAME: Der vollständige Name des Pub/Sub-Themas, das Sie in Ihrem Cloud-Projekt erstellt haben. Formatiert als projects/PROJECT_ID/topics/TOPIC_ID.
  • RESOURCE_DATA: Ein boolescher Wert, der angibt, ob das Abo Ressourcendaten in der Nutzlast enthält:
    • True: Enthält alle Ressourcendaten. Wenn Sie die enthaltenen Felder einschränken möchten, fügen Sie das Feld fieldMask hinzu und geben Sie mindestens ein Feld für die geänderte Ressource an. Nur Abos für Chat-Ressourcen unterstützen das Einbeziehen von Ressourcendaten.
    • False: Schließt Ressourcendaten aus.