Ce document explique comment utiliser les notifications push qui informent vos en cas de modification d'une ressource.
Présentation
L'API Google Drive fournit des notifications push qui vous permettent de surveiller des changements de ressources. Vous pouvez utiliser cette fonctionnalité pour améliorer les performances votre application. Il vous permet d'éliminer les tâches de réseau et de calcul les coûts liés aux ressources de sondage pour déterminer si elles ont changé. Chaque fois qu'une ressource surveillée est modifiée, l'API Google Drive en informe application.
Pour utiliser les notifications push, vous devez:
Configurer votre URL de réception ou votre "webhook" destinataire de rappel.
Ce est un serveur HTTPS qui gère les messages de notification API déclenché lorsqu'une ressource est modifiée.
Configurez un (canal de notification) pour chaque point de terminaison de ressource que vous souhaitez montre.
Un canal spécifie les informations de routage pour les notifications messages. Lors de la configuration de la chaîne, vous devez identifier l'URL spécifique vous souhaitez recevoir des notifications. Chaque fois que la ressource d'un canal change, L'API Google Drive envoie un message de notification sous forme de
POST
à cette URL.
Actuellement, l'API Google Drive est compatible avec les notifications concernant les modifications apportées à
les méthodes files
et changes
.
Créer des canaux de notification
Pour demander des notifications push, vous devez configurer un canal de notification pour chaque ressource que vous souhaitez surveiller. Une fois vos canaux de notification définis l'API Google Drive informe votre application lorsqu'une ressource surveillée des modifications.
Envoyer des demandes de visionnage
Chaque ressource d'API Google Drive pouvant être visionnée est associée à
watch
à un URI au format suivant:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Pour configurer un canal de notification pour les messages concernant les modifications
ressource spécifique, envoyez une requête POST
au
watch
pour la ressource.
Chaque canal de notification est associé à la fois à un utilisateur particulier et
une ressource spécifique (ou un ensemble de ressources). Une requête watch
ne fonctionne que si l'utilisateur actuel
ou compte de service
est propriétaire de cette ressource ou est autorisé à y accéder.
Exemples
L'exemple de code suivant montre comment utiliser une ressource channels
pour commencer à surveiller les modifications apportées à une seule ressource files
à l'aide de la méthode files.watch
:
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. }
L'exemple de code suivant montre comment utiliser une ressource channels
pour commencer à surveiller toutes les changes
à l'aide de la méthode changes.watch
:
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. }
Propriétés obligatoires
Avec chaque requête watch
, vous devez fournir les champs suivants:
-
Une chaîne de propriété
id
qui l'identifie de manière unique un nouveau canal de notification dans votre projet. Nous vous recommandons d'utiliser un identifiant unique universel (UUID) ou tout autre code similaire chaîne unique. Ne doit pas dépasser 64 caractères.La valeur d'ID que vous avez définie est renvoyée dans le En-tête HTTP
X-Goog-Channel-Id
de chaque notification qui vous est envoyé pour cette chaîne. -
Une chaîne de propriété
type
définie sur la valeurweb_hook
-
Une chaîne de propriété
address
définie sur l'URL qui écoute et répond aux notifications pour ce canal de notification. C'est l'URL de rappel du webhook. Elle doit utiliser HTTPS.Notez que l'API Google Drive peut envoyer des notifications à cette adresse HTTPS uniquement si un certificat SSL valide est installé sur votre serveur Web. Les certificats non valides sont :
- les certificats auto-signés ;
- Certificats signés par une source non fiable
- Certificats révoqués
- Certificats dont le sujet ne correspond pas à la cible nom d'hôte.
Propriétés facultatives
Vous pouvez également spécifier ces champs facultatifs avec votre
Requête watch
:
-
Une propriété
token
qui spécifie une chaîne arbitraire à utiliser comme jeton de canal. Vous pouvez utiliser le canal de notification des jetons à des fins diverses. Par exemple, vous pouvez utiliser la méthode pour vérifier que chaque message entrant est destiné à un canal application créée) pour s'assurer que la notification n'est pas ou pour acheminer le message vers la bonne destination votre demande en fonction de l'objectif de ce canal. Longueur maximale: 256 caractères.Le jeton est inclus dans En-tête HTTP
X-Goog-Channel-Token
dans chaque notification que votre application reçoit pour ce canal.Si vous utilisez des jetons de canal de notification, nous vous recommandons de:
Utilisez un format d'encodage extensible, tel que les requêtes d'URL. paramètres. Exemple :
forwardTo=hr&createdBy=mobile
N'incluez pas de données sensibles telles que les jetons OAuth.
-
Une chaîne de propriété
expiration
définie sur Code temporel Unix (en millisecondes) de la date et de l'heure auxquelles vous souhaitez que l'API Google Drive arrêter d'envoyer des messages pour ce canal de notification.Si un canal a un délai d'expiration, celui-ci est inclus comme valeur de l'en-tête HTTP
X-Goog-Channel-Expiration
(dans un format lisible ) dans chaque message de notification que l'application reçoit pour ce canal.
Pour en savoir plus sur la requête, reportez-vous à la méthode watch
.
pour les méthodes files
et changes
dans la documentation de référence de l'API.
Regarder la réponse
Si la requête watch
crée une notification
canal, elle renvoie un code d'état HTTP 200 OK
.
Le corps du message de la réponse de surveillance fournit des informations sur le canal de notification que vous venez de créer, comme illustré dans l'exemple ci-dessous.
{ "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. }
En plus des propriétés que vous avez envoyées dans votre demande, le
les informations renvoyées incluent également les champs resourceId
et
resourceUri
pour identifier la ressource surveillée
canal de notification.
Vous pouvez transmettre les informations renvoyées à un autre canal de notification par exemple lorsque vous voulez arrêter de recevoir notifications.
Pour en savoir plus sur la réponse, consultez le watch
pour les méthodes files
et changes
dans la documentation de référence de l'API.
Synchroniser le message
Après avoir créé un canal de notification pour surveiller une ressource,
L'API Google Drive envoie un message sync
pour indiquer que
Les notifications ont démarré. Le protocole HTTP X-Goog-Resource-State
la valeur d'en-tête de ces messages est sync
. En raison du réseau
des problèmes de synchronisation, il est possible de recevoir le message sync
avant même de recevoir la réponse de la méthode watch
.
Vous pouvez ignorer la notification sync
, mais vous pouvez
également l'utiliser. Par exemple, si vous décidez de ne pas conserver
le canal, vous pouvez utiliser X-Goog-Channel-ID
et
X-Goog-Resource-ID
valeurs dans un appel de
ne plus recevoir de notifications. Vous pouvez également utiliser
Notification sync
pour effectuer une initialisation en vue de
les événements ultérieurs.
Format des messages sync
envoyés par l'API Google Drive
votre URL de réception est indiquée ci-dessous.
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
Les messages de synchronisation ont toujours un code HTTP X-Goog-Message-Number
la valeur d'en-tête de 1
. Chaque notification ultérieure pour cette chaîne
un numéro de message plus grand que le précédent, même si le message
ne se suivent pas.
Renouveler les canaux de notification
Un canal de notification peut avoir un délai d'expiration, avec une valeur
déterminé par votre demande ou par les limites internes de l'API Google Drive
ou par défaut (la valeur utilisée est la plus restrictive). La date d'expiration de la chaîne
l'heure, le cas échéant, est incluse sous la forme d'un code temporel Unix.
(en millisecondes) dans les informations renvoyées par la méthode watch
. De plus, le
la date et l'heure d'expiration sont indiquées (au format intelligible) dans chaque
de notification reçu par votre application pour ce canal dans le
En-tête HTTP X-Goog-Channel-Expiration
.
Il n'existe actuellement aucun moyen automatique de renouveler un canal de notification. Quand ?
d'un canal sur le point d'expirer, vous devez le remplacer par un nouveau en appelant
la méthode watch
. Comme toujours, vous devez utiliser une valeur unique pour
la propriété id
du nouveau canal. Notez qu'il est probable
soit un "chevauchement" période pendant laquelle les deux canaux de notification
même ressource sont actifs.
Recevoir des notifications
Chaque fois qu'une ressource surveillée est modifiée, votre application reçoit une
de notification décrivant la modification. L'API Google Drive envoie ces
les messages en tant que requêtes HTTPS POST
vers l'URL que vous avez spécifiée en tant que
Propriété address
pour cette notification
canal.
Interpréter le format du message de la notification
Tous les messages de notification incluent un ensemble d'en-têtes HTTP contenant
Préfixes X-Goog-
.
Certains types de notifications peuvent également inclure
corps du message.
En-têtes
Messages de notification publiés par l'API Google Drive et envoyés à votre réception L'URL comprend les en-têtes HTTP suivants:
En-tête | Description |
---|---|
Toujours présenter | |
|
UUID ou autre chaîne unique que vous avez fournie pour identifier cet élément canal de notification. |
|
Entier qui identifie ce message pour cette notification
canal. La valeur est toujours 1 pour les messages sync . Envoyer un message
nombres augmentent pour chaque message ultérieur sur le canal, mais ils sont
et non séquentielles. |
|
Valeur opaque identifiant la ressource surveillée. Cet ID est stable entre les versions de l'API. |
|
Nouvel état de la ressource ayant déclenché la notification.
Valeurs possibles:
sync , add , remove , update
trash , untrash ou change
pour en savoir plus.
|
|
Identifiant spécifique à la version de l'API pour la ressource surveillée. |
Parfois présent | |
|
Informations supplémentaires sur les modifications.
Valeurs possibles:
content ,
parents ,
children ou
permissions
pour en savoir plus.
Non fourni avec les messages sync . |
|
Date et heure d'expiration du canal de notification, exprimées au format dans un format lisible par l'humain. Présent uniquement si défini. |
|
Un jeton de canal de notification défini par votre application que vous pouvez utiliser pour vérifier la source de notification. Présent uniquement si définis. |
Les messages de notification pour files
et changes
sont vides.
Exemples
Message de notification de modification pour les ressources files
, qui n'inclut pas de corps de requête:
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
Message de notification de modification pour les ressources changes
, qui inclut un corps de requête:
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" }
Répondre à des notifications
Pour indiquer que l'opération a réussi, vous pouvez renvoyer l'un des codes d'état suivants:
200
, 201
, 202
, 204
ou
102
Si votre service utilise la bibliothèque cliente des API de Google
et renvoie 500
, 502
, 503
ou 504
, l'API Google Drive
de nouvelles tentatives avec un intervalle exponentiel entre les tentatives.
Tout autre code d'état renvoyé est considéré comme un échec de message.
Comprendre les événements de notification de l'API Google Drive
Cette section fournit des informations sur les messages de notification que vous pouvez recevoir en cas d'utilisation de notifications push avec l'API Google Drive.
Distribué lorsque | ||
---|---|---|
sync |
files , changes |
Une chaîne a bien été créée. Vous devriez commencer à recevoir des notifications à ce sujet. |
add |
files |
Une ressource a été créée ou partagée. |
|
files |
Une ressource existante a été supprimée ou n'est plus partagée. |
|
files |
Une ou plusieurs propriétés (métadonnées) d'une ressource ont été mises à jour. |
|
files |
Une ressource a été placée dans la corbeille. |
|
files |
Une ressource a été supprimée de la corbeille. |
|
changes |
Un ou plusieurs éléments du journal des modifications ont été ajoutés. |
Pour les événements update
, l'en-tête HTTP X-Goog-Changed
peut être fourni. Cet en-tête contient une liste d'éléments séparés par une virgule qui décrit les types de modifications qui se sont produites.
Type de modification | Indique |
---|---|
content |
Le contenu de la ressource a été mis à jour. |
properties |
Une ou plusieurs propriétés de ressources ont été mises à jour. |
parents |
Un ou plusieurs parents de ressources ont été ajoutés ou supprimés. |
children |
Une ou plusieurs ressources enfants ont été ajoutées ou supprimées. |
permissions |
Les autorisations liées aux ressources ont été mises à jour. |
Exemple avec l'en-tête X-Goog-Changed
:
X-Goog-Resource-State: update X-Goog-Changed: content, permissions
Arrêter les notifications
La propriété expiration
contrôle à quel moment les notifications s'arrêtent automatiquement. Vous pouvez
choisir de ne plus recevoir les notifications d'une chaîne en particulier
expire en appelant la méthode stop
l'URI suivant:
https://www.googleapis.com/drive/v3/channels/stop
Pour utiliser cette méthode, vous devez indiquer au moins
id
et resourceId
, comme indiqué dans les
dans l'exemple ci-dessous. Notez que si l'API Google Drive comporte plusieurs types de
ressources comportant des méthodes watch
, il n'y en a qu'une
stop
.
Seuls les utilisateurs disposant des autorisations appropriées peuvent arrêter une chaîne. En particulier :
- Si la chaîne a été créée par un compte utilisateur standard, seule la même du même client (identifié par les ID client OAuth 2.0 du jetons d'authentification) qui l'a créée peuvent l'arrêter.
- Si le canal a été créé par un compte de service, tout utilisateur du même le client peut arrêter la chaîne.
L'exemple de code suivant montre comment arrêter de recevoir des notifications:
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" }