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 verfolgen 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-Benachrichtigungen verarbeitet, die ausgelöst werden, wenn sich eine Ressource ändert.

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

  Ein Kanal gibt Routinginformationen für Benachrichtigungen Nachrichten an. Im Rahmen der Kanaleinrichtung müssen Sie die URL angeben, an die Sie Benachrichtigungen erhalten möchten. Wenn sich die Ressource eines Kanals ändert, sendet die Google Drive API eine Benachrichtigung als POST Anfrage an diese URL.

Hinweis: Der Begriff „Kanal“ bezieht sich in diesem Dokument speziell auf einen Benachrichtigungskanal und nicht auf andere Arten von Kanälen, die in dieser API oder diesem Dienst verwendet werden. Für dieselbe Ressource können mehrere Benachrichtigungskanäle gleichzeitig aktiv sein.

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 überwachen möchten, einen Benachrichtigungskanal einrichten. Nachdem Sie Ihre Benachrichtigungskanäle eingerichtet haben , informiert die Google Drive API Ihre Anwendung, wenn sich eine überwachte Ressource ändert.

Überwachungsanfragen stellen

Jeder überwachbaren 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 Überwachung von Änderungen an einer einzelnen files-Ressource mit der Methode files.watch starten:

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 Überwachung aller changes mit der Methode changes.watch starten:

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 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 Ihre watch Anfrage aufnehmen:

• 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 prüfen, ob jede eingehende Nachricht für einen Kanal bestimmt ist, den Ihre Anwendung erstellt hat. So lässt sich 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 im X-Goog-Channel-Token HTTP-Header jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Kanal erhält.

  Wenn Sie Benachrichtigungskanal-Tokens verwenden, empfehlen wir Folgendes:

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

  • Nehmen Sie keine vertraulichen Daten wie OAuth-Tokens auf.

  Hinweis: Wenn Sie hochsensible Daten senden müssen, verschlüsseln Sie sie, bevor Sie sie dem Token hinzufügen.

• 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, ist sie als Wert des X-Goog-Channel-Expiration HTTP-Headers (in einem für Menschen lesbaren Format) in jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Kanal erhält.

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

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

Antwort auf die Überwachungsanfrage

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

Der Inhalt der Nachricht der Antwort auf die Überwachungsanfrage enthält Informationen zum gerade erstellten Benachrichtigungskanal, wie im folgenden Beispiel zu sehen ist.

{
  "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 überwachten Ressource.
• resourceUri: Die versionsspezifische ID der überwachten 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 resourceId und resourceUri um die Ressource zu identifizieren, die auf diesem Benachrichtigungskanal überwacht wird.

Hinweis: Das Attribut resourceId ist eine stabile, versionsunabhängige ID für die Ressource. Das resourceUri Attribut ist der kanonische URI der überwachten Ressource im Kontext der aktuellen API-Version. Es ist also versionsspezifisch.

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 Überwachen einer Ressource erstellt haben, sendet die Google Drive API eine sync Nachricht, um anzugeben, dass Benachrichtigungen gesendet werden. Der Wert des HTTP Headers für diese Nachrichten ist sync.X-Goog-Resource-State 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 den Empfang von Benachrichtigungen zu beenden. 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 von 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, 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 Unix-Zeitstempel (in Millisekunden) in den von der watch Methode zurückgegebenen Informationen enthalten. Außerdem sind das Ablaufdatum und die ‑zeit (in einem für Menschen lesbaren Format) in jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Kanal erhält. Sie finden sie im X-Goog-Channel-Expiration HTTP-Header.

Derzeit gibt es keine automatische Möglichkeit, einen Benachrichtigungskanal zu verlängern. 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. Beachten Sie, dass es wahrscheinlich einen Zeitraum geben wird, in dem die beiden Benachrichtigungskanäle für dieselbe Ressource aktiv sind.

Benachrichtigungen erhalten

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 das address Attribut für diesen Benachrichtigungs Kanal angegeben haben.

Hinweis: HTTPS-Anfragen zur Benachrichtigungsübermittlung geben einen User-Agent von APIs-Google an und berücksichtigen robots.txt Anweisungen, wie unter User-Agent von APIs-Google beschrieben.

Format der Benachrichtigung interpretieren

Alle Benachrichtigungen enthalten eine Reihe von HTTP-Headern mit dem X-Goog- Präfix. 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 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. Nachrichtennummern werden für jede nachfolgende Nachricht im Kanal erhöht, sind aber nicht fortlaufend.
X-Goog-Resource-ID	Ein intransparenter Wert, der die überwachte 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 überwachte 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.

Benachrichtigungen für files und changes sind leer.

Beispiele

Benachrichtigung für Änderungen an files-Ressourcen, die keinen Anfragetext enthält:

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: 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

Benachrichtigung für Änderungen an changes-Ressourcen, die einen Anfragetext enthält:

POST https://mydomain.com/notifications
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

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 Benachrichtigungen, 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.

Im Laufe der Zeit werden dieser Liste möglicherweise weitere Ereignisse zum Ressourcenstatus hinzugefügt. Möglicherweise erhalten Sie unerwartete Ereignistypen. Ihre Ereignishandler sollten diese ignorieren.

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 Berechtigungen für die Ressource wurden aktualisiert.

Beispiel mit X-Goog-Changed-Header:

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

Benachrichtigungen deaktivieren

Das Attribut expiration steuert, wann die Benachrichtigungen automatisch beendet werden. Sie können den Empfang von 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 zu sehen ist. 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 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 vom selben Client den Kanal beenden.

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

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