S'abonner à Webhooks pour recevoir les notifications de modification

  • Article

S'applique à : Blocs-notes de l'utilisateur sur OneDrive

Soyez informé des modifications que vos utilisateurs apportent dans OneNote en vous abonnant au service Webhooks.

Si vous disposez d'une application web ou d'un service web qui expose un point de terminaison public, vous pouvez recevoir des notifications en temps quasi-réel lorsque des modifications sont apportées aux blocs-notes OneNote personnels de vos utilisateurs sur OneDrive.

Les notifications sont envoyées lorsqu'une modification est effectuée dans un bloc-notes appartenant à l'un de vos utilisateurs. Cela inclut les modifications à tous les niveaux de la hiérarchie du bloc-notes, y compris les modifications apportées au contenu de la page.

Les notifications ne contiennent aucune information détaillée sur les modifications ou les utilisateurs. Elles vous notifient qu'une modification est apportée, ce qui permet à votre gestionnaire d'événements de rechercher des détails spécifiques. Le service Webhooks ne prend pas en charge les petits abonnements pour des types spécifiques de modifications ou de ressources.

Les notifications sont envoyées en tant que demandes POST contenant un objet JSON, comme indiqué dans l'exemple suivant.

{
  "value":[
    {
      "subscriptionId":"client-id-of-your-registered-application",
      "userId":"id-of-the-user-who-owns-the-changed-resource" 
    }
  ]
}

Votre service doit répondre promptement à la notification avec l'un des codes d'état HTTP suivants :

  • 200 OK
  • 202 Accepté
  • 204 Aucun contenu

Si nous ne recevons pas la réponse, nous réessaierons plusieurs fois avec une temporisation exponentielle, et rejetterons finalement le message.

Plus d’informations sur les notifications

  • Les notifications portent sur le contenu appartenant à vos utilisateurs, peu importe qui est l'auteur de la modification. Les notifications ne sont pas envoyées pour les modifications apportées au contenu partagé avec vos utilisateurs. Donc, si Bob (qui n'est pas votre utilisateur) apporte une modification à un bloc-notes appartenant à Alice (votre utilisateur), vous recevrez une notification avec l'ID d’utilisateur d'Alice. Vous ne recevrez pas de notification si Alice modifie le bloc-notes de Bob.

  • Le userId dans la notification correspond à l'ID renvoyé dans l'en-tête X-AuthenticatedUserId des réponses de OneNote API.

  • Les modifications apportées dans un court laps de temps peuvent être combinées en une seule notification.

  • Les notifications sont généralement envoyées dans les minutes qui suivent la modification. Cette latence garantit que les modifications sont disponibles pour l'API, même si la modification peut être disponible immédiatement chez le client.

Flux des notifications

Un flux élevé de notifications ressemble typiquement à ceci :

  1. Des modifications sont apportées à un bloc-notes appartenant à l'un de vos utilisateurs.
  2. OneNote envoie une ou plusieurs demandes POST à ​​votre URL de rappel enregistrée. Chaque demande POST représente un ou plusieurs changements.
  3. Votre service répond à chaque demande POST avec un code d'état HTTP 200, 202 ou 204.
  4. Les notifications déclenchent un gestionnaire d'événements dans votre API de rappel.
  5. Vous interrogez le service OneNote pour les modifications détaillées.

L'interrogation basée sur le timestamp de la dernière modification est la meilleure façon de vous assurer de capturer tous les changements. Stockez le timestamp du plus récent lastModifiedTime à partir des résultats, puis utilisez-le dans votre prochaine requête de modification.

Cette requête utilise la propriété lastModifiedTime pour renvoyer toutes les pages qui ont été modifiées depuis votre timestamp stocké :

GET ../me/notes/pages?filter=lastModifiedTime%20ge%20{stored-iso-8601-timestamp}

Après votre requête de modification, il faut mettre à jour votre timestamp stocké avec la dernière lastModifiedTime.

Notes

Le service Webhooks n'est pas destiné à être utilisé en tant que mécanisme de synchronisation. Vous devriez envoyer périodiquement une requête de modifications dans l'événement pour lequel une notification ne peut pas être envoyée ou reçue.

Comment s’abonner au service Webhooks

Pour vous abonner au service OneNote Webhooks, vous aurez besoin de :

  • Enregistrer une URL de rappel qui est un point de terminaison public (HTTP ou HTTPS) où vous recevrez des demandes HTTP POST depuis le service OneNote Webhooks. Le service Webhooks ne suivra pas les redirections HTTP.

  • Demander les autorisations suivantes pour votre application :

    • wl.offline_access (Autorisation de compte Microsoft)
    • office.onenote, office.onenote_create, office.onenote_update_by_app, ou office.onenote_update pour l'API OneNote, en fonction de ce que fait votre application

Lorsque vous êtes prêt à vous abonner, contactez-nous à @onenotedev. Un membre de notre équipe travaillera avec vous pour vous guider dans l'installation.

Lorsque vos utilisateurs s'inscrivent à votre application, vous devriez effectuer un appel API OneNote en leur nom (par exemple : GET ../me/notes/notebooks). Cet appel va :

  • Vous garantir que OneNote enregistre l'utilisateur pour les notifications de rappel.
  • Vous permettre de récupérer et de stocker l'ID de l'utilisateur, qui est renvoyé dans l'en-tête de réponse X-AuthenticatedUserId .

Modèle d'expiration

Pour les notifications de Webhooks, nous enregistrons les ID de vos utilisateurs. Chaque interaction réalisée par un utilisateur donné renouvelle l'inscription de l'utilisateur pour six mois.

Une inscription devient inactive après une période de six mois pendant laquelle vous n'avez pas appelé l'API OneNote au nom de l'utilisateur. Vous ne recevrez pas de notifications pour les utilisateurs inactifs, y compris les utilisateurs qui désinstallent votre application ou révoquent ses autorisations.

Parce qu'une notification de modification ne contient pas de détails sur l'utilisateur ou sur la modification, le risque potentiel pour la confidentialité de l'utilisateur est atténué. Les utilisateurs inactifs sont réenregistrés chaque fois que vous appelez l'API OneNote en leur nom.

Voir aussi