Mit Ereignissen aus Google Drive arbeiten

Auf dieser Seite wird beschrieben, wie Sie Google Drive-Ereignisse von Google Cloud Pub/Sub empfangen.

Ein Drive-Ereignis stellt eine Aktivität oder Änderung an einer Drive-Ressource dar, z. B. eine neue Datei in einem Ordner. Mit Ereignissen können Sie nachvollziehen, was passiert ist, und dann Maßnahmen ergreifen oder auf sinnvolle Weise auf Ihre Nutzer reagieren.

Hier einige Beispiele für die Verwendung von Ereignissen:

• Änderungen an einer Datei, einem Ordner oder einer geteilten Ablage beobachten und darauf reagieren, z. B. wenn eine Datei bearbeitet oder eine neue Version hochgeladen wird.

• Änderungen an Dateien überwachen, um die Leistung Ihrer App zu verbessern

• Prüfen Sie Aktivitäten wie Dateifreigaben, Dateiverschiebung und Löschungen, um potenzielle Datenlecks und unautorisierte Zugriffe zu erkennen.

• Sie erhalten Einblicke in die Art und Weise, wie Nutzer ihre Dateien verwalten, und können so Bereiche identifizieren, in denen die Inhaltsverwaltung verbessert werden könnte.

• Dateiänderungen verfolgen, um die Einhaltung von behördlichen Anforderungen oder Sicherheitsrichtlinien zu überprüfen.

• Drive-Aktivitäten mit anderen Google Cloud-Produkten wie Eventarc, Workflows und BigQuery analysieren

So funktionieren Ereignisse

Immer wenn etwas in Drive passiert, wird eine Google Drive API-Ressource erstellt, aktualisiert oder gelöscht. In Drive werden Ereignisse verwendet, um Informationen über die Art der Aktivität und die betroffene Drive API-Ressource an Ihre App zu senden.

In Drive werden Ereignisse nach Typ kategorisiert. Mit Ereignistypen können Sie filtern und nur die Informationen erhalten, die Sie benötigen. Außerdem können Sie ähnliche Aktivitäten auf dieselbe Weise verarbeiten.

In der folgenden Tabelle sehen Sie, wie sich eine Aktivität in Drive auf eine zugehörige Drive API-Ressource auswirkt und welche Art von Ereignis Ihre Drive-App empfängt:

Ereignisse aus Google Drive empfangen

Bisher konnten Ereignisse in Ihrer Drive-App entweder über die Drive API oder die Google Drive Activity API gefunden werden. Mit der Aufnahme von Drive-Ereignissen in die Google Workspace Events API gibt es jetzt eine dritte Methode zum Empfangen von Ereignissen:

• Developer Preview: Abonnieren Sie Ereignisse mit der Google Workspace Events API, um Ereignisse zu empfangen, sobald sie eintreten.

• Abonnieren Sie Ereignisse mit der Drive API. Rufen Sie Nutzeränderungsereignisse mit der Methode changes.watch oder Dateiänderungsereignisse mit der Methode files.watch ab.

• Rufen Sie die Google Drive Activity API auf, um nach aktuellen Ereignissen zu suchen.

In der folgenden Tabelle werden die Unterschiede und Gründe für das Abonnieren von Ereignissen im Vergleich zum Abfragen von Ereignissen erläutert:

Einstieg in Drive-Ereignisse

In dieser Anleitung wird beschrieben, wie Sie ein Google Workspace-Abo für Ereignisse für eine Drive-Ressource erstellen und verwalten. So kann Ihre App Ereignisse über Google Cloud Pub/Sub empfangen.

Google Cloud-Projekt erstellen

Informationen zum Erstellen eines Google Cloud-Projekts finden Sie unter Google Cloud-Projekt erstellen.

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

Client-ID einrichten

Informationen zum Generieren einer OAuth 2.0-Client-ID finden Sie unter Anmeldedaten mit OAuth 2.0-Client-ID erstellen.

Pub/Sub-Thema erstellen

Bevor Sie ein Abo erstellen, müssen Sie ein Google Cloud Pub/Sub-Thema erstellen, in dem relevante Ereignisse empfangen werden, die für Ihre Anwendung von Interesse sind. Informationen zum Erstellen des Pub/Sub-Themas finden Sie unter Pub/Sub-Thema erstellen und abonnieren.

Achten Sie darauf, dass Sie in Ihren Anfragen auf das Drive-Dienstkonto (drive-api-event-push@system.gserviceaccount.com) verweisen.

Drive-Abo erstellen

