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 überwachen können. Mit dieser Funktion können Sie die Leistung Ihrer Anwendung verbessern. So können Sie die zusätzlichen Netzwerk- und Rechenkosten vermeiden, die beim Abrufen von Ressourcen anfallen, um festzustellen, ob sie sich geändert haben. Wenn sich eine beobachtete Ressource ändert, benachrichtigt die Google Drive API Ihre Anwendung.

Wenn Sie Push-Benachrichtigungen verwenden möchten, müssen Sie zwei Dinge tun:

  • Richten Sie Ihre Empfangs-URL oder den Callback-Empfänger für Webhooks 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 Channel gibt Routinginformationen für Benachrichtigungsnachrichten an. Im Rahmen der Einrichtung des Channels müssen Sie die spezifische URL angeben, an die Sie Benachrichtigungen erhalten möchten. 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 für Ä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 Ihre Benachrichtigungskanäle eingerichtet sind, werden Sie über die Google Drive API benachrichtigt, wenn sich eine überwachte Ressource ändert.

Smartwatch-Anfragen stellen

Jeder beobachtbaren Google Drive API-Ressource ist eine watch-Methode unter einem URI des folgenden Formats 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 Gruppe von Ressourcen) zugeordnet. Eine watch-Anfrage ist nur erfolgreich, wenn der aktuelle Nutzer oder das Dienstkonto Eigentümer dieser Ressource ist oder die Berechtigung hat, darauf zuzugreifen.

Beispiele

Das folgende Codebeispiel zeigt, wie Sie mit einer channels-Ressource mit der Methode files.watch Änderungen an einer einzelnen files-Ressource 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", // 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 mit einer channels-Ressource mit der Methode changes.watch alle changes 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 die folgenden Felder angeben:

  • Ein id-Attributstring, der diesen neuen Benachrichtigungskanal in Ihrem Projekt eindeutig identifiziert. Wir empfehlen, eine 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 Benachrichtigungsnachricht, die Sie für diesen Kanal erhalten, zurückgegeben.

  • 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 empfängt und darauf reagiert. Dies ist die Callback-URL Ihres Webhooks. 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 Subjekt nicht mit dem Zielhostnamen übereinstimmt.

Optionale Attribute

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

  • Eine token-Eigenschaft, die einen beliebigen Stringwert angibt, der als Channel-Token verwendet werden soll. Sie können Benachrichtigungschannel-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, der von Ihrer Anwendung erstellt wurde. So lässt sich sicherstellen, dass die Benachrichtigung nicht gefälscht wird. Außerdem können Sie die Nachricht basierend auf dem Zweck des 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 Benachrichtigungsnachricht enthalten, die Ihre Anwendung für diesen Kanal empfängt.

    Wenn Sie Benachrichtigungschannel-Tokens verwenden, empfehlen wir Ihnen Folgendes:

    • Verwenden Sie ein erweiterbares Codierungsformat wie URL-Suchparameter. 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 der die Google Drive API keine Nachrichten mehr für diesen Benachrichtigungskanal senden soll.

    Wenn ein Channel eine Ablaufzeit hat, ist sie als Wert des HTTP-Headers X-Goog-Channel-Expiration (in einem für Menschen lesbaren Format) in jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Channel empfängt.

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

Antwort auf der Smartwatch ansehen

Wenn durch die watch-Anfrage erfolgreich ein Benachrichtigungschannel erstellt wird, wird der HTTP-Statuscode 200 OK zurückgegeben.

Der Nachrichtentext der Smartwatch-Antwort enthält Informationen zum Benachrichtigungskanal, den Sie gerade erstellt haben, wie im Beispiel unten 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 Ihrer Anfrage gesendet haben, enthalten die zurückgegebenen Informationen auch resourceId und resourceUri, um die Ressource zu identifizieren, die auf diesem Benachrichtigungskanal beobachtet wird.

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.

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 X-Goog-Resource-State-HTTP-Headerwert für diese Nachrichten ist sync. Aufgrund von Netzwerk-Timing-Problemen ist es möglich, dass Sie die Meldung sync erhalten, bevor Sie die Antwort der Methode watch erhalten.

Sie können die Benachrichtigung sync ignorieren, aber 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 zum Beenden des Empfangs von Benachrichtigungen verwenden. 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

