Notifications en cas de modifications des ressources

Ce document explique comment utiliser des notifications push qui informent votre application en cas de modification d'une ressource.

Présentation

L'API Google Drive fournit des notifications push qui vous permettent de surveiller les modifications apportées aux ressources. Vous pouvez utiliser cette fonctionnalité pour améliorer les performances de votre application. Il vous permet d'éliminer les coûts de réseau et de calcul supplémentaires liés aux ressources d'interrogation afin de déterminer si elles ont changé. Chaque fois qu'une ressource surveillée est modifiée, l'API Google Drive en informe votre application.

Pour utiliser les notifications push, vous devez:

  • Configurez votre récepteur de rappel "webhook" ou URL de réception.

    Il s'agit d'un serveur HTTPS qui gère les messages de notification d'API déclenchés lorsqu'une ressource est modifiée.

  • Configurez un canal de notification pour chaque point de terminaison de ressource que vous souhaitez surveiller.

    Un canal spécifie des informations de routage pour les messages de notification. Lors de la configuration du canal, vous devez identifier l'URL spécifique à laquelle vous souhaitez recevoir des notifications. Chaque fois que la ressource d'un canal est modifiée, l'API Google Drive envoie un message de notification sous la forme d'une requête POST à cette URL.

Actuellement, l'API Google Drive est compatible avec les notifications concernant les modifications apportées aux 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 configurés, l'API Google Drive informe votre application en cas de modification d'une ressource surveillée.

Envoyer des demandes de visionnage

Chaque ressource d'API Google Drive pouvant être surveillée est associée à une méthode 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 apportées à une ressource particulière, envoyez une requête POST à la méthode watch de la ressource.

Chaque canal de notification est associé à la fois à un utilisateur particulier et à une ressource (ou un ensemble de ressources) particulière. Une requête watch n'aboutira que si l'utilisateur ou le compte de service actuel possède cette ressource ou n'est pas 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:

  • Chaîne de propriété id qui identifie de manière unique ce nouveau canal de notification au sein de votre projet. Nous vous recommandons d'utiliser un identifiant unique universel (UUID) ou toute chaîne unique similaire. Ne doit pas dépasser 64 caractères.

    La valeur d'ID que vous définissez est renvoyée dans l'en-tête HTTP X-Goog-Channel-Id de chaque message de notification que vous recevez pour ce canal.

  • Une chaîne de propriété type définie sur la valeur web_hook.

  • Chaîne de propriété address définie sur l'URL qui écoute les notifications pour ce canal de notification et y répond. Il s'agit de l'URL de rappel du webhook. Elle doit utiliser HTTPS.

    Notez que l'API Google Drive ne peut envoyer des notifications à cette adresse HTTPS que 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 l'objet ne correspond pas au nom d'hôte cible.

Propriétés facultatives

