Cette page a été traduite par l'API Cloud Translation.

Notifications en cas de modifications des ressources

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 valeur web_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 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.
Remarque:Si vous devez envoyer des messages très sensibles données, assurez-vous qu'elles sont chiffrées avant de les ajouter à un jeton d'accès.
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.

Remarque: Pour l'API Google Drive, le délai d'expiration maximal est de 86 400 secondes (1 jour) après l'heure actuelle pour la ressource files et 604 800 secondes (une semaine) pour changes. Si vous ne définissez pas expiration dans votre requête, le délai d'expiration La valeur par défaut est 3 600 secondes après l'heure actuelle.

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.

Remarque:La propriété resourceId est une stable et indépendant de la version de la ressource. La La propriété resourceUri correspond à l'URI canonique de la propriété ressource dans le contexte de la version actuelle de l'API. spécifique à chaque version.

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. En outre, 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.

Remarque:Requêtes HTTPS de diffusion de notifications spécifier un user-agent APIs-Google et respecter le fichier robots.txt comme décrit dans la section API Google user-agent

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 que vous avez reçus L'URL comprend 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 cet élément canal de notification.
`X-Goog-Message-Number`	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.
`X-Goog-Resource-ID`	Valeur opaque identifiant la ressource surveillée. Cet ID est stable entre les versions 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` pour en savoir plus.
`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` pour en savoir plus. Non fourni avec les messages `sync`.
`X-Goog-Channel-Expiration`	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.
`X-Goog-Channel-Token`	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.

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.

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