Pub/Sub-Benachrichtigungen für Cloud Storage

Einrichtung

Auf dieser Seite erhalten Sie einen Überblick über Pub/Sub-Benachrichtigungen für Cloud Storage.

Übersicht

Pub/Sub-Benachrichtigungen enthalten Informationen über Änderungen an Objekten in Ihren Buckets. Diese Informationen werden an Pub/Sub gesendet und dort in Form von Nachrichten zu einem Pub/Sub-Thema Ihrer Wahl hinzugefügt. Beispiel: Sie erfassen, welche Objekte in Ihrem Bucket erstellt und gelöscht werden. Jede Benachrichtigung enthält Informationen über das Ereignis, das diese ausgelöst hat, und über das geänderte Objekt.

Sie können Benachrichtigungen an alle Pub/Sub-Themen in jedem Projekt senden, für das Sie ausreichende Berechtigungen haben. Nach dem Eingang beim Pub/Sub-Thema können Abonnenten die verknüpfte Nachricht empfangen. Weitere Informationen zum Verbinden von Cloud Storage-Buckets mit einem Pub/Sub-Thema finden Sie unter Voraussetzungen.

Andere Benachrichtigungsoptionen

Warnungen und Aktionen können durch Abonnieren von Pub/Sub-Benachrichtigungen als Reaktion auf Änderungen in einem Bucket ausgelöst werden. Alternativ sind die folgenden Optionen verfügbar:

  • Cloud Run-Funktionen: Wenn Sie als Reaktion auf Ereignisse nur eine einfache, eigenständige Funktion auslösen und kein Pub/Sub-Thema verwalten möchten, verwenden Sie Cloud Run-Funktionen. Mit Cloud Run-Funktionen können Sie C#-, Go-, Java-, Node.js-, Python-, PHP- und Ruby-Funktionen ausführen, wenn sich ein Objekt in einem Bucket ändert. Beachten Sie, dass sich Ihr Bucket im selben Projekt wie Cloud Run-Funktionen befinden muss. Erläuterungen, wie Cloud Run-Funktionen mit Cloud Storage genutzt wird, finden Sie in der zugehörigen Anleitung.

  • Änderungsbenachrichtigung für Objekte: Dies ist ein separates, älteres Feature in Cloud Storage, um Benachrichtigungen zu generieren. Darüber werden HTTPS-Nachrichten an eine Client-Anwendung gesendet, die Sie separat eingerichtet haben. Dieses Feature wird im Allgemeinen nicht empfohlen, da Pub/Sub-Benachrichtigungen günstiger, einfacher und flexibler sind.

Benachrichtigungskonfigurationen

Eine Benachrichtigungskonfiguration ist eine Regel, die Sie mit einem Bucket verknüpfen und die Folgendes festlegt:

  • Das Thema in Pub/Sub, das Benachrichtigungen empfangen soll
  • Welche Ereignisse eine Benachrichtigung auslösen
  • Die in den Benachrichtigungen enthaltenen Informationen

Sie können mehrere Benachrichtigungskonfigurationen zu einem Bucket hinzufügen. Ein Bucket kann insgesamt bis zu 100 Benachrichtigungskonfigurationen sowie bis zu 10 Benachrichtigungskonfigurationen haben, die zum Auslösen von Benachrichtigungen für ein bestimmtes Ereignis festgelegt sind.

Wenn Sie beispielsweise eine Benachrichtigungskonfiguration haben, die Löschbenachrichtigungen an ein Pub/Sub-Thema sendet, können Sie dem Bucket eine zweite Benachrichtigungskonfiguration hinzufügen, die Löschbenachrichtigungen an ein anderes Thema sendet. Wenn Sie jedoch versuchen, mehr als zehn Benachrichtigungskonfigurationen zu erstellen, erhalten Sie eine Fehlermeldung. Zusätzlich zu diesen Benachrichtigungskonfigurationen können Sie auch Benachrichtigungskonfigurationen erstellen, die Benachrichtigungen zu anderen Ereignissen, z. B. zur Objekterstellung, enthalten. Empfänger dieser Benachrichtigungen können entweder Pub/Sub-Themen, die von den Löschbenachrichtigungen verwendet werden, oder andere Themen sein.