Cloud-Ereignisse werden gesendet, wenn sich das Abo-Subjekt (oder eine andere Datei in der Hierarchie des Subjekts) ändert. Wenn Sie beispielsweise ein Abo für eine geteilte Ablage erstellen und sich eine Datei ändert, die in mehreren Unterordnern in dieser geteilten Ablage verschachtelt ist, wird ein Ereignis generiert. Informationen zu unterstützten Ressourcen und Drive-Ereignistypen finden Sie unter Ereignistypen zum Erstellen von Abos.

Die folgende Node.js-Anwendung erstellt ein Drive-Ereignisabo für eine Datei oder einen Ordner, um auf Ereignisse zu warten, die durch Änderungen am Inhalt ausgelöst werden. Weitere Informationen finden Sie unter Google Workspace-Abo erstellen.

Damit Sie dieses Beispiel ausführen können, müssen Sie Node.js und npm installieren. Außerdem müssen Sie die erforderlichen Abhängigkeiten installiert haben, um dieses Beispiel auszuführen.

# Install needed dependencies
$ npm install googleapis @google-cloud/local-auth axios

Zum Erstellen eines Drive-Abos verwenden Sie die Methode subscriptions.create() der Google Workspace Events API, um eine Subscription-Ressource zu erstellen:

// app.js

const fs = require('fs').promises;
const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const axios = require('axios');

// Scopes for Google Drive API access.
const SCOPES = ['SCOPES'];

/**
 * Loads saved credentials from token.json, or authenticates the user.
 * @return {Promise<OAuth2Client>} The authorized client.
 */
async function authorize() {
  try {
    const content = await fs.readFile('token.json');
    const credentials = JSON.parse(content);
    return google.auth.fromJSON(credentials);
  } catch (err) {
    const client = await authenticate({
      scopes: SCOPES,
      keyfilePath: 'credentials.json',
    });
    if (client.credentials) {
      const content = await fs.readFile('credentials.json');
      const keys = JSON.parse(content);
      const { client_id, client_secret } = keys.installed || keys.web;
      const payload = JSON.stringify({
        type: 'authorized_user',
        client_id,
        client_secret,
        refresh_token: client.credentials.refresh_token,
      });
      await fs.writeFile('token.json', payload);
    }
    return client;
  }
}

/**
 * Creates a subscription to Google Drive events.
 * @param {OAuth2Client} authClient An authorized OAuth2 client.
 */
async function createSubscription(authClient) {
  const url = 'https://workspaceevents.googleapis.com/v1beta/subscriptions';

  const data = {
    targetResource: 'TARGET_RESOURCE',
    eventTypes: ['EVENT_TYPES'],
    payload_options: {
      include_resource: RESOURCE_DATA
    },
    drive_options: {
      include_descendants: INCLUDE_DESCENDANTS
    },
    notification_endpoint: {
      pubsub_topic: 'TOPIC_NAME'
    }
  };

  try {
    const { token } = await authClient.getAccessToken();
    const response = await axios.post(url, data, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    console.log('Subscription created:', response.data);
  } catch (error) {
    const message = error.response ? error.response.data : error.message;
    console.error('Error creating subscription:', message);
  }
}

authorize().then(createSubscription).catch(console.error);

Ersetzen Sie Folgendes:

• SCOPES: Ein oder mehrere OAuth-Bereiche, die jeden Ereignistyp für das Abo unterstützen. Als Array von Strings formatiert. Wenn Sie mehrere Bereiche auflisten möchten, trennen Sie sie durch Kommas. Als Best Practice sollten Sie den restriktivsten Bereich verwenden, der für die Funktion Ihrer App erforderlich ist. Beispiel: 'https://www.googleapis.com/auth/drive.file'.

• TARGET_RESOURCE: Die Google Workspace-Ressource, die Sie abonnieren, formatiert als vollständiger Ressourcenname. Wenn Sie beispielsweise eine Drive-Datei oder einen Drive-Ordner abonnieren möchten, verwenden Sie //drive.googleapis.com/v3/files/FileID.

• EVENT_TYPES: Ein oder mehrere Ereignistypen, die Sie in der Zielressource abonnieren möchten. Als Array von Strings formatieren, z. B. 'google.workspace.drive.file.v3.contentChanged'.

• RESOURCE_DATA: Ein boolescher Wert, der angibt, ob die Ereignisnutzlast Ressourcendaten enthält. Diese Property wirkt sich auf die Laufzeit Ihres Abos aus. Weitere Informationen zu Ereignisdaten

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

  • False: Schließt Ressourcendaten aus.

• INCLUDE_DESCENDANTS: Ein boolesches Feld, das Teil von DriveOptions ist. Nur verfügbar, wenn targetResource entweder eine Drive-Datei oder eine geteilte Ablage mit dem MIME-Typ application/vnd.google-apps.folder ist. Kann nicht für den Stammordner von „Meine Ablage“ oder geteilte Ablagen festgelegt werden.

  • True: Das Abo umfasst alle untergeordneten Drive-Dateien in der Liste der Ereignisse.

  • False: Das Abo wird für die einzelne Datei oder die geteilte Ablage erstellt, die als targetResource angegeben ist.

• TOPIC_NAME: Der vollständige Name des Pub/Sub-Themas, das Sie in Ihrem Cloud-Projekt erstellt haben. Dieses Pub/Sub-Thema empfängt Ereignisse für das Abo. Das Format sieht so aus: projects/PROJECT_ID/topics/TOPIC_ID. Mit dem Feld notificationEndpoint wird das Pub/Sub-Thema angegeben, über das das Abo Ereignisse bereitstellt.

Drive-Abo testen

Wenn Sie testen möchten, ob Sie Drive-Ereignisse empfangen, können Sie ein Ereignis auslösen und Nachrichten für das Pub/Sub-Abo abrufen. Weitere Informationen finden Sie unter Google Workspace-Abo testen.

Drive-Ereignisse mit Cloud Functions verarbeiten

Drive-Ereignisse werden an das Pub/Sub-Thema im Abo gesendet, das Sie erstellen. Achten Sie beim Erstellen des Triggers darauf, dass das Pub/Sub-Thema für den Trigger mit dem Pub/Sub-Thema in Ihrem Ereignisabo übereinstimmt. Anschließend können Sie Ihre Cloud Run-Funktion bereitstellen und die Datei bearbeiten, um Ereignisänderungen in den Logs zu sehen.

Bevor Sie die Funktion erstellen, aktualisieren Sie die package.json für die Abhängigkeiten:

{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0",
    "cloudevents": "^8.0.0"
  }
}

