Änderungsbenachrichtigung für Objekte

Mit der Änderungsbenachrichtigung für Objekte kann eine Anwendung benachrichtigt werden, wenn ein Objekt aktualisiert oder einem Bucket hinzugefügt wird.

Sollte ich Änderungsbenachrichtigungen für Objekte verwenden?

Im Allgemeinen sollten Sie Änderungsbenachrichtigungen für Objekte nicht verwenden. Zum Erstellen von Benachrichtigungen, die Änderungen an Objekten in Ihren Cloud Storage-Buckets verfolgen, empfehlen wir Pub/Sub-Benachrichtigungen für Cloud Storage, da dieses Tool schneller, flexibler, einfacher einzurichten und kostengünstiger ist. Eine detaillierte Anleitung zum Einrichten von Pub/Sub-Benachrichtigungen für Cloud Storage finden Sie unter Pub/Sub-Benachrichtigungen für Cloud Storage konfigurieren.

Funktionsweise der Änderungsbenachrichtigung für Objekte

Eine Clientanwendung kann eine Anfrage senden, um einen bestimmten Bucket auf Änderungen an den darin enthaltenen Objekten zu überwachen.

Durch eine solche Überwachungsanfrage wird ein neuer Benachrichtigungskanal angelegt. Über diesen wird eine Benachrichtigung an eine Anwendung gesendet, die einen Bucket beobachtet. Derzeit werden nur Webhooks als Benachrichtigungskanal unterstützt.

Nachdem ein Benachrichtigungskanal initiiert wurde, benachrichtigt Cloud Storage die Anwendung jedes Mal, wenn ein Objekt hinzugefügt, aktualisiert oder aus dem Bucket entfernt wird. Fügen Sie beispielsweise einem Bucket ein neues Bild hinzu, kann eine Anwendung benachrichtigt werden, damit sie eine Miniaturansicht erstellt.

Details zur Änderungsbenachrichtigung für Objekte

Terminologie

Die folgende Tabelle enthält eine Beschreibung verschiedener Begriffe, die in der Dokumentation der Änderungsbenachrichtigung für Objekte verwendet werden.

Begriff Beschreibung
Anwendungs-URL Die URL Ihrer Anwendung. Dies ist die Adresse, an die Benachrichtigungen gesendet werden. Dabei muss es sich um eine HTTPS-URL handeln. HTTP-URLs sind nicht zulässig.
Kanal-ID Die Kennung eines Benachrichtigungskanals. Darf innerhalb eines Buckets nur einmal vorkommen, d. h. wenn es mehrere Benachrichtigungskanäle für einen einzelnen Bucket gibt, muss jeder Benachrichtigungskanal eine einmalige Kanal-ID haben. Diese ID wird zusammen mit jeder Benachrichtigungsnachricht an Ihre Anwendung gesendet.
Ressourcenkennzeichner Eine intransparente Kennzeichnung für die überwachte Ressource. Der Ressourcenkennzeichner wird benötigt, um einen Benachrichtigungskanal zu beenden. Sie können diesen Kennzeichner der Antwort auf eine Überwachungsanfrage oder dem X-Goog-Resource-Id-Header von Nachrichten zu Benachrichtigungsereignissen entnehmen.
Client-Token (Optional) Mit Client-Tokens können Benachrichtigungsereignisse validiert werden. Richten Sie hierzu ein benutzerdefiniertes Client-Token für Ihre Überwachungsanfrage ein. Die Benachrichtigungen enthalten dieses Token, woran Sie erkennen können, dass sie echt sind.

Buckets überwachen

Wenn Sie einen Bucket auf Ereignisse überwachen möchten, die eine Änderungsbenachrichtigung erfordern, senden Sie eine watchAll-Anfrage. Dadurch wird ein Benachrichtigungskanal erstellt, über den Benachrichtigungsereignisse an die angegebene address des jeweiligen Buckets gesendet werden. Dieser Benachrichtigungskanal enthält ein benutzerdefiniertes Client-Token und eine Kanal-ID, falls angegeben.

Hier sehen Sie ein Beispiel für eine POST-Anfrage zum Überwachen eines Buckets:

