Benachrichtigungen bei Ressourcenänderungen

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

Übersicht

Die Google Drive API bietet Push-Benachrichtigungen, mit denen Sie Änderungen an Ressourcen beobachten können. Mit dieser Funktion können Sie die Leistung Ihrer Anwendung verbessern. Sie können die zusätzlichen Netzwerk- und Rechen kosten vermeiden, die beim Abrufen von Ressourcen anfallen, um festzustellen, ob sie sich geändert haben. Wenn sich eine überwachte Ressource ändert, benachrichtigt die Google Drive API Ihre Anwendung.

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

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

    Dies ist ein HTTPS-Server, der die API-Benachrichtigungsnachrichten 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 Benachrichtigungs Nachrichten an. Im Rahmen der Kanaleinrichtung müssen Sie die spezifische URL angeben, an die Sie Sie Benachrichtigungen erhalten möchten. Wenn sich die Ressource eines Kanals ändert, sendet die Google Drive API eine Benachrichtigungsnachricht als POST Anfrage an diese URL.

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

Benachrichtigungskanäle erstellen

Wenn Sie Push-Benachrichtigungen anfordern möchten, müssen Sie für jede Ressource, die Sie beobachten möchten, einen Benachrichtigungskanal einrichten. Nachdem Ihre Benachrichtigungskanäle eingerichtet wurden , informiert die Google Drive API Ihre Anwendung, wenn sich eine überwachte Ressource ändert.

Anfragen zum Beobachten stellen

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

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

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

Jeder Benachrichtigungskanal ist sowohl einem bestimmten Nutzer als auch einer bestimmten Ressource (oder einer Reihe von Ressourcen) zugeordnet. Eine watch Anfrage ist nur erfolgreich, wenn der aktuelle Nutzer oder das aktuelle Dienstkonto Inhaber dieser Ressource ist oder die Berechtigung hat, darauf zuzugreifen.

Beispiele

Das folgende Codebeispiel zeigt, wie Sie mit einer channels-Ressource die Methode files.watch verwenden, um Änderungen an einer einzelnen files-Ressource zu beobachten:

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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

Geben Sie im Anfragetext die id Ihres Kanals, den type als web_hook und Ihre Empfangs-URL in address an. Optional können Sie auch Folgendes angeben:

  • Ein token, das als Kanal-Token verwendet werden soll.
  • Eine expiration-Zeit in Millisekunden für die gewünschte Ablaufzeit des Kanals.

Das folgende Codebeispiel zeigt, wie Sie mit einer channels-Ressource die Methode changes.watch verwenden, um 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myChangesChannelDest",
  "expiration": 1426325213000
}

Geben Sie im Anfragetext die id Ihres Kanals, den type als web_hook und Ihre Empfangs-URL in address an. Optional können Sie auch Folgendes angeben:

  • Ein token, das als Kanal-Token verwendet werden soll.
  • Eine expiration-Zeit in Millisekunden für die gewünschte Ablaufzeit des Kanals.

Erforderliche Attribute

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, eine universell eindeutige ID (UUID) oder einen ähnlichen eindeutigen String zu verwenden. Maximale Länge: 64 Zeichen.

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

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

  • Ein address-Attributstring, der auf die URL festgelegt ist, die Benachrichtigungen für diesen Benachrichtigungskanal empfängt und darauf reagiert. Dies ist Ihre Webhook-Callback-URL und 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 Ziel hostname übereinstimmt.

Optionale Attribute