Synchronisierungsnachrichten haben immer den X-Goog-Message-Number-HTTP-Headerwert 1. Jede nachfolgende Benachrichtigung für diesen Channel hat eine Nachrichtennummer, die größer als die vorherige ist. Die Nachrichtennummern sind jedoch nicht fortlaufend.

Benachrichtigungskanäle erneuern

Ein Benachrichtigungschannel kann eine Ablaufzeit haben, deren Wert entweder durch Ihre Anfrage oder durch interne Grenzwerte oder Standardeinstellungen der Google Drive API bestimmt wird (der restriktivere Wert wird verwendet). Die Ablaufzeit des Channels, sofern vorhanden, ist als Unix-Zeitstempel (in Millisekunden) in den von der Methode watch zurückgegebenen Informationen enthalten. Außerdem sind das Ablaufdatum und die Ablaufzeit (in einem für Menschen lesbaren Format) in jeder Benachrichtigung enthalten, die Ihre Anwendung für diesen Channel im HTTP-Header X-Goog-Channel-Expiration empfängt.

Derzeit gibt es keine automatische Möglichkeit, einen Benachrichtigungskanal zu verlängern. Wenn ein Channel bald abläuft, müssen Sie ihn durch einen neuen ersetzen. Rufen Sie dazu die watch-Methode auf. Wie immer müssen Sie für die Property id des neuen Channels 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 Benachrichtigung mit einer Beschreibung der Änderung. Die Google Drive API sendet diese Nachrichten als HTTPS-POST-Anfragen an die URL, die Sie als address-Property für diesen Benachrichtigungschannel angegeben haben.

Format der Benachrichtigungsnachricht interpretieren

Alle Benachrichtigungen enthalten eine Reihe von HTTP-Headern mit dem Präfix X-Goog-. Einige Benachrichtigungstypen 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 Channel 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 Kennung für die überwachte Ressource.
Manchmal vorhanden
X-Goog-Changed Zusätzliche Details zu den Änderungen. Mögliche Werte: content, parents, children oder permissions . Nicht in sync-Nachrichten enthalten.
X-Goog-Channel-Expiration Datum und Uhrzeit des Ablaufs des Benachrichtigungschannels in einem für Menschen lesbaren Format. Nur vorhanden, wenn definiert.
X-Goog-Channel-Token Das von Ihrer Anwendung festgelegte Benachrichtigungschannel-Token, mit dem Sie die Benachrichtigungsquelle überprüfen können. Nur vorhanden, wenn definiert.

Benachrichtigungen für files und changes sind leer.

Beispiele

Benachrichtigungstext für Änderungen an files-Ressourcen, der 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

Benachrichtigung über Änderungen 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

Um den Erfolg anzugeben, können Sie einen der folgenden Statuscodes zurückgeben: 200, 201, 202, 204 oder 102.

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

Google Drive API-Benachrichtigungsereignisse

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 geliefert, wenn
sync files, changes Ein Kanal wurde erstellt. Sie sollten dann Benachrichtigungen dazu erhalten.
add files Eine Ressource wurde erstellt oder freigegeben.
remove files Eine vorhandene Ressource wurde gelöscht oder die Freigabe wurde aufgehoben.
update files Eine oder mehrere Eigenschaften (Metadaten) einer Ressource wurden aktualisiert.
trash files Eine Ressource wurde in den Papierkorb verschoben.
untrash files Eine Ressource wurde aus dem Papierkorb entfernt.
change changes Es wurden ein oder mehrere Changelog-Einträge hinzugefügt.

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 Inhalt der Ressource wurde aktualisiert.
properties Mindestens eine Ressourcen-Property wurde aktualisiert.
parents Ein oder mehrere übergeordnete Elemente von Ressourcen wurden hinzugefügt oder entfernt.
children Mindestens ein untergeordnetes Element einer 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 der Eigenschaft expiration wird festgelegt, wann die Benachrichtigungen automatisch beendet werden. Sie können Benachrichtigungen für einen bestimmten Kanal deaktivieren, 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 Sie mindestens die Attribute id und resourceId des Kanals angeben, wie im Beispiel unten 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 Channel beenden. Wichtig ist insbesondere:

  • Wenn der Kanal über ein reguläres Nutzerkonto erstellt wurde, kann er nur von demselben Nutzer über denselben Client (anhand der OAuth 2.0-Client-IDs aus den Autorisierungstokens) beendet werden, der den Kanal erstellt hat.
  • Wenn der Kanal von einem Dienstkonto erstellt wurde, kann jeder Nutzer desselben Clients 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"
}