POST /storage/v1/b/BucketName/o/watch?alt=json HTTP/1.1
Host: storage.googleapis.com
Content-Length: 200
User-Agent: google-api-python-client/1.0
Content-Type: application/json
Authorization: Bearer oauth2_token

{
  "token": "ClientToken",
  "type": "web_hook",
  "id": "ChannelId",
  "address": "ApplicationUrl"
}

Benachrichtigungsautorisierung

Beim Beobachten eines Buckets wird der erstellte Benachrichtigungskanal mit dem Google Cloud Console-Projekt der Anwendung verknüpft, die die API-Anfrage auslöst. Wenn ein Nutzer beispielsweise über einen OAuth2-Ablauf Zugriff auf eine installierte Anwendung oder Webanwendung gewährt, wird ein von der Anwendung erstellter Benachrichtigungskanal mit dem Projekt der Anwendung verknüpft und nicht mit dem Projekt, das den beobachteten Bucket enthält.

Da ein Dienstkonto mit einem Projekt verknüpft ist, wird durch den Einsatz eines Dienstkontos zum Überwachen eines Buckets ein Benachrichtigungskanal im Projekt des Dienstkontos erstellt.

Benachrichtigungskanal entfernen

Wenn Sie einen Benachrichtigungskanal beenden möchten, senden Sie eine stop-Anfrage. Dadurch werden keine Benachrichtigungsereignisse mehr an das angegebene Paar aus Ressourcen-ID (resourceId) und Kanal-ID (id) gesendet. Weitere aktive Kanäle für dieselbe Ressource bleiben davon unberührt. Den Ressourcenkennzeichner und die Kanal-ID finden Sie in der Antwort auf eine Überwachungsanfrage oder im Text von Nachrichten zu Benachrichtigungsereignissen.

Hier sehen Sie ein Beispiel für eine POST-Anfrage zum Beenden eines Kanals:

POST /storage/v1/channels/stop HTTP/1.1
Host: storage.googleapis.com
Content-Length: 200
User-Agent: google-api-python-client/1.0
Content-Type: application/json
Authorization: Bearer oauth2_token

{
  "resourceId": "ResourceId",
  "id": "ChannelId"
}

Arten von Nachrichten zu Benachrichtigungsereignissen

Synchronisieren

Ein Benachrichtigungsereignis wird gesendet, wenn aufgrund einer Überwachungsanfrage ein neuer Benachrichtigungskanal erstellt wurde. Nach Erhalt des Synchronisierungsereignisses werden alle späteren Bucket-Änderungen an die für den Kanal konfigurierte Anwendungs-URL gesendet.

Die Benachrichtigung wird als POST-Anfrage an die konfigurierte Anwendungs-URL gesendet. Die Anfrage enthält keinen Text. Die Metadaten der Synchronisierungsbenachrichtigung befinden sich in den Anfrage-Headern. Das folgende Beispiel zeigt eine Synchronisierungsbenachrichtigungsanfrage:

POST /ApplicationUrlPath
Accept: */*
Content-Type: application/json; charset="utf-8"
Content_Length: 0
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: sync
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

Objekt hinzufügen, aktualisieren oder löschen

Ein Benachrichtigungsereignis wird gesendet, wenn ein neues Objekt zu einem Bucket hinzugefügt wird, der Inhalt oder die Metadaten eines bereits vorhandenen Objekts geändert wurden oder ein Objekt aus einem Bucket gelöscht wird.

Die Benachrichtigung wird als POST-Anfrage an die konfigurierte Anwendungs-URL gesendet. Der Anfragetext enthält eine JSON-codierte Nachricht, wie in der folgenden Benachrichtigungsanfrage gezeigt: 

POST /ApplicationUrlPath
Accept: */*
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: ResourceState
X-Goog-Resource-Uri: https://storage.googleapis.com/storage/v1/b/BucketName/o?alt=json

