Ä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.

Diese Funktion hat nichts mit Cloud Pub/Sub-Benachrichtigungen für Cloud Storage zu tun. Cloud Pub/Sub-Benachrichtigungen sollten Sie verwenden, um Änderungen an Objekten in Cloud Storage-Buckets zu erfassen, weil sie schneller, flexibler, leichter einzurichten und günstiger sind.

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.

Die Abbildung unten zeigt ein Beispiel für den Datenfluss in einer Anwendung, die Änderungsbenachrichtigungen verarbeitet. Dafür kann jeder Anwendungsserver verwendet werden, der HTTPS-POST-Anfragen empfangen kann.

Komponenten der Änderungsbenachrichtigung für Objekte
Komponenten der Änderungsbenachrichtigung für Objekte

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 finden die Kennzeichnung in der Antwort auf eine Überwachungsanfrage oder im Header X-Goog-Resource-Id von Nachrichten über Benachrichtigungsereignisse.
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

Zum Überwachen eines Buckets auf Ereignisse, die eine Änderungsbenachrichtigung erfordern, können Sie den Befehl gsutil notification watchbucket verwenden:

gsutil notification watchbucket [-i ChannelId] [-t ClientToken] ApplicationUrl gs://BucketName

Dadurch wird ein Benachrichtigungskanal erstellt, über den Benachrichtigungsereignisse an die Anwendungs-URL des jeweiligen Buckets gesendet werden. Dieser Benachrichtigungskanal enthält das benutzerdefinierte Client-Token und die Kanal-ID, falls angegeben.

Mit dem Befehl gsutil help notification watchbucket können Sie weitere Informationen dazu abrufen.

Hier sehen Sie ein Beispiel für eine POST-Anfrage, die von gsutil zum Überwachen eines Buckets generiert wurde:

POST /storage/v1/b/BucketName/o/watch?alt=json HTTP/1.1
Host: www.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

Der für das Überwachen eines Buckets erstellte Benachrichtigungskanal wird mit dem Google Cloud Platform-Projekt der Anwendung verknüpft, die die API-Anfrage initiiert hat. Wenn also ein Nutzer Zugriff auf eine installierte Anwendung oder eine Webanwendung über einen OAuth2-Ablauf gewährt, wird der von der Anwendung erstellte Benachrichtigungskanal mit dem Projekt der Anwendung verknüpft und nicht mit dem Projekt, das den überwachten Bucket enthält.

Die Autorisierungskonfiguration für Änderungsbenachrichtigungen für Objekte erfolgt in drei Schritten:

Dienstkonto erstellen

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.

Sie sollten ein vorhandenes Dienstkonto verwenden oder ein neues erstellen und den zugehörigen privaten Schlüssel herunterladen.

gsutil für die Verwendung des Dienstkontos konfigurieren

Wenn Sie gsutil für die Verwendung des Dienstkontos konfigurieren möchten, können Sie das Dienstkonto mit dem Google Cloud SDK als Konto mit Anmeldedaten für die Arbeit mit Google Cloud Platform-Ressourcen hinzufügen, was den Einsatz der Änderungsbenachrichtigung für Objekte ermöglicht. Nachdem Sie die Anmeldedaten hinzugefügt haben, verwenden alle gsutil-Befehle die Anmeldedaten des Dienstkontos.

So erstellen Sie Anmeldedaten basierend auf dem Dienstkonto:

  1. Sie benötigen die neueste Version des Cloud SDK. Die Komponenten lassen sich mit dem folgenden Befehl aktualisieren:
    gcloud components update
    
  2. Geben Sie im Befehl gcloud auth activate-service-account die E-Mail-Adresse und den privaten Schlüssel des Dienstkontos an:
    gcloud auth activate-service-account service-account-email --key-file path/to/key.p12
    

    wobei:

    • service-account-email ist die E-Mail-Adresse des Dienstkontos. Sie sieht in etwa so aus: 1234567890123-abcdefghijklmonpqrstuvwxz01234567@developer.gserviceaccount.com.
    • path/to/key.p12 ist der Schlüssel, den Sie beim Erstellen des Dienstkontos heruntergeladen haben. Falls Sie den Schlüssel nicht mehr haben, können Sie auf der Seite Anmeldedaten in der Google Cloud Platform Console einen neuen erstellen.
  3. Bestätigen Sie, dass das Dienstkonto das Konto mit den aktiven Anmeldedaten ist.
    $ gcloud auth list
    Credentialed accounts:
    - 1234567890123-abcdefghijklmonpqrstuvwxz01234567@developer.gserviceaccount.com (active)
    

    Neben den Anmeldedaten des Dienstkontos sollte active angezeigt werden. Jetzt verwenden alle gsutil-Befehle für Änderungsbenachrichtigungen für Objekte die Anmeldedaten dieses Dienstkontos.

Domain für den Empfang von Benachrichtigungen festlegen

Überwachungsanfragen sind nur dann erfolgreich, wenn die Benachrichtigungs-URL eine Domain ist, die vom Projekt des Benachrichtigungskanals auf die weiße Liste gesetzt wurde.

So setzen Sie eine Domain auf die weiße Liste:

  1. Überprüfen Sie, ob Sie der Inhaber der Domain sind, indem Sie den Search Console-Bestätigungsvorgang nutzen.
  2. Gehen Sie in der GCP Console auf der Seite "Anmeldedaten" zum Tab "Domain-Überprüfung".

    Zur Seite Anmeldedaten

  3. Auf „Domain hinzufügen“ klicken.
  4. In dem Dialog Webhook-Benachrichtigungen konfigurieren die zu bestätigende Domain eingeben.

    Konfigurieren des Dialogs "Webhook-Benachrichtigungen"

  5. Auf „Domain hinzufügen“ klicken.

    Um Fehler bei der Domain-Bestätigung zu beheben:

    • Die Domain muss in der Search Console mit einer https://-URL registriert oder mit der Bestätigungsmethode des Domainnamen-Anbieters bestätigt worden sein.
    • Achten Sie darauf, dass Sie entweder Inhaber oder Bearbeiter des Projekts in der GCP Console (siehe Projektmitglieder und Berechtigungen) und Website-Inhaber der Domain sein müssen, die die Benachrichtigungen erhalten wird. Wenn Sie kein Website-Inhaber der Domain sind, kontaktieren Sie den Website-Inhaber, um als bestätigter Inhaber hinzugefügt zu werden (mehr Informationen in Inhaber hinzufügen oder entfernen).
    • Sie können den Google API Explorer für Webmaster Tools verwenden, um eine Liste von Websites auf der Domain abzurufen und insbesondere um zu sehen, ob das Attribut siteUrl der Domain mit https:// beginnt.

Benachrichtigungskanal entfernen

Mit dem Befehl gsutil notification stopchannel können Sie einen Benachrichtigungskanal beenden:

gsutil notification stopchannel ChannelId ResourceId

Dadurch werden keine Benachrichtigungsereignisse mehr an den angegebenen Ressourcenkennzeichner und die Kanal-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.

Mit dem Befehl gsutil help notification stopchannel können Sie weitere Informationen dazu abrufen.

Hier sehen Sie ein Beispiel für eine POST-Anfrage, die von gsutil zum Beenden eines Kanals generiert wurde:

POST /storage/v1/channels/stop HTTP/1.1
Host: www.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. Sie 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://www.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://www.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://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName?generation=1367014943964000&alt=media",
 "owner": {
  "entity": "user-jane@gmail.com"
 },
 "crc32c": "C7+82w==",
 "etag": "COD2jMGv6bYCEAE="
}
Dabei lautet der Wert für 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 sie 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 übermittelt:
    • 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.

In der folgenden Abbildung ist die Zeitachse der grundlegenden Ereignisse beim Empfang einer Benachrichtigung dargestellt – von der Erstellung eines Buckets bis zur Verarbeitung der zugehörigen Änderungsbenachrichtigungsereignisse:

Zeitachse der Änderungsbenachrichtigung für Objekte
Zeitachse der Änderungsbenachrichtigung für Objekte

Die Beispielanwendung enthält eine Klasse namens MainPage. Wenn ein Nutzer ein Objekt aktualisiert oder dem Bucket hinzufügt, verarbeitet die MainPage-Klasse das Benachrichtigungsereignis. Der Einfachheit halber verzeichnet die post-Methode, die für die eigentliche Verarbeitung zuständig ist, nur eine Nachricht mit dem Zeitpunkt, 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: <ApplicationId>
    version: 1
    runtime: python27
    api_version: 1
    threadsafe: true
    
    handlers:
    - url: /.*
      script: change_notification_client.app
    
  2. Anwendung erstellen
    Im folgenden Beispiel wird eine Clientanwendung zur Verarbeitung der Änderungsbenachrichtigungs-Ereignisse eines Buckets implementiert. Nennen Sie sie change_notification_client.py und stellen Sie sie 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, indem Sie den folgenden Befehl ausführen:
    gsutil acl ch -u ApplicationId@appspot.gserviceaccount.com:OWNER gs://BucketName
    
  4. Bucket auf Objektänderungen überwachen
    Erstellen Sie einen Benachrichtigungskanal für Ihre Anwendung. Dazu überwachen Sie den Bucket mit gsutil:
    gsutil notification watchbucket ApplicationUrl gs://BucketName
    
    Dabei ist ApplicationUrl die URL der App 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 überprüfen Sie, ob die Anwendung bereitgestellt wurde und korrekt funktioniert:
      curl -X Post https://<ApplicationId>.appspot.com
      
      Falls Sie Ihren eigenen Domainnamen für die Bereitstellung der Anwendung verwendet haben, setzen Sie im Befehl diesen anstelle von appspot.com ein.
    2. Gehen Sie zur Logging-Seite für Ihr Projekt. Aktualisieren Sie ggf. die Liste der protokollierten Nachrichten. Sehen Sie nach, ob die von der Anwendung ausgegebene Log-Nachricht protokolliert wurde.
    3. Fügen Sie ein Objekt dem Bucket hinzu. Geben Sie dazu im gsutil-Tool Folgendes ein:
      gsutil cp ObjectName gs://BucketName/
      
      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. Benachrichtigungskanal entfernen
    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.
    gsutil notification stopchannel <channel_id> <resource_identifier>
    

Zurück nach oben

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

Feedback geben zu...