Erstellen Sie als Nächstes den Quellcode für die Funktion:

const functions = require('@google-cloud/functions-framework');
const { HTTP } = require("cloudevents");

/**
 * A Cloud Function triggered by Pub/Sub messages containing Google Drive activity events.
 * This function processes different types of Drive events.
 *
 * @param {object} cloudEvent The CloudEvent object.
 * @param {object} cloudEvent.data The data payload from the event source.
 */
functions.cloudEvent('helloFromDrive', async (cloudEvent) => {
  try {
    // Verify the Pub/Sub message exists
    if (!cloudEvent.data || !cloudEvent.data.message) {
      console.warn("Event is missing the Pub/Sub message payload.");
      return;
    }

    // Extract the Pub/Sub message details
    const { message } = cloudEvent.data;
    const { attributes, data } = message;

    // The original Drive CloudEvent is reconstructed from the Pub/Sub message attributes
    const driveEvent = HTTP.toEvent({ headers: attributes });
    const { type } = driveEvent;

    // The Drive event's payload is a base64 encoded JSON string
    const payload = JSON.parse(Buffer.from(data, "base64").toString());

    console.log(`Processing Drive event type: ${type}`);

    // Use a switch statement to handle different event types
    switch (type) {
      case 'google.workspace.drive.file.v3.contentChanged':
        console.log('File Content Changed:', payload);
        break;
      case 'google.workspace.drive.accessproposal.v3.created':
        console.log('Access Proposal Created:', payload);
        break;
      default:
        console.log(`Received unhandled event type: ${type}`);
        break;
    }
  } catch (error) {
    console.error("An error occurred while processing the Drive event:", error);
  }
});

• Wenn das boolesche Feld includeDescendants in DriveOptions true ist, wird bei Drive-Abos für geteilte Ablagen und Ordner immer ein Ereignis gesendet, auch wenn die Datei, die das Ereignis ausgelöst hat, viele Ebenen unter dem Ordner liegt, der für das Drive-Abo verwendet wird.
• Auch wenn Sie ein Abo für einen Ordner erstellt haben, erhalten Sie möglicherweise nicht alle Ereignisse in der Dateihierarchie, da der Nutzer oder die Anwendung möglicherweise keinen Zugriff darauf hat. In diesem Fall bleibt das Abo aktiv, Sie erhalten aber keine Ereignisse für Ressourcen, auf die Sie keinen Zugriff haben.
• Abos werden für Ereignisse für alle Dateien und Ordner unterstützt, nicht jedoch für den Stammordner von geteilten Ablagen. Abos werden nur für Dateien und Ordner in geteilten Ablagen unterstützt. Änderungen, die direkt am Stammordner einer geteilten Ablage vorgenommen werden, lösen keine Ereignisse aus.
• Der Nutzer, der das Abo autorisiert, muss die Berechtigung für die Datei haben, die den Ereignissen entspricht, die er abonniert.
• Das Abo empfängt nur Ereignisse für Ressourcen, auf die der Nutzer über sein Google Workspace-Konto oder Google-Konto Zugriff hat.

Weitere Informationen

• Übersicht über die Google Workspace Events API
• Google Workspace-Abo erstellen