{
 "kind": "storage#object",
 "id": "BucketName/ObjectName",
 "selfLink": "https://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName",
 "name": "ObjectName",
 "bucket": "BucketName",
 "generation": "1367014943964000",
 "metageneration": "1",
 "contentType": "application/octet-stream",
 "updated": "2013-04-26T22:22:23.832Z",
 "size": "10",
 "md5Hash": "xHZY0QLVuYng2gnOQD90Yw==",
 "mediaLink": "https://content-storage.googleapis.com/storage/v1/b/BucketName/o/ObjectName?generation=1367014943964000&alt=media",
 "owner": {
  "entity": "user-jane@gmail.com"
 },
 "crc32c": "C7+82w==",
 "etag": "COD2jMGv6bYCEAE="
}
 Dabei ist ResourceState:
  • exists: für Objekte, die hinzugefügt oder aktualisiert wurden
  • not_exists: für Objekte, die gelöscht wurden

Die JSON-Nachricht enthält die aktuelle Darstellung des Objekts, wie unter Ressourcendarstellungen für Objekte beschrieben.

Zuverlässige Übermittlung

Die Änderungsbenachrichtigung für Objekte versucht, Benachrichtigungen an Ihre Anwendung zuverlässig zu übermitteln. Es kann jedoch vorkommen, dass sich Benachrichtigungen auf unbestimmte Zeit verzögern. Eine pünktliche Übermittlung wird nicht garantiert. Da Ihre Anwendung möglicherweise nicht immer verfügbar ist, gelten die folgenden Regeln für die Übermittlung von Benachrichtigungen:

  • Wenn die Übermittlung einer Benachrichtigung fehlschlägt, werden weitere Versuche unternommen. Das Intervall zwischen weiteren Übermittlungsversuchen hängt von einem exponentiellen Backoff-Algorithmus ab, der 30 Sekunden nach dem ersten Fehler einen neuen Versuch unternimmt. Nachfolgende Übermittlungsversuche werden mit zunehmenden Intervallen bis zu einem maximalen Abstand von 90 Minuten durchgeführt. Dabei weichen die nachfolgenden Wiederholungsintervalle leicht voneinander ab, damit sie keine exakt exponentiellen Werte aufweisen. Wenn das maximale Wiederholungsintervall von 90 Minuten erreicht ist, werden weitere Wiederholungen 7 Tage lang im Abstand von 90 Minuten versucht. Sollte die Benachrichtigung in dieser Zeit nicht übermittelt werden können, wird sie gelöscht.
  • Wenn Ihre Anwendung nach 20 Sekunden nicht erreicht werden kann oder einen der folgenden HTTP-Antwortcodes ausgibt, gilt die Benachrichtigungsübermittlung als fehlgeschlagen und wird noch einmal versucht:
    • 500 Interner Serverfehler
    • 502 Fehlerhaftes Gateway
    • 503 Dienst nicht verfügbar
    • 504 Gateway-Zeitüberschreitung
  • Wenn Ihre Anwendung einen der folgenden HTTP-Antwortcodes ausgibt, gilt die Benachrichtigung als erfolgreich gesendet:
    • 102 Verarbeitung
    • 200 OK
    • 201 Erstellt
    • 202 Angenommen
    • 204 Kein Inhalt
  • Alle anderen von Ihrer Anwendung zurückgegebenen HTTP-Antwortcodes gelten als dauerhafte Fehler, bei denen die Übermittlung nicht noch einmal versucht wird.

Beispiel für Clientanwendung

In diesem Abschnitt wird erläutert, wie Sie eine App Engine-Clientanwendung erstellen, die Änderungsbenachrichtigungsereignisse verarbeitet.

Die Beispielanwendung enthält eine Klasse namens MainPage. Wenn ein Nutzer ein Objekt aktualisiert oder zum Bucket hinzufügt, verarbeitet die MainPage-Klasse das Benachrichtigungsereignis. Der Einfachheit halber erfasst die post-Methode, die für die eigentliche Verarbeitung zuständig ist, nur eine Nachricht mit dem Zeitpunkt in einem Log, zu dem die Benachrichtigung eingegangen ist. Sie können diesen Code durch Ihre tatsächliche Verarbeitungslogik ersetzen. Wenn Sie noch nicht mit der Entwicklung von App Engine-Anwendungen vertraut sind, empfehlen wir Ihnen, eine Beispielanwendung bereitzustellen oder eine Anleitung zu lesen, bevor Sie fortfahren.

  1. Anwendung konfigurieren
    Erstellen Sie die Konfigurationsdatei app.yaml, um die Clientanwendung festzulegen, die die Änderungsbenachrichtigungsereignisse des Buckets verarbeitet. 
    application: APPLICATION
version: 1
runtime: python38
api_version: 1
threadsafe: true

handlers:
- url: /.*
  script: change_notification_client.app
  2. Anwendung erstellen
    Im folgenden Beispiel wird eine Clientanwendung zur Verarbeitung der Änderungsbenachrichtigungsereignisse eines Buckets implementiert. Nennen Sie die Anwendung change_notification_client.py und stellen Sie diese dann bereit: 
    """Notification handling for Google Cloud Storage."""

import json
import logging

import webapp2


class MainPage(webapp2.RequestHandler):
  """Process notification events."""
  def get(self):
    logging.info("Get request to notification page.")
    self.response.write("Welcome to the notification app.")

  def post(self):  # pylint: disable-msg=C6409
    """Process the notification event.

    This method is invoked when the notification channel is first created with
    a sync event, and then subsequently every time an object is added to the
    bucket, updated (both content and metadata) or removed. It records the
    notification message in the log.
    """

    logging.debug(
        '%s\n\n%s',
        '\n'.join(['%s: %s' % x for x in self.request.headers.iteritems()]),
        self.request.body)

    # The following code is for demonstration. Replace
    # it with your own notification processing code.

    if 'X-Goog-Resource-State' in self.request.headers:
      resource_state = self.request.headers['X-Goog-Resource-State']
      if resource_state == 'sync':
        logging.info('Sync message received.')
      else:
        an_object = json.loads(self.request.body)
        bucket = an_object['bucket']
        object_name = an_object['name']
        logging.info('%s/%s %s', bucket, object_name, resource_state)
    else:
      logging.info("Other post.")

logging.getLogger().setLevel(logging.DEBUG)
app = webapp2.WSGIApplication([('/', MainPage)], debug=True)
  3. Zugriffsberechtigung der Anwendung dem Bucket zuweisen
    Wenn Ihr Bucket zu einem anderen Dienstkonto gehört als Ihre App Engine-Anwendung, gewähren Sie der Anwendung OWNER-Zugriff auf den Bucket.
  4. Bucket auf Objektänderungen überwachen
    Erstellen Sie einen Benachrichtigungskanal für Ihre Anwendung, indem Sie den Bucket mithilfe einer watchAll-Anfrage mit dem address der URL für Ihre Anwendung überwachen. Engine-Anwendung, z. B. https://ApplicationId.appspot.com/.
  5. Anwendung testen
    Führen Sie die folgenden Schritte aus, um herauszufinden, ob die Anwendung wie erwartet funktioniert:
    1. Mit dem folgenden curl-Befehl prüfen Sie, ob die Anwendung bereitgestellt wurde und korrekt funktioniert:
      curl -X Post https://APPLICATION_ID.appspot.com
       Falls Sie Ihren eigenen Domainnamen für die Bereitstellung der Anwendung verwendet haben, setzen Sie im vorherigen Befehl diesen anstelle von appspot.com ein.
    2. Gehen Sie zur Logging-Seite für Ihr Projekt. Aktualisieren Sie ggf. die Liste der in Logs erfassten Nachrichten. Sehen Sie nach, ob die von der Anwendung ausgegebene Log-Nachricht protokolliert wurde.
    3. Fügen Sie ein Objekt dem Bucket hinzu. Cloud Storage benachrichtigt die Anwendung, die dann eine Nachricht protokolliert.
    4. Gehen Sie zur Logging-Seite für Ihr Projekt. Aktualisieren Sie die Liste der protokollierten Nachrichten und suchen Sie nach der Nachricht für die Objektkopie.
  6. Entfernen Sie den Benachrichtigungskanal.
    Entfernen Sie den Benachrichtigungskanal, indem Sie die Kanal-ID und den Ressourcenkennzeichner angeben, die beim Senden des Benachrichtigungsbefehls zur Überwachung des Buckets zurückgegeben wurden.