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 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 die folgenden Felder angegeben werden:
-
Ein
id
-Attributstring, 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 istweb_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 und muss HTTPS verwenden.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 findest du 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 die sync
-Nachricht
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 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 an, 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
keine fortlaufende Nummerierung.
Benachrichtigungskanäle verlängern
Ein Benachrichtigungskanal kann eine Ablaufzeit haben, mit einem Wert
der entweder durch Ihre Anfrage oder durch interne Beschränkungen der Google Drive API bestimmt wird
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
Immer 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 einblenden | |
|
UUID oder ein anderer eindeutiger String, den Sie zur Identifizierung angegeben haben Benachrichtigungskanal. |
|
Ganzzahl, die diese Nachricht für diese Benachrichtigung identifiziert
Kanal. Der Wert für sync -Nachrichten ist immer 1 . Nachricht
mit jeder nachfolgenden Nachricht im Kanal erhöht,
nicht sequenziell. |
|
Ein intransparenter Wert, der die überwachte Ressource identifiziert. Diese ID lautet in allen API-Versionen stabil sein. |
|
Der neue Ressourcenstatus, der die Benachrichtigung ausgelöst hat.
Mögliche Werte:
sync , add , remove , update ,
trash , untrash oder change
.
|
|
Eine API-versionsspezifische Kennung für die überwachte Ressource. |
Manchmal anwesend | |
|
Weitere Details zu den Änderungen.
Mögliche Werte:
content ,
parents ,
children oder
permissions
.
Nicht mit sync -Nachrichten angegeben. |
|
Datum und Uhrzeit des Ablaufs des Benachrichtigungskanals, angegeben in menschenlesbares Format. Nur vorhanden, wenn definiert. |
|
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 Google Drive API-Benachrichtigungsereignissen
Dieser Abschnitt enthält Details zu den Benachrichtigungen, die Sie die Sie erhalten, wenn Sie Push-Benachrichtigungen mit der Google Drive API verwenden.
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. |
|
files |
Eine vorhandene Ressource wurde gelöscht oder ihre Freigabe wurde zurückgenommen. |
|
files |
Mindestens ein Attribut (Metadaten) einer Ressource wurde aktualisiert. |
|
files |
Eine Ressource wurde in den Papierkorb verschoben. |
|
files |
Eine Ressource wurde aus dem Papierkorb entfernt. |
|
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 Methode stop
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 Kanal 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" }