Utilisation des webhooks pour recevoir des notifications de service à service

OneDrive envoie des notifications de service à service via des webhooks. Les webhooks fournissent un pipeline de notification permettant à votre application d’être informée des modifications apportées au lecteur d’un utilisateur sans avoir à interroger le service.

Lorsque des éléments auxquels votre application a accès dans le lecteur d’un utilisateur sont modifiés, l’URL que vous fournissez reçoit une requête lui signalant que des modifications ont eu lieu.

Tâches courantes

Tâche	Méthode HTTP
Créer un abonnement	POST /subscriptions
Supprimer un abonnement	DELETE /subscriptions/{id}
Mettre à jour un abonnement	PATCH /subscriptions/{id}

Inscription

Pour vous inscrire à des webhooks, ajoutez un nouvel abonnement à l’élément représentant le niveau supérieur de l’étendue du projet pour lequel vous souhaitez recevoir les modifications.

Pour plus d’informations sur l’enregistrement d’une URL pour la réception de notifications, voir Ajout d’un nouvel abonnement.

Étendue des notifications

Les notifications Webhook sont uniquement envoyées à votre application pour les modifications qui répondent aux critères suivants :

• Un utilisateur a autorisé votre application à accéder au contenu de OneDrive.
• L’application a accès à l’élément qui génère la notification.
• L’abonnement n’a pas expiré.

Votre application ne recevra pas de notifications pour les éléments qui ont été partagés avec l’utilisateur qui s’est connecté ou les éléments distants sur le lecteur de l’utilisateur, sauf si des abonnements distincts ont été créés sur les éléments d’origine.

Réception de notifications

Une fois que votre abonnement est créé, OneDrive envoie des requêtes POST à votre URL inscrite lorsque des éléments appartenant à l’étendue de la notification sont modifiés. Plusieurs notifications de votre service peuvent être regroupées en une seule demande si des modifications sont apportées à plusieurs utilisateurs au cours de la même période.

Exemple de notification

Le corps de la requête HTTP à votre URL de notification contient une ressource Webhook Notification semblable à la suivante :

{
  "value": [
    {
      "subscriptionId": "A640DFF3-0429-44FC-AF7E-30523A476864",
      "expirationDateTime": "2017-02-22T16:00:00Z",
      "resource": "/me/drive/root",
      "clientState": "client-specific string"
    }
  ]
}

Vous pouvez remarquer que la notification n’inclut pas d’informations sur les modifications qui l’ont déclenchée. Votre application est censée utiliser le verbe delta pour détecter les modifications éventuelles apportées à l’état des éléments dans OneDrive et stocker la valeur syncToken pour la prochaine fois que vous recevez une notification.

Gestion des erreurs

Si une erreur se produit lors de l’envoi de la notification à votre service, OneDrive suivra une logique d’interruption exponentielle. Toute demande dont la réponse a un code de statut HTTP en dehors de la plage 200-299 ou qui arrive à expiration sera réessayée dans les minutes suivantes. Si la demande n’aboutit pas après 15 minutes, la notification est abandonnée.

Le système essaiera d’envoyer les notifications futures à votre service, mais le service se réserve le droit de supprimer l’abonnement si un nombre suffisant d’échecs est détecté.

Expiration

Les nouveaux abonnements reçoivent automatiquement une date d’expiration si aucune n’est fournie lors de la création de l’abonnement. Par défaut, les abonnements sont configurés pour expirer six mois après leur création.

Meilleures pratiques

Lorsque vous utilisez des webhooks tenez compte des points importants suivants :

Service à service

N’essayez pas d’utiliser des webhooks pour avertir directement les appareils clients. Chaque application dispose d’une URL webhook unique qui est appelée pour tous les utilisateurs. Cette URL doit pointer vers un service que vous contrôlez. Vous pouvez laisser votre service analyser les messages de notification et transférer des notifications Push appropriées aux applications client comme vous le souhaitez.

Répondre rapidement

Votre application dispose d’un temps limité pour répondre à la demande. Vous devez mettre en file d’attente les informations concernant les mises à jour de notification, puis traiter ces requêtes sur un thread séparé. N’essayez pas d’extraire des modifications à partir du service OneDrive avant d’avoir répondu à la requête webhook.

Attendez-vous à des notifications simultanées

Dans de nombreux cas, vous recevrez plusieurs fois de suite des notifications adressées au même utilisateur en rapide succession. Par exemple, si un utilisateur est nouveau ou qu’il charge un lot de contenu vers OneDrive, vous pouvez recevoir plusieurs notifications concernant le même utilisateur avant d’avoir traité la première. Assurez-vous que les actions qui répondent aux notifications webhook gèrent correctement ce cas.