Sie können auch die folgenden optionalen Felder in Ihrer watch Anfrage angeben:

  • Ein token Attribut, das einen beliebigen Stringwert angibt, der als Kanal-Token verwendet werden soll. Sie können Benachrichtigungskanal Tokens für verschiedene Zwecke verwenden. Sie können das Token beispielsweise verwenden, um zu überprüfen, ob jede eingehende Nachricht für einen Kanal bestimmt ist, den Ihre Anwendung erstellt hat. So können Sie sicherstellen, dass die Benachrichtigung nicht gefälscht ist. Außerdem können Sie die Nachricht basierend auf dem Zweck dieses Kanals an das richtige Ziel in Ihrer Anwendung weiterleiten. Maximale Länge: 256 Zeichen.

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

    Wenn Sie Benachrichtigungskanal-Tokens verwenden, empfehlen wir Folgendes:

    • Verwenden Sie ein erweiterbares Codierungsformat wie URL-Abfrage parameter. Beispiel: forwardTo=hr&createdBy=mobile

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

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

    Wenn ein Kanal eine Ablaufzeit hat, wird sie als Wert des X-Goog-Channel-Expiration HTTP-Headers (in einem für Menschen lesbaren Format) in jeder Benachrichtigungsnachricht angegeben, die Ihre Anwendung für diesen Kanal erhält.

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

Antwort auf die Anfrage zum Beobachten

Wenn mit der watch Anfrage ein Benachrichtigung Kanal erstellt wird, wird der HTTP-Statuscode 200 OK zurückgegeben.

Der Nachrichtentext der Antwort auf die Anfrage zum Beobachten enthält Informationen zum gerade erstellten Benachrichtigungskanal, wie im folgenden Beispiel gezeigt.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

Der Antworttext enthält Details zum Kanal, z. B.:

  • kind: Gibt an, dass es sich um eine API-Kanalressource handelt.
  • id: Die ID, die Sie für diesen Kanal angegeben haben.
  • resourceId: Die ID der beobachteten Ressource.
  • resourceUri: Die versionsspezifische ID der beobachteten Ressource.
  • token: Das im Anfragetext angegebene Token.
  • expiration: Die Ablaufzeit des Kanals als Unix-Zeitstempel in Millisekunden.

Zusätzlich zu den Attributen, die Sie als Teil Ihrer Anfrage gesendet haben, enthalten die zurückgegebenen Informationen auch die resourceId und resourceUri um die Ressource zu identifizieren, die auf diesem Benachrichtigungskanal beobachtet wird.

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

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

Synchronisierungsnachricht

Nachdem Sie einen Benachrichtigungskanal zum Beobachten einer Ressource erstellt haben, sendet die Google Drive API eine sync Nachricht, um anzugeben, dass Benachrichtigungen gesendet werden. Der Wert des X-Goog-Resource-State HTTP Headers für diese Nachrichten ist sync. Aufgrund von Netzwerk Timing-Problemen kann es vorkommen, dass Sie die sync Nachricht erhalten, bevor Sie die watch Methodenantwort erhalten.

Sie können die sync-Benachrichtigung ignorieren, aber Sie können sie auch verwenden. Wenn Sie beispielsweise den Kanal nicht behalten möchten, können Sie 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 sync Benachrichtigung auch verwenden, um einige Initialisierungen vorzunehmen, um sich auf spätere Ereignisse vorzubereiten.

Das Format von sync Nachrichten, die die Google Drive API an Ihre Empfangs-URL sendet, ist unten dargestellt.

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

`sync`-Nachrichten haben immer den X-Goog-Message-Number HTTP Headerwert 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 erneuern

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

Derzeit gibt es keine automatische Möglichkeit, einen Benachrichtigungskanal zu erneuern. Wenn ein Kanal bald abläuft, müssen Sie ihn durch einen neuen ersetzen, indem Sie die watch Methode aufrufen. Wie immer müssen Sie für das id Attribut des neuen Kanals einen eindeutigen Wert verwenden. Es wird wahrscheinlich einen Zeitraum geben, in dem die beiden Benachrichtigungskanäle für dieselbe Ressource aktiv sind.

Benachrichtigungen erhalten

Wenn sich eine beobachtete Ressource ändert, erhält Ihre Anwendung eine Benachrichtigungsnachricht, in der die Änderung beschrieben wird. Die Google Drive API sendet diese Nachrichten als HTTPS-POST Anfragen an die URL, die Sie als address Attribut für diesen Benachrichtigungs kanal angegeben haben.