Vous pouvez également spécifier les champs facultatifs suivants avec votre requête watch:

  • Propriété token qui spécifie une valeur de chaîne arbitraire à utiliser comme jeton de canal. Vous pouvez utiliser les jetons de canal de notification à des fins diverses. Par exemple, vous pouvez utiliser le jeton pour vérifier que chaque message entrant est destiné à un canal créé par votre application (pour vous assurer que la notification n'est pas falsifiée) ou pour acheminer le message vers la destination appropriée dans votre application en fonction de l'objectif de ce canal. Longueur maximale : 256 caractères.

    Le jeton est inclus dans l'en-tête HTTP X-Goog-Channel-Token de chaque message de 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 des paramètres de requête d'URL. 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 un code temporel Unix (en millisecondes) de la date et de l'heure auxquelles vous souhaitez que l'API Google Drive cesse d'envoyer des messages pour ce canal de notification.

    Si un canal a un délai d'expiration, celui-ci est inclus en tant que valeur de l'en-tête HTTP X-Goog-Channel-Expiration (au format lisible) dans chaque message de notification que votre 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 correctement un canal de notification, 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 requête, les informations renvoyées incluent également resourceId et resourceUri pour identifier la ressource surveillée sur ce canal de notification.

Vous pouvez transmettre les informations renvoyées à d'autres opérations de canal de notification, par exemple lorsque vous souhaitez arrêter de recevoir des notifications.

Pour en savoir plus sur la réponse, reportez-vous à la méthode 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 sont lancées. La valeur de l'en-tête HTTP X-Goog-Resource-State pour ces messages est sync. En raison de problèmes de temps réseau, 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 les valeurs X-Goog-Channel-ID et X-Goog-Resource-ID dans un appel pour arrêter de recevoir des notifications. Vous pouvez également utiliser la notification sync pour effectuer une initialisation afin de vous préparer aux événements ultérieurs.

Le format des messages sync que l'API Google Drive envoie à votre URL de réception est indiqué 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

La valeur d'en-tête HTTP X-Goog-Message-Number des messages de synchronisation est toujours 1. Chaque notification ultérieure pour ce canal comporte un numéro de message supérieur à la précédente, bien que les numéros de message ne soient pas séquentiels.

Renouveler les canaux de notification

Un canal de notification peut avoir un délai d'expiration, dont la valeur est déterminée par votre requête, ou par les limites internes ou par défaut de l'API Google Drive (la valeur la plus restrictive est utilisée). Le cas échéant, le délai d'expiration du canal est inclus sous forme d'horodatage Unix (en millisecondes) dans les informations renvoyées par la méthode watch. De plus, la date et l'heure d'expiration sont incluses (au format lisible) dans chaque message de notification que votre application reçoit pour ce canal, dans l'en-tête HTTP X-Goog-Channel-Expiration.

Il n'existe actuellement aucun moyen automatique de renouveler un canal de notification. Lorsqu'un canal est 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 peut y avoir une période de "chevauchement" lorsque les deux canaux de notification pour la même ressource sont actifs.

Recevoir les notifications

Chaque fois qu'une ressource surveillée est modifiée, votre application reçoit un message de notification décrivant la modification. L'API Google Drive envoie ces messages sous forme de requêtes HTTPS POST à l'URL que vous avez spécifiée en tant que propriété address pour ce canal de notification.

Interpréter le format du message de la notification

Tous les messages de notification incluent un ensemble d'en-têtes HTTP comportant les préfixes X-Goog-. Certains types de notifications peuvent également inclure un corps de message.

En-têtes

Les messages de notification publiés par l'API Google Drive sur votre URL de réception incluent les en-têtes HTTP suivants:

En-tête Description
Toujours présenter
X-Goog-Channel-ID UUID ou autre chaîne unique que vous avez fournie pour identifier ce canal de notification.
X-Goog-Message-Number Entier qui identifie ce message pour ce canal de notification. La valeur est toujours 1 pour les messages sync. Les numéros de message augmentent pour chaque message suivant sur le canal, mais ils ne sont pas séquentiels.
X-Goog-Resource-ID Valeur opaque identifiant la ressource surveillée. Cet ID est stable quelle que soit la version de l'API.
X-Goog-Resource-State Nouvel état de la ressource ayant déclenché la notification. Valeurs possibles : sync, add, remove, update, trash, untrash ou change.
X-Goog-Resource-URI Identifiant spécifique à la version de l'API pour la ressource surveillée.
Parfois présent
X-Goog-Changed Informations supplémentaires sur les modifications. Valeurs possibles : content, parents, children ou permissions. Non fourni avec les messages sync.
X-Goog-Channel-Expiration Date et heure d'expiration du canal de notification, exprimées dans un format lisible. Présent uniquement si défini.
X-Goog-Channel-Token Jeton de canal de notification défini par votre application, et que vous pouvez utiliser pour vérifier la source de notification. Présent uniquement si défini.

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 réessaie 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 détails sur les messages de notification que vous pouvez recevoir lorsque vous utilisez les notifications push avec l'API Google Drive.

X-Goog-Resource-State Applicable à 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.
remove files Une ressource existante a été supprimée ou n'est plus partagée.
update files Une ou plusieurs propriétés (métadonnées) d'une ressource ont été mises à jour.
trash files Une ressource a été placée dans la corbeille.
untrash files Une ressource a été supprimée de la corbeille.
change 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.

Change type 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 de notifications pour un canal particulier avant son expiration en appelant la méthode stop à l'URI suivant:

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

Cette méthode nécessite que vous fournissiez au moins les propriétés id et resourceId du canal, comme illustré dans l'exemple ci-dessous. Notez que si l'API Google Drive comporte plusieurs types de ressources ayant des méthodes watch, il n'existe qu'une seule méthode stop.

Seuls les utilisateurs disposant des autorisations appropriées peuvent arrêter une chaîne. En particulier :

  • Si le canal a été créé par un compte utilisateur standard, seul l'utilisateur du même client (identifié par les ID client OAuth 2.0 des jetons d'authentification) qui a créé le canal peut arrêter le canal.
  • Si le canal a été créé par un compte de service, n'importe quel utilisateur du même client peut l'arrêter.

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