Cloud Pub/Sub-Benachrichtigungen für Cloud Storage

Auf dieser Seite erhalten Sie eine Übersicht über Cloud Pub/Sub-Benachrichtigungen für Cloud Storage. Informationen zum Einrichten und Verwenden von Cloud Pub/Sub-Benachrichtigungen finden Sie in Objektänderungen registrieren.

Übersicht

Mit Cloud Pub/Sub-Benachrichtigungen werden Informationen über Änderungen an Objekten in Buckets an Cloud Pub/Sub gesendet. Dort werden die Informationen in Form von Nachrichten einem Cloud Pub/Sub-Thema Ihrer Wahl hinzugefügt. Sie können beispielsweise 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 Cloud Pub/Sub-Themen in jedem Projekt senden, für das Sie ausreichende Berechtigungen haben. Nach dem Eingang bei dem jeweiligen Cloud 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 Cloud Pub/Sub-Thema finden Sie unter Voraussetzungen.

Andere Benachrichtigungsoptionen

Das Abonnieren von Cloud Pub/Sub-Benachrichtigungen ist eine vielseitige Möglichkeit, bei Änderungen in einem Bucket Warnungen und Aktionen auszulösen. 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 Cloud 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. Im Allgemeinen sind Cloud Pub/Sub-Benachrichtigungen günstiger, einfacher und flexibler.

Benachrichtigungskonfigurationen

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

  • Das Thema in Cloud 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. Für jedes Ereignis können bis zu zehn Benachrichtigungskonfigurationen festgelegt werden, um eine Benachrichtigung auszulösen.

Wenn Sie beispielsweise eine Benachrichtigungskonfiguration einrichten, die Löschbenachrichtigungen an ein Cloud 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 solche erstellen, die Benachrichtigungen für andere Ereignisse senden, z. B. zur Objekterstellung, entweder an Cloud Pub/Sub-Themen, die von den Löschbenachrichtigungen verwendet werden, oder an andere Themen.

Jede Benachrichtigungskonfiguration ist durch eine 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 bzw. 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. Für Buckets mit aktivierter Objektversionsverwaltung wird dieses Ereignis nicht gesendet, wenn ein Objekt archiviert wird (siehe OBJECT_ARCHIVE). Dies gilt auch, wenn die Archivierung über die Methode storage.objects.delete erfolgt.
OBJECT_ARCHIVE Wird nur gesendet, wenn für einen Bucket die Objektversionsverwaltung aktiviert ist. Dieses Ereignis bedeutet, dass die Liveversion eines Objekts zu einer archivierten Version geworden ist, weil sie entweder archiviert oder durch das Hochladen 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 Cloud 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 Cloud 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.

Benachrichtigungen können zusätzlich zu den obigen Attributen benutzerdefinierte Attribute enthalten. Diese 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 Cloud Pub/Sub. Auch Cloud 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 gibt derzeit kein SLA für die Übermittlungszeit, aber Benachrichtigungen werden in der Regel innerhalb von Sekunden zugestellt. In seltenen Fällen können sich Benachrichtigungen deutlich verzögern.

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

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

Weitere Informationen

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...