Benachrichtigungen bei Ressourcenänderungen

In diesem Dokument wird beschrieben, wie Sie Push-Benachrichtigungen verwenden, um Ihre wenn sich eine Ressource ändert.

Übersicht

Die Google Drive API bietet Push-Benachrichtigungen, mit denen Sie Änderungen an den Ressourcen. Mit dieser Funktion können Sie die Leistung Ihrer Ihre Anwendung. Sie eliminieren zusätzliche Netzwerk- und Rechenleistung die Kosten für das Abfragen von Ressourcen, um festzustellen, ob sie sich geändert haben. Wenn sich eine beobachtete Ressource ändert, benachrichtigt die Google Drive API Ihr .

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

  • Empfangs-URL oder Webhook einrichten des Rückrufempfängers.

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

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

    Ein Kanal gibt Routinginformationen für Benachrichtigungen an. Nachrichten. Bei der Einrichtung des Channels müssen Sie die URL angeben, unter der Sie Benachrichtigungen erhalten möchten. Wenn sich die Ressourcen eines Kanals ändern, Die Google Drive API sendet eine Benachrichtigung als POST an diese URL senden.

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

Benachrichtigungskanäle erstellen

Um Push-Benachrichtigungen anzufordern, musst du einen Benachrichtigungskanal einrichten für jede Ressource, die Sie überwachen möchten. Nach dem Festlegen der Benachrichtigungskanäle informiert die Google Drive API Ihre Anwendung, sobald eine beobachtete Ressource Änderungen.

Wiedergabeanfragen stellen

Jeder Watchable Google Drive API-Ressource ist ein watch bei einem URI der folgenden Form:

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

So richten Sie einen Benachrichtigungskanal für Benachrichtigungen über Änderungen an einer bestimmten Ressource, senden Sie eine POST-Anfrage an den Die Methode watch für die Ressource.

Jeder Benachrichtigungskanal ist sowohl einem bestimmten Nutzer als auch eine bestimmte Ressource (oder eine Gruppe von Ressourcen) Eine watch-Anfrage ist nur erfolgreich, wenn der aktuelle Nutzer oder Dienstkonto besitzt oder hat die Berechtigung, auf diese Ressource zuzugreifen.

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-Property-String, der dieses Objekt eindeutig identifiziert in Ihrem Projekt zu erstellen. Wir empfehlen die Verwendung von eine universell eindeutige Kennung (UUID) oder Ähnliches eindeutigen String hinzu. Maximale Länge: 64 Zeichen.

    Der von Ihnen festgelegte ID-Wert wird im X-Goog-Channel-Id-HTTP-Header jeder Benachrichtigung die du für diesen Kanal erhältst.

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

  • Einen address-Property-String, der auf die URL festgelegt ist, die überwacht und reagiert auf Benachrichtigungen für diesen Benachrichtigungskanal. Dies ist Ihre Webhook-Callback-URL angegeben. Außerdem muss HTTPS verwendet werden.

    Beachten Sie, dass die Google Drive API Benachrichtigungen an diese HTTPS-Adresse nur verwenden, wenn ein gültiges SSL-Zertifikat installiert ist auf Ihrem Webserver. Folgende Zertifikate sind nicht gültig:

    • selbst signierte Zertifikate.
    • von einer nicht vertrauenswürdigen Quelle signierte Zertifikate
    • gesperrte Zertifikate
    • Zertifikate, deren Thema nicht mit dem Ziel übereinstimmt Hostname.

Optionale Attribute

Sie können diese optionalen Felder auch mit Ihrem watch-Anfrage:

  • Ein token-Attribut, das einen beliebigen String angibt. -Wert zur Verwendung als Kanaltoken. Du kannst den Benachrichtigungskanal verwenden für verschiedene Zwecke. Sie können beispielsweise die Methode um zu überprüfen, ob alle eingehenden Nachrichten zu einem Kanal gehören, Anwendung erstellt, um sicherzustellen, dass die Benachrichtigung nicht um Spoofing zu verhindern, oder die Nachricht an das richtige Ziel innerhalb entsprechend dem Zweck dieses Kanals anpassen. Maximale Länge: 256 Zeichen.

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

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

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

    • Verwenden Sie keine sensiblen Daten wie OAuth-Tokens.

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

    Wenn ein Channel eine Ablaufzeit hat, wird dieser als Wert des HTTP-Headers X-Goog-Channel-Expiration (für Menschen lesbar) Format) in jeder Benachrichtigung, die Ihr Anwendung für diesen Kanal erhält.

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

Antwort ansehen

Wenn die watch-Anfrage erfolgreich eine Benachrichtigung erstellt wird der HTTP-Statuscode 200 OK zurückgegeben.

Der Nachrichtentext der Überwachungsantwort enthält Informationen über die den Sie gerade erstellt haben, 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 Eigenschaften, die Sie im Rahmen Ihrer Anfrage gesendet haben, enthält der die zurückgegebenen Informationen auch die resourceId und resourceUri, um die dafür zu überwachende Ressource zu identifizieren Benachrichtigungskanal.

Sie können die zurückgegebenen Informationen an einen anderen Benachrichtigungskanal weitergeben. z. B. wenn Sie den Erhalt von E-Mails nicht mehr Benachrichtigungen.

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

Nachricht synchronisieren

Nachdem Sie einen Benachrichtigungskanal zum Überwachen einer Ressource erstellt haben, zeigt der Die Google Drive API sendet eine sync-Nachricht mit dem Hinweis, dass Benachrichtigungen werden gestartet. Das X-Goog-Resource-State-HTTP Der Headerwert für diese Nachrichten ist sync. Aufgrund des Netzwerks Probleme mit dem Zeitplan haben, ist es möglich, dass du die sync-Nachricht erhältst. noch bevor Sie die Antwort der Methode watch erhalten.

Du kannst die sync-Benachrichtigung ignorieren, aber du kannst verwenden. Wenn Sie z. B. entscheiden, Ihre des Kanals, können Sie die X-Goog-Channel-ID und X-Goog-Resource-ID-Werte in einem Aufruf von keine Benachrichtigungen mehr erhalten. Sie können auch die sync-Benachrichtigung, um eine Initialisierung durchzuführen, um sich auf späteren Terminen.

Das Format der sync-Nachrichten, an die die Google Drive API sendet Ihre Empfangs-URL 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 das HTTP-Statuscode X-Goog-Message-Number Headerwert von 1. Jede weitere Benachrichtigung für diesen Kanal hat die größer als die vorherige ist, auch wenn die Meldung nicht fortlaufend sind.

Benachrichtigungskanäle verlängern

Ein Benachrichtigungskanal kann eine Ablaufzeit haben, mit einem Wert die entweder durch Ihre Anfrage oder durch interne Beschränkungen der Google Drive API bestimmt werden. oder Standardwerte (der restriktivere Wert wird verwendet). Ablauf des Kanals (sofern vorhanden) als Unix-Zeitstempel (in Millisekunden) in den Informationen, die von der Methode watch zurückgegeben werden. Darüber hinaus enthält der Ablaufdatum und -uhrzeit werden (in visuell lesbarem Format) in jedem Benachrichtigung, die Ihre Anwendung für diesen Kanal in der HTTP-Header „X-Goog-Channel-Expiration“

Derzeit gibt es keine automatische Verlängerung eines Benachrichtigungskanals. Wann? ein Kanal bald abläuft, musst du ihn durch einen neuen ersetzen. Rufe dazu folgenden Link auf: die Methode watch. Wie immer müssen Sie für jedes Element einen eindeutigen Wert verwenden, Das Attribut id des neuen Channels Es gibt wahrscheinlich als „Überlappung“ Zeitraum, in dem die beiden Benachrichtigungskanäle für den Ressource aktiv sind.

Benachrichtigungen erhalten

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

Nachrichtenformat für Benachrichtigungen interpretieren

Alle Benachrichtigungen enthalten eine Reihe von HTTP-Headern mit X-Goog- Präfixe. Einige Benachrichtigungstypen können auch ein Nachrichtentext.

Header

Benachrichtigungen, die von der Google Drive API an Ihren Empfänger gesendet wurden Die URL enthält die folgenden HTTP-Header:

Header Beschreibung
Immer anzeigen
X-Goog-Channel-ID UUID oder ein anderer eindeutiger String, den Sie zur Identifizierung angegeben haben Benachrichtigungskanal.
X-Goog-Message-Number Ganzzahl, die diese Nachricht für diese Benachrichtigung identifiziert Kanal. Der Wert für sync-Nachrichten ist immer 1. Nachricht mit jeder weiteren Nachricht im Kanal erhöht, nicht sequenziell.
X-Goog-Resource-ID Ein intransparenter Wert, der die beobachtete Ressource identifiziert. Diese ID lautet in allen API-Versionen stabil sein.
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, angegeben in menschenlesbares Format. Nur vorhanden, wenn definiert.
X-Goog-Channel-Token Token des Benachrichtigungskanals, 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

Ä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 Ihr Dienst die API-Clientbibliothek von Google verwendet und gibt 500,502, 503 oder 504, die Google Drive API, zurück. Wiederholungsversuche 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 die Sie erhalten, 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 Du kannst festlegen, dass du für einen bestimmten Kanal keine Benachrichtigungen mehr erhalten möchtest, bevor dieser durch Aufrufen der stop-Methode unter den folgenden URI:

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

Bei dieser Methode müssen Sie mindestens den Typ id- und resourceId-Eigenschaften, wie in den Beispiel unten. Wenn die Google Drive API über verschiedene Ressourcen mit watch-Methoden, es gibt nur eine stop-Methode.

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

  • Wurde der Kanal über ein reguläres Nutzerkonto erstellt, werden nur dieselben Nutzer aus dem gleichen Client (identifiziert durch OAuth 2.0-Client-IDs aus der Authentifizierungstokens), die den Kanal erstellt haben, können ihn beenden.
  • Wenn der Channel von einem Dienstkonto erstellt wurde, kann jeder Nutzer desselben kann der Client 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"
}