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 im Blick behalten können. Mit diesem Feature können Sie die Leistung Ihrer Anwendung verbessern. Sie eliminieren zusätzliche Netzwerk- und Rechenkosten, die mit dem Abfragen von Ressourcen verbunden sind, um festzustellen, ob sie sich geändert haben. Wenn sich eine beobachtete Ressource ändert, benachrichtigt die Google Drive API Ihre Anwendung.

Um Push-Benachrichtigungen zu verwenden, müssen Sie zwei Dinge tun:

  • Richten Sie die Empfangs-URL oder den Webhook-Rückrufempfänger ein.

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

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

    Ein Kanal gibt Routinginformationen für Benachrichtigungen an. Bei der Einrichtung des Kanals musst du die URL angeben, unter der Benachrichtigungen gesendet werden sollen. Immer wenn sich die Ressource eines Kanals ändert, sendet die Google Drive API eine Benachrichtigung als POST-Anfrage an diese URL.

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

Benachrichtigungskanäle erstellen

Zum Anfordern von Push-Benachrichtigungen müssen Sie für jede Ressource, die Sie überwachen möchten, einen Benachrichtigungskanal einrichten. Nach der Einrichtung der Benachrichtigungskanäle informiert die Google Drive API Ihre Anwendung über Änderungen an beobachteten Ressourcen.

Wiedergabeanfragen stellen

Jeder Watchable Google Drive API-Ressource ist eine watch-Methode bei einem URI im folgenden Format zugeordnet:

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

Zum Einrichten eines Benachrichtigungskanals für Nachrichten über Änderungen an einer bestimmten Ressource senden Sie eine POST-Anfrage an die Methode watch für die Ressource.

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

Beispiele

Das folgende Codebeispiel zeigt, wie Sie eine channels-Ressource verwenden, um mit der Methode files.watch nach Änderungen an einer einzelnen files-Ressource zu 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 Sie eine channels-Ressource verwenden, um mithilfe der Methode changes.watch alle changes zu überwachen:

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 die folgenden Felder angeben:

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

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

  • Ein type-Attributstring, der auf den Wert web_hook festgelegt ist.

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

    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

Sie können diese optionalen Felder auch in der watch-Anfrage angeben:

  • Eine token-Eigenschaft, die einen beliebigen Stringwert angibt, der als Kanaltoken verwendet werden soll. Tokens für Benachrichtigungskanäle lassen sich für verschiedene Zwecke verwenden. Sie können das Token beispielsweise verwenden, um zu überprüfen, ob alle eingehenden Nachrichten zu einem Kanal gehören, den Ihre Anwendung erstellt hat, um sicherzustellen, dass die Benachrichtigung nicht gefälscht wird, oder um die Nachricht basierend auf dem Zweck dieses Kanals an das richtige Ziel innerhalb Ihrer Anwendung weiterzuleiten. Maximale Länge: 256 Zeichen.

    Das Token ist im HTTP-Header X-Goog-Channel-Token jeder Benachrichtigungsnachricht 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 wie URL-Suchparameter. Beispiel: forwardTo=hr&createdBy=mobile

    • Verwenden Sie keine sensiblen Daten wie OAuth-Tokens.

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

    Wenn ein Kanal eine Ablaufzeit hat, wird er als Wert des HTTP-Headers X-Goog-Channel-Expiration (in visuell lesbarem Format) in jede Benachrichtigungsnachricht aufgenommen, die Ihre Anwendung für diesen Kanal erhält.

Weitere Informationen zur Anfrage finden Sie in der API-Referenz unter 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 Smartwatch-Antwort enthält Informationen über den gerade erstellten Benachrichtigungskanal, wie im folgenden Beispiel gezeigt.