Jede Benachrichtigungskonfiguration ist mit einer Zahl gekennzeichnet. Diese wird in folgenden Fällen zurückgegeben:

  • Wenn Sie die Benachrichtigungskonfiguration erstellen
  • Wenn Sie die mit einem Bucket verknüpften Benachrichtigungskonfigurationen auflisten
  • Im Attribut notificationConfig jeder Benachrichtigung, die durch die Benachrichtigungskonfiguration ausgelöst wird

Durch das Erstellen oder Löschen von Benachrichtigungskonfigurationen erhöht sich die Metagenerierungsnummer des Buckets.

Ereignistypen

Die folgende Liste enthält die von Cloud Storage unterstützten Ereignistypen:

Ereignistyp Beschreibung
OBJECT_FINALIZE Wird gesendet, wenn ein neues Objekt (oder eine neue Generierung eines vorhandenen Objekts) im Bucket erfolgreich erstellt wurde. Dazu gehört auch das Kopieren, Neuschreiben oder Wiederherstellen eines vorhandenen Objekts. Ein fehlgeschlagener Upload löst dieses Ereignis nicht aus.
OBJECT_METADATA_UPDATE Wird gesendet, wenn sich die Metadaten eines vorhandenen Objekts ändern.
OBJECT_DELETE Wird gesendet, wenn ein Objekt endgültig gelöscht wurde. Dies gilt auch für Objekte, die im Rahmen der Lebenszykluskonfiguration des Buckets ersetzt oder gelöscht werden. Dies umfasst Objekte, die nicht aktuell sind (siehe OBJECT_ARCHIVE) oder mehrteilige Uploads abgebrochen haben nicht.
OBJECT_ARCHIVE Wird nur gesendet, wenn für einen Bucket die Objektversionsverwaltung aktiviert ist. Dieses Ereignis bedeutet, dass die Live-Version eines Objekts zu einer nicht aktuellen Version geworden ist, weil sie entweder explizit dazu gemacht wurde oder durch den Upload eines Objekts mit dem gleichen Namen ersetzt wurde.

Für andere Cloud Storage-Ereignisse wie Bucket-Vorgänge oder Objektlesevorgänge können Sie den entsprechenden Audit-Logtyp in Cloud-Audit-Logs aktivieren und mit einem Filter Audit-Logs an Pub/Sub weiterleiten.

Objekte ersetzen

Wenn Sie ein vorhandenes Objekt durch ein neues mit demselben Namen ersetzen, werden zwei unterschiedliche Ereignisse ausgelöst: OBJECT_FINALIZE für die neue Version des Objekts und OBJECT_ARCHIVE oder OBJECT_DELETE für das ersetzte Objekt. Das Ereignis OBJECT_FINALIZE enthält dann zusätzlich das Attribut overwroteGeneration mit der Generierungsnummer des ersetzten Objekts. Das Ereignis OBJECT_ARCHIVE oder OBJECT_DELETE enthält dann zusätzlich das Attribut overwrittenByGeneration mit der Generierungsnummer des neuen Objekts.

Benachrichtigungsformat

Benachrichtigungen, die an ein Pub/Sub-Thema gesendet werden, bestehen aus zwei Teilen:

  • Attribute: Eine Reihe von Schlüssel/Wert-Paaren, die das Ereignis beschreiben
  • Nutzlast: Ein String, der die Metadaten des geänderten Objekts enthält

Attribute

Attribute sind Schlüssel/Wert-Paare, die in allen Benachrichtigungen enthalten sind, die von Cloud Storage an Ihr Pub/Sub-Thema gesendet werden. Benachrichtigungen enthalten immer die folgenden Schlüssel/Wert-Paare, unabhängig von der Nutzlast der Benachrichtigung:

Attributname Beispiel Beschreibung
notificationConfig projects/_/buckets/foo/notificationConfigs/3 Die Kennzeichnung der Benachrichtigungskonfiguration, die diese Benachrichtigung ausgelöst hat.
eventType OBJECT_FINALIZE Die Art des Ereignisses, das gerade aufgetreten ist. Eine Liste möglicher Werte finden Sie unter Ereignistypen.
payloadFormat JSON_API_V1 Das Format der Objektnutzlast. Eine Liste möglicher Werte finden Sie unter Nutzlast.
bucketId foo Der Name des Buckets, der das geänderte Objekt enthält.
objectId bar Der Name des geänderten Objekts.
objectGeneration 123456 Die Generierungsnummer des geänderten Objekts.
eventTime 2021-01-15T01:30:15.01Z Der Zeitpunkt des Ereignisses, angegeben im RFC 3339-Format.

Unter Umständen enthalten Benachrichtigungen auch die folgenden Schlüssel/Wert-Paare, unabhängig von der Nutzlast der Benachrichtigung:

Attributname Beispiel Beschreibung
overwrittenByGeneration 107458 Die Generierungsnummer des Objekts, das das Objekt ersetzt hat, auf das sich diese Benachrichtigung bezieht. Dieses Attribut kommt nur im Fall von Ersetzungen in OBJECT_ARCHIVE- oder OBJECT_DELETE-Ereignissen vor.
overwroteGeneration 352947 Die Generierungsnummer des Objekts, das durch das Objekt ersetzt wurde, auf das sich diese Benachrichtigung bezieht. Dieses Attribut kommt nur im Fall von Ersetzungen in OBJECT_FINALIZE-Ereignissen vor.

Zusätzlich zu den oben genannten Attributen kann jede Benachrichtigungskonfiguration bis zu 10 benutzerdefinierte Attribute beinhalten. Benutzerdefinierte Attribute werden beim Erstellen einer Benachrichtigungskonfiguration mit --custom-attributes im Befehl gcloud storage oder mit dem Objekt custom_attributes im Text der JSON-Anfrage POST notificationConfigs definiert.

Nutzlast

Die Nutzlast ist ein String, der die Metadaten des geänderten Objekts enthält. Beim Erstellen einer Benachrichtigungskonfiguration geben Sie einen Nutzlasttyp an, der in Benachrichtigungen enthalten sein soll, die durch diese Konfiguration ausgelöst werden. Die folgenden Nutzlasttypen stehen zur Wahl:

Nutzlasttyp Beschreibung
NONE Die Benachrichtigung enthält keine Nutzlast.
JSON_API_V1 Die Nutzlast ist ein UTF-8-String, der die Ressourcendarstellung der Metadaten des Objekts enthält.

Bei OBJECT_DELETE-Benachrichtigungen stellen die in der Nutzlast enthaltenen Metadaten die Objektmetadaten vor dem Löschvorgang dar. Zusätzlich enthalten sie das Attribut timeDeleted. Bei allen anderen Benachrichtigungen repräsentieren die in der Nutzlast enthaltenen Metadaten die Objektmetadaten nach der Änderung.

Beispiel: Sie haben eine Benachrichtigungskonfiguration, die OBJECT_METADATA_UPDATE-Ereignisse verfolgt. Wenn ein Nutzer das Attribut contentType eines Objekts von binary/octet-stream zu video/mp4 ändert, wird eine OBJECT_METADATA_UPDATE-Benachrichtigung gesendet und die Metadaten in der Nutzlast enthalten die Information "contentType":"video/mp4".

Übermittlungsgarantien

Wenn Sie eine Benachrichtigungskonfiguration hinzufügen, kann es bis zu 30 Sekunden dauern, bis Cloud Storage mit dem Senden von Benachrichtigungen beginnt. Danach garantiert Cloud Storage eine mindestens einmalige Übermittlung an Pub/Sub. Auch Pub/Sub bietet eine mindestens einmalige Übermittlung an den Empfänger. Dies bedeutet, dass Sie mehrere Nachrichten mit unterschiedlichen IDs zu demselben Cloud Storage-Ereignis erhalten können.

Es wird nicht garantiert, dass Benachrichtigungen in der Reihenfolge veröffentlicht werden, in der Pub/Sub sie empfängt. Wenn Sie ein Cloud Storage-Objekt basierend auf einer Benachrichtigung ändern möchten, sollten Sie die Generierungs- und Metagenerierungsnummern des Objekts als Bedingungen in Ihrer Aktualisierungsanfrage verwenden.

Wenn eine Benachrichtigung dauerhaft nicht an ein Pub/Sub-Thema gesendet werden kann, löscht Cloud Storage die Benachrichtigung möglicherweise nach 7 Tagen. Ein Übermittlungsfehler kann auftreten, wenn das Pub/Sub-Thema nicht mehr vorhanden ist, Cloud Storage nicht mehr über die Berechtigung zum Veröffentlichen in dem Thema verfügt oder wenn das Projekt, zu dem das Thema gehört, das Veröffentlichungskontingent überschreitet.

Nächste Schritte