Format der Benachrichtigungsnachricht interpretieren

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

Header

Benachrichtigungsnachrichten, 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 anderer eindeutiger String, den Sie zur Identifizierung dieses Benachrichtigungskanals angegeben haben.
X-Goog-Message-Number Ganzzahl, die diese Nachricht für diesen Benachrichtigungskanal identifiziert. Der Wert ist für sync-Nachrichten immer 1. Die Nachrichtennummern werden für jede nachfolgende Nachricht im Kanal erhöht, sind aber nicht fortlaufend.
X-Goog-Resource-ID Ein intransparenter Wert, der die beobachtete Ressource identifiziert. Diese ID ist über API-Versionen hinweg 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 ID für die beobachtete Ressource.
Manchmal vorhanden
X-Goog-Changed Zusätzliche Details zu den Änderungen. Mögliche Werte: content, parents, children oder permissions . Wird nicht mit sync-Nachrichten bereitgestellt.
X-Goog-Channel-Expiration Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals in einem für Menschen lesbaren Format. Nur vorhanden, wenn definiert.
X-Goog-Channel-Token Benachrichtigungskanal-Token, das von Ihrer Anwendung festgelegt wurde und mit dem Sie die Benachrichtigungsquelle überprüfen können. Nur vorhanden, wenn definiert.

Benachrichtigungsnachrichten für files-Ressourcen (einschließlich add, remove, update, trash und untrash-Ereignisse) und changes-Ressourcen sind immer leer (der HTTP-Anfragetext ist leer, d.h. Content-Length: 0).

Beispiele

Benachrichtigungsnachricht für files-Ressourcen, wenn eine Ressource hinzugefügt wird (der Anfragetext ist leer):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 3a98f1a2b3c4d5e6f7
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:  add
X-Goog-Message-Number: 10

Benachrichtigungsnachricht für files-Ressourcen, wenn eine Ressource aktualisiert wird (der Anfragetext ist leer):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 3a98f1a2b3c4d5e6f7
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: 11

Benachrichtigungsnachricht für changes-Ressourcen (der Anfragetext ist leer):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
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

Auf Benachrichtigungen reagieren

Um den Erfolg anzugeben, 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 die Anfrage mit exponentiellem Backoff. Jeder andere zurückgegebene Statuscode wird als Nachrichtenfehler betrachtet.

Benachrichtigungsereignisse der Google Drive API

In diesem Abschnitt finden Sie Details zu den Benachrichtigungsnachrichten, die Sie erhalten können, wenn Sie Push-Benachrichtigungen mit der Google Drive API verwenden.

X-Goog-Resource-State Gilt für Wird gesendet, wenn
sync files, changes Ein Kanal wurde erstellt. Sie können Benachrichtigungen dafür erhalten.
add files Eine Ressource wurde erstellt oder freigegeben.
remove files Eine vorhandene Ressource wurde gelöscht oder die Freigabe wurde aufgehoben.
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 Änderungsprotokollelement wurde hinzugefügt.

Bei update-Ereignissen kann der HTTP-Header X-Goog-Changed angegeben werden. Dieser Header enthält eine durch Kommas getrennte Liste, in der die Arten der aufgetretenen Ä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 Element der Ressource 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 dem Attribut expiration wird gesteuert, wann die Benachrichtigungen automatisch beendet werden. Sie können Benachrichtigungen für einen bestimmten Kanal beenden, bevor er abläuft, indem Sie die stop Methode unter dem folgenden URI aufrufen:

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

Für diese Methode müssen Sie mindestens die Attribute des Kanals id und die resourceId 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. Insbesondere gilt:

  • Wenn der Kanal von einem normalen Nutzerkonto erstellt wurde, kann nur derselbe Nutzer vom selben Client (identifiziert durch die OAuth 2.0-Client-IDs aus den Authentifizierungstokens), der den Kanal erstellt hat, den Kanal beenden.
  • 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"
}