{
  "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 Attributen, die Sie im Rahmen der Anfrage gesendet haben, enthalten die zurückgegebenen Informationen auch resourceId und resourceUri, um die über diesen Benachrichtigungskanal beobachtete Ressource zu identifizieren.

Sie können die zurückgegebenen Informationen an andere Vorgänge des Benachrichtigungskanals ü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 Beobachten einer Ressource erstellt haben, sendet die Google Drive API eine sync-Nachricht, um anzuzeigen, dass Benachrichtigungen gestartet werden. Der HTTP-Header-Wert X-Goog-Resource-State für diese Nachrichten ist sync. Aufgrund von Netzwerkzeitproblemen ist es möglich, dass die sync-Nachricht noch vor der Antwort der watch-Methode empfangen wird.

Die Benachrichtigung sync kann ignoriert, aber auch verwendet werden. Wenn du beispielsweise den Kanal 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 die Benachrichtigung sync auch verwenden, um eine Initialisierung durchzuführen, um sich auf spätere Ereignisse vorzubereiten.

Unten sehen Sie das Format der sync-Nachrichten, die die Google Drive API an Ihre Empfangs-URL sendet.

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 HTTP-Header-Wert X-Goog-Message-Number 1. Jede nachfolgende Benachrichtigung für diesen Kanal hat eine Nachrichtennummer, die größer als die vorherige ist. 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 Standardeinstellungen der Google Drive API bestimmt. Dabei wird der restriktivere Wert verwendet. Die Ablaufzeit des Kanals, sofern vorhanden, ist als Unix-Zeitstempel (in Millisekunden) in den Informationen enthalten, die von der Methode watch zurückgegeben werden. Darüber hinaus sind das Ablaufdatum und die Ablaufzeit (in visuell lesbarem 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 Verlängerung eines Benachrichtigungskanals. Wenn ein Kanal kurz vor seinem Ablauf steht, müssen Sie ihn durch einen neuen Kanal ersetzen. Dazu rufen Sie die Methode watch auf. Wie immer musst du auch für das Attribut id des neuen Kanals einen eindeutigen Wert verwenden. Wenn die beiden Benachrichtigungskanäle für dieselbe Ressource aktiv sind, kann es zu einer Überschneidung kommen.

Benachrichtigungen erhalten

Wenn sich eine beobachtete Ressource ändert, erhält Ihre Anwendung eine Benachrichtigung mit einer Beschreibung der Änderung. Die Google Drive API sendet diese Nachrichten als HTTPS-POST-Anfragen an die URL, die Sie als Attribut address für diesen Benachrichtigungskanal angegeben haben.

Nachrichtenformat für Benachrichtigungen interpretieren

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

Header

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

Header Beschreibung
Immer anzeigen
X-Goog-Channel-ID UUID oder ein anderer eindeutiger String, den Sie zur Identifizierung dieses Benachrichtigungskanals angegeben haben.
X-Goog-Message-Number Ganzzahl zur Identifizierung dieser Nachricht für diesen Benachrichtigungskanal. Der Wert für sync-Nachrichten ist immer 1. Die Anzahl der Nachrichten erhöht sich mit jeder nachfolgenden Nachricht auf dem Kanal, sie folgen jedoch nicht der Reihe nach.
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.
Manchmal anwesend
X-Goog-Changed Weitere Details zu den Änderungen. Mögliche Werte: content, parents, children oder permissions. Nicht mit sync-Nachrichten angegeben.
X-Goog-Channel-Expiration Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals in menschenlesbarem Format. Nur vorhanden, wenn definiert.
X-Goog-Channel-Token Token des Benachrichtigungskanals, das von Ihrer Anwendung festgelegt wurde und mit dem Sie die Benachrichtigungsquelle prüfen können. Ist nur vorhanden, wenn definiert.

Benachrichtigungen für files und changes sind leer.

Beispiele

Ändern Sie die Benachrichtigungsnachricht für files-Ressourcen, 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

Benachrichtigungsnachricht für changes-Ressourcen ändern, 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

Bei erfolgreicher Ausführung können Sie einen der folgenden Statuscodes zurückgeben: 200, 201, 202, 204 oder 102.

Wenn der Dienst die API-Clientbibliothek von Google verwendet und 500, 502, 503 oder 504 zurückgibt, versucht die Google Drive API einen neuen Versuch mit exponentiellem Backoff. Jeder andere Rückgabestatuscode wird als Nachrichtenfehler betrachtet.

Informationen zu Benachrichtigungsereignissen 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 Der Kanal wurde erstellt. Du wirst in Zukunft Benachrichtigungen dafür erhalten.
add files Eine Ressource wurde erstellt oder freigegeben.
remove files Eine vorhandene Ressource wurde gelöscht oder ihre Freigabe wurde zurückgenommen.
update files Mindestens ein Attribut (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.

Für update-Ereignisse wird möglicherweise der HTTP-Header X-Goog-Changed angegeben. 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 Inhalt der Ressource wurde aktualisiert.
properties Mindestens ein Ressourcenattribut wurde aktualisiert.
parents Mindestens ein übergeordnetes Element der Ressource wurde hinzugefügt oder entfernt.
children Mindestens ein untergeordnetes Ressourcenelement 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. Sie können festlegen, dass Sie für einen bestimmten Kanal keine Benachrichtigungen mehr erhalten möchten, bevor er abläuft. Rufen Sie dazu die Methode stop unter dem folgenden URI auf:

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

Für diese Methode müssen mindestens die Attribute id und resourceId des Kanals angegeben werden, 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 über ein reguläres Nutzerkonto erstellt wurde, kann nur derselbe Nutzer vom Client, der den Kanal erstellt hat, den Kanal beenden. Er wird durch die OAuth 2.0-Client-IDs der Authentifizierungstokens identifiziert.
  • Wenn der Kanal von einem Dienstkonto erstellt wurde, kann jeder Nutzer desselben Clients den Kanal beenden.

Das folgende Codebeispiel zeigt, wie Sie keine Benachrichtigungen mehr erhalten:

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"
}