Benachrichtigungen bei Ressourcenänderungen

In diesem Dokument wird beschrieben, wie Sie Push-Benachrichtigungen verwenden, um Ihre Anwendung über Änderungen an einer Ressource zu informieren.

Überblick

Die Google Drive API bietet Push-Benachrichtigungen, mit denen Sie Änderungen an Ressourcen überwachen können. Mit diesem Feature können Sie die Leistung Ihrer Anwendung verbessern. Sie können die zusätzlichen Netzwerk- und Rechenkosten für das Abfragen von Ressourcen eliminieren, um festzustellen, ob sie sich geändert haben. Jedes Mal, wenn sich eine überwachte Ressource ändert, benachrichtigt die Google Drive API Ihre Anwendung.

Wenn Sie Push-Benachrichtigungen verwenden möchten, müssen Sie zwei Schritte ausführen:

• Richten Sie Ihre Empfangs-URL oder einen „Webhook“-Callback-Empfänger ein.

  Dies ist ein HTTPS-Server, der die API-Benachrichtigungen verarbeitet, die ausgelöst werden, wenn sich eine Ressource ändert.

• Richten Sie für jeden Ressourcenendpunkt, den Sie beobachten möchten, einen Benachrichtigungskanal ein.

  Ein Kanal gibt Routinginformationen für Benachrichtigungen an. Bei der Kanaleinrichtung musst du die URL angeben, unter der du Benachrichtigungen erhalten möchtest. Wenn sich die Ressource eines Kanals ändert, sendet die Google Drive API eine Benachrichtigung als POST-Anfrage an diese URL.

Hinweis:Das Wort „Kanal“ in diesem Dokument bezieht sich speziell auf einen Benachrichtigungskanal und nicht auf andere Kanaltypen, die in dieser API oder diesem Dienst verwendet werden.

Derzeit unterstützt die Google Drive API Benachrichtigungen über Änderungen an den Methoden files und changes.

Benachrichtigungskanäle erstellen

Wenn Sie Push-Benachrichtigungen anfordern möchten, müssen Sie für jede Ressource, die Sie überwachen möchten, einen Benachrichtigungskanal einrichten. Nachdem Sie die Benachrichtigungskanäle eingerichtet haben, informiert die Google Drive API Ihre Anwendung über beobachtete Ressourcenänderungen.

Wiedergabeanfragen senden

Jede Watchable Google Drive API-Ressource ist mit einer watch-Methode mit einem URI der folgenden Form verknüpft:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

Wenn Sie einen Benachrichtigungskanal für Nachrichten über Änderungen an einer bestimmten Ressource einrichten möchten, senden Sie eine POST-Anfrage an die Methode watch für die Ressource.

Jeder Benachrichtigungskanal ist sowohl mit einem bestimmten Nutzer als auch einer bestimmten Ressource (oder Gruppe von Ressourcen) verknüpft. Eine watch-Anfrage ist nur erfolgreich, wenn der aktuelle Nutzer oder das aktuelle Dienstkonto Inhaber oder Zugriffsberechtigung für diese Ressource hat.

Beispiele

Das folgende Codebeispiel zeigt, wie Sie mit einer channels-Ressource mithilfe der files.watch-Methode nach Änderungen an einer einzelnen files-Ressource suchen:

POST https://www.googleapis.com/drive/v3/files/fileId/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your files channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

Das folgende Codebeispiel zeigt, wie eine channels-Ressource verwendet wird, um mit der Methode changes.watch alle changes zu beobachten:

POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

Erforderliche Properties

Bei jeder watch-Anfrage müssen Sie folgende Felder angeben:

• Ein id-Attributstring, der diesen neuen Benachrichtigungskanal in Ihrem Projekt eindeutig identifiziert. Wir empfehlen die Verwendung einer UUID (Universally Unique Identifier) oder eines ähnlichen eindeutigen Strings. Maximale Länge: 64 Zeichen

  Der von Ihnen festgelegte ID-Wert wird im HTTP-Header X-Goog-Channel-Id jeder Benachrichtigung, die Sie für diesen Kanal erhalten, zurückgegeben.

• Ein type-Attributstring mit dem Wert web_hook.

