Pub/Sub-Benachrichtigungen für Cloud Storage

Zu den Beispielen

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

Überblick

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 dazu 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 jeweiligen Pub/Sub-Thema kann die Nachricht an eine beliebige Anzahl von Abonnenten dieses Themas weitergeleitet werden. 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 Functions: 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 Functions. Damit können Sie JavaScript-, Python- und Go-Funktionen ausführen, wenn sich ein Objekt in Ihrem Bucket ändert. Beachten Sie, dass sich Ihr Bucket im selben Projekt wie Cloud Functions befinden muss. Erläuterungen, wie Cloud Functions 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 derzeit 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 oder Neuschreiben eines bestehenden 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 überschrieben oder gelöscht werden. Bei Buckets mit aktivierter Objektversionsverwaltung wird dies nicht gesendet, wenn ein Objekt nicht mehr aktuell ist (siehe OBJECT_ARCHIVE). Dies gilt auch, wenn das Objekt über die Methode storage.objects.delete zu einem nicht aktuellen Objekt wird.
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 überschrieben wurde.

Objekte überschreiben

Das Überschreiben eines bestehenden Objekts durch ein neues mit demselben Namen löst zwei separate Ereignisse aus: OBJECT_FINALIZE für die neue Version des Objekts und OBJECT_ARCHIVE oder OBJECT_DELETE für das überschriebene Objekt. Das Ereignis OBJECT_FINALIZE enthält dann zusätzlich das Attribut overwroteGeneration mit der Generierungsnummer des überschriebenen Objekts. Das Ereignis OBJECT_ARCHIVE oder OBJECT_DELETE enthält 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.

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 überschrieben hat, auf das sich diese Benachrichtigung bezieht. Dieses Attribut kommt nur in OBJECT_ARCHIVE- oder OBJECT_DELETE-Ereignissen im Fall von Überschreibungen vor.
overwroteGeneration 352947 Die Generierungsnummer des Objekts, das von dem Objekt überschrieben wurde, auf das sich diese Benachrichtigung bezieht. Dieses Attribut kommt nur in OBJECT_FINALIZE-Ereignissen im Fall von Überschreibungen vor.

Das folgende Schlüssel/Wert-Paar ist veraltet. Bei neuen Abonnements wird es ab sofort und bei allen anderen Abonnements ab dem 1. Juni 2018 nicht mehr angezeigt.

Attributname Beispiel Beschreibung
resource projects/_/buckets/foo/objects/bar#123456 Der Pfad des Cloud Storage-Objekts, das sich geändert hat.

Zusätzlich zu den oben genannten Attributen kann jede Benachrichtigungskonfiguration bis zu 10 benutzerdefinierte Attribute beinhalten. Benutzerdefinierte Attribute werden beim Erstellen einer Benachrichtigungskonfiguration mit dem Flag -m im Befehl gsutil notification 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.

Weitere Informationen