• Ein address-Property-String, der auf die URL festgelegt ist, die Benachrichtigungen für diesen Benachrichtigungskanal erfasst und darauf antwortet. Dies ist die Webhook-Callback-URL, die HTTPS verwenden muss.

  Die Google Drive API kann nur dann Benachrichtigungen an diese HTTPS-Adresse senden, wenn auf Ihrem Webserver ein gültiges SSL-Zertifikat installiert ist. Folgende Zertifikate sind nicht gültig:

  • selbst signierte Zertifikate.
  • von einer nicht vertrauenswürdigen Quelle signierte Zertifikate
  • gesperrte Zertifikate
  • Zertifikate, deren Betreff nicht mit dem Zielhostnamen übereinstimmt.

Optionale Attribute

Du kannst diese optionalen Felder auch mit deiner watch-Anfrage angeben:

• Ein token-Attribut, das einen beliebigen Stringwert zur Verwendung als Kanaltoken angibt. Sie können Tokens für Benachrichtigungskanäle für verschiedene Zwecke verwenden. Mit dem Token können Sie beispielsweise prüfen, ob jede eingehende Nachricht zu einem von Ihrer Anwendung erstellten Kanal gehört, um sicherzustellen, dass die Benachrichtigung nicht gefälscht wird. Alternativ können Sie die Nachricht je nach Zweck dieses Kanals an das richtige Ziel innerhalb Ihrer Anwendung weiterleiten. Maximale Länge: 256 Zeichen

  Das Token ist im HTTP-Header X-Goog-Channel-Token in jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Kanal empfängt.

  Wenn Sie Tokens für Benachrichtigungskanäle verwenden, empfehlen wir Folgendes:

  • Verwenden Sie ein erweiterbares Codierungsformat, z. B. URL-Suchparameter. Beispiel: forwardTo=hr&createdBy=mobile

  • Geben Sie keine sensiblen Daten wie OAuth-Tokens an.

  Hinweis: Wenn Sie vertrauliche Daten senden müssen, müssen diese verschlüsselt werden, bevor Sie sie dem Token hinzufügen.

• Ein expiration-Property-String, der auf einen Unix-Zeitstempel (in Millisekunden) für das Datum und die Uhrzeit festgelegt ist, zu der die Google Drive API keine Nachrichten mehr für diesen Benachrichtigungskanal senden soll.

  Wenn ein Kanal eine Ablaufzeit hat, wird er (im visuell lesbaren Format) als Wert des HTTP-Headers X-Goog-Channel-Expiration in jede Benachrichtigung eingefügt, die Ihre Anwendung für diesen Kanal empfängt.

Hinweis:Für die Google Drive API beträgt die maximale Ablaufzeit 86.400 Sekunden (1 Tag) nach der aktuellen Zeit für die Ressource files und 604.800 Sekunden (1 Woche) für changes. Wenn Sie das Attribut expiration nicht in der Anfrage festlegen, wird die Ablaufzeit standardmäßig auf 3.600 Sekunden nach der aktuellen Uhrzeit festgelegt.

Weitere Informationen zur Anfrage finden Sie in der API-Referenz in der Methode watch für die Methoden files und changes.

Antwort ansehen

Wenn die watch-Anfrage erfolgreich einen Benachrichtigungskanal erstellt, wird der HTTP-Statuscode 200 OK zurückgegeben.

Der Nachrichtentext der Überwachungsantwort enthält Informationen über den gerade erstellten Benachrichtigungskanal, wie im folgenden Beispiel dargestellt.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable.
}

Zusätzlich zu den Properties, die du im Rahmen der Anfrage gesendet hast, enthalten die zurückgegebenen Informationen auch resourceId und resourceUri zur Identifizierung der Ressource, die in diesem Benachrichtigungskanal beobachtet wird.

Hinweis: Das Attribut resourceId ist eine stabile, versionsunabhängige Kennzeichnung für die Ressource. Das Attribut resourceUri ist der kanonische URI der beobachteten Ressource im Kontext der aktuellen API-Version und ist daher versionsspezifisch.

Sie können die zurückgegebenen Informationen an andere Benachrichtigungskanalvorgänge übergeben, z. B. wenn Sie keine Benachrichtigungen mehr erhalten möchten.

Weitere Informationen zur Antwort finden Sie in der API-Referenz in der Methode watch für die Methoden files und changes.

Nachricht synchronisieren

Nachdem Sie einen Benachrichtigungskanal zum Überwachen einer Ressource erstellt haben, sendet die Google Drive API eine sync-Nachricht, um anzugeben, dass Benachrichtigungen gestartet werden. Der X-Goog-Resource-State-HTTP-Header-Wert für diese Nachrichten lautet sync. Aufgrund von Problemen mit dem Netzwerk-Timing kann es sein, dass die sync-Nachricht bereits empfangen wird, bevor Sie die Antwort der watch-Methode erhalten.

Sie können die sync-Benachrichtigung ignorieren, Sie können sie aber auch verwenden. Wenn du den Kanal beispielsweise nicht behalten möchtest, kannst du die Werte X-Goog-Channel-ID und X-Goog-Resource-ID in einem Aufruf verwenden, um keine Benachrichtigungen mehr zu erhalten. Sie können auch die Benachrichtigung sync verwenden, um eine Initialisierung durchzuführen, um sich auf spätere Ereignisse vorzubereiten.

Das Format der sync-Nachrichten, die die Google Drive API an Ihre Empfänger-URL sendet, wird unten angezeigt.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

Synchronisierungsnachrichten haben immer den X-Goog-Message-Number-HTTP-Header-Wert 1. Jede nachfolgende Benachrichtigung für diesen Kanal hat eine größere Nachrichtennummer als die vorherige. Die Nachrichtennummern sind jedoch nicht fortlaufend.

Benachrichtigungskanäle verlängern

Ein Benachrichtigungskanal kann eine Ablaufzeit haben. Der Wert wird entweder durch Ihre Anfrage oder durch interne Limits oder Standardwerte der Google Drive API bestimmt (es wird der restriktivere Wert verwendet). Die Ablaufzeit des Kanals, falls vorhanden, wird als Unix-Zeitstempel (in Millisekunden) in die Informationen aufgenommen, die von der Methode watch zurückgegeben werden. Außerdem sind das Ablaufdatum und die Ablaufzeit (in menschenlesbarem Format) in jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Kanal im HTTP-Header X-Goog-Channel-Expiration erhält.

Derzeit gibt es keine automatische Möglichkeit, einen Benachrichtigungskanal zu verlängern. Kurz vor Ablauf eines Kanals müssen Sie ihn durch einen neuen ersetzen. Dazu rufen Sie die Methode watch auf. Wie immer musst du einen eindeutigen Wert für die id-Property des neuen Kanals verwenden. Beachten Sie, dass es wahrscheinlich einen „Überlappungszeitraum“ geben kann, in dem die beiden Benachrichtigungskanäle für dieselbe Ressource aktiv sind.

Benachrichtigungen erhalten

Immer wenn sich eine überwachte Ressource ändert, erhält Ihre Anwendung eine Benachrichtigung, in der die Änderung beschrieben wird. Die Google Drive API sendet diese Nachrichten als HTTPS-POST-Anfragen an die URL, die Sie als Property address für diesen Benachrichtigungskanal angegeben haben.

Hinweis:Bei HTTPS-Anfragen für die Zustellung von Benachrichtigungen ist der User-Agent APIs-Google angegeben und es werden robots.txt-Anweisungen berücksichtigt, wie in den APIs des Google-User-Agents beschrieben.

Format der Benachrichtigung interpretieren

Alle Benachrichtigungen enthalten eine Reihe von HTTP-Headern mit dem Präfix X-Goog-. Einige Arten von Benachrichtigungen können auch einen Nachrichtentext enthalten.

Header

Benachrichtigungen, die von der Google Drive API an Ihre Empfangs-URL gesendet werden, enthalten die folgenden HTTP-Header:

Header	Beschreibung
Immer vorhanden
X-Goog-Channel-ID	UUID oder ein anderer eindeutiger String, den Sie angegeben haben, um diesen Benachrichtigungskanal zu identifizieren.
X-Goog-Message-Number	Ganzzahl, die diese Nachricht für diesen Benachrichtigungskanal identifiziert. Der Wert für sync-Nachrichten ist immer 1. Bei jeder weiteren Nachricht auf dem Kanal erhöht sich die Anzahl der Nachrichten. Sie werden jedoch nicht fortlaufend gesendet.
X-Goog-Resource-ID	Ein intransparenter Wert, der die beobachtete Ressource identifiziert. Diese ID ist in allen API-Versionen stabil.
X-Goog-Resource-State	Der neue Ressourcenstatus, der die Benachrichtigung ausgelöst hat. Mögliche Werte: sync, add, remove, update, trash, untrash oder change.
X-Goog-Resource-URI	Eine API-versionsspezifische Kennung für die überwachte Ressource.
Gelegentlich vorhanden
X-Goog-Changed	Weitere Informationen zu den Änderungen. Mögliche Werte: content, parents, children oder permissions. Nicht mit sync-Nachrichten bereitgestellt.
X-Goog-Channel-Expiration	Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals in einem für Menschen lesbaren Format. Ist nur vorhanden, wenn definiert.
X-Goog-Channel-Token	Das von Ihrer Anwendung festgelegte Benachrichtigungskanaltoken, mit dem Sie die Benachrichtigungsquelle prüfen können. Ist nur vorhanden, wenn definiert.

Benachrichtigungen für files und changes sind leer.

Beispiele

Benachrichtigungsnachricht für files Ressourcen ändern, die keinen Anfragetext enthält:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State:  update
X-Goog-Changed: content,properties
X-Goog-Message-Number: 10

Änderungsbenachrichtigung für changes-Ressourcen, die einen Anfragetext enthält:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 118
X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes
X-Goog-Resource-State:  changed
X-Goog-Message-Number: 23

{
  "kind": "drive#changes"
}

Auf Benachrichtigungen reagieren

Zur Anzeige des Erfolgs können Sie einen der folgenden Statuscodes zurückgeben: 200, 201, 202, 204 oder 102.

Wenn Ihr Dienst die API-Clientbibliothek von Google verwendet und 500, 502, 503 oder 504 zurückgibt, wiederholt die Google Drive API den Vorgang mit exponentiellem Backoff. Jeder andere Rückgabestatuscode gilt als Nachrichtenfehler.

Benachrichtigungsereignisse der Google Drive API

Dieser Abschnitt enthält Details zu den Benachrichtigungen, die Sie erhalten können, wenn Sie Push-Benachrichtigungen mit der Google Drive API verwenden.

X-Goog-Resource-State	Gilt für	Zugestellt, wenn
sync	files, changes	Ein Kanal wurde erstellt. Du wirst dann entsprechende Benachrichtigungen erhalten.
add	files	Eine Ressource wurde erstellt oder freigegeben.
remove	files	Eine vorhandene Ressource wurde gelöscht oder ihre Freigabe wurde aufgehoben.
update	files	Mindestens eine Eigenschaft (Metadaten) einer Ressource wurde aktualisiert.
trash	files	Eine Ressource wurde in den Papierkorb verschoben.
untrash	files	Eine Ressource wurde aus dem Papierkorb entfernt.
change	changes	Mindestens ein Änderungsprotokoll wurde hinzugefügt.

Der Liste können im Laufe der Zeit weitere Ressourcenstatusereignisse hinzugefügt werden. Möglicherweise erhalten Sie unerwartete Ereignistypen. Ihre Event-Handler sollten diese ignorieren.

Für update-Ereignisse kann der X-Goog-Changed-HTTP-Header angegeben werden. Dieser Header enthält eine durch Kommas getrennte Liste, in der die Arten der vorgenommenen Änderungen beschrieben werden.

Art der Änderung	Gibt an
content	Der Ressourceninhalt wurde aktualisiert.
properties	Mindestens ein Ressourcenattribut wurde aktualisiert.
parents	Mindestens ein übergeordnetes Element der Ressource wurde hinzugefügt oder entfernt.
children	Mindestens ein untergeordnetes Ressourcenobjekt wurde hinzugefügt oder entfernt.
permissions	Die Ressourcenberechtigungen wurden aktualisiert.

Beispiel mit X-Goog-Changed-Header:

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

Benachrichtigungen deaktivieren

Mit der Eigenschaft expiration wird festgelegt, wann die Benachrichtigungen automatisch beendet werden. Wenn du für einen bestimmten Kanal keine Benachrichtigungen mehr erhalten möchtest, bevor er abläuft, kannst du die Methode stop unter dem folgenden URI aufrufen:

https://www.googleapis.com/drive/v3/channels/stop

Bei dieser Methode musst du mindestens die Properties id und resourceId des Kanals angeben, wie im folgenden Beispiel gezeigt. Wenn die Google Drive API mehrere Ressourcentypen mit watch-Methoden hat, gibt es nur eine stop-Methode.

Nur Nutzer mit der entsprechenden Berechtigung können einen Kanal beenden. Wichtig ist insbesondere:

• Wenn der Kanal von einem regulären Nutzerkonto erstellt wurde, kann nur derselbe Nutzer aus demselben Client (wie durch die OAuth 2.0-Client-IDs der Authentifizierungstokens identifiziert), der den Kanal erstellt hat, den Kanal beenden.
• Wenn der Kanal von einem Dienstkonto erstellt wurde, kann jeder Nutzer desselben Clients ihn beenden.

Das folgende Codebeispiel zeigt, wie Sie den Empfang von Benachrichtigungen deaktivieren:

POST https://www.googleapis.com/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}