Suscribirse a WebHooks para recibir notificaciones de cambios

  • Artículo

Se aplica a: blocs de notas para consumidores de OneDrive

Mantente al día de los cambios que realizan tus usuarios en OneNote suscribiéndote al servicio de WebHooks.

Si tienes una aplicación web o servicio web que expone un punto de conexión público, puedes recibir notificaciones casi en tiempo real cuando se realicen cambios en los blocs de notas personales de OneNote en OneDrive.

Las notificaciones se envían cuando se realiza un cambio en el bloc de notas de uno de tus usuarios. Esto incluye cambios en cualquier nivel de la jerarquía del bloc de notas, como los cambios en el contenido de la página.

Las notificaciones no contienen información detallada sobre los cambios o los usuarios. Te avisan cuando se realiza un cambio, para que tu controlador de eventos pueda consultar los detalles específicos. El servicio de WebHooks no admite suscripciones detalladas para tipos de cambios o recursos específicos.

Las notificaciones se envían como solicitudes POST que contienen un objeto JSON, tal y como se muestra en el siguiente ejemplo.

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

Tu servicio debe responder rápidamente a la notificación con uno de los siguientes códigos de estado HTTP:

  • 200 Correcto
  • 202 Aceptado
  • 204 Sin contenido

Si no recibimos la respuesta, volveremos a intentarlos varias veces más con un retraso exponencial y, finalmente, descartaremos el mensaje.

Para obtener más información acerca de las notificaciones

  • Las notificaciones se asignan al contenido que pertenece a tus usuarios, independientemente de quién haya realizado el cambio. Las notificaciones no se envían por cambios realizados en el contenido que se comparte con tus usuarios. Entonces, si Juan (no tu usuario) realiza un cambio en un bloc de notas de Alicia (tu usuaria), recibirás una notificación con la ID de usuario de Alicia. Pero no recibirás una notificación si Alicia hace un cambio en el bloc de notas de Juan.

  • Los userId en la notificación coinciden con los ID que se devuelven en el encabezado X-AuthenticatedUserId de las respuestas API de OneNote.

  • Los cambios realizados en un corto período de tiempo se pueden combinar en una sola notificación.

  • Las notificaciones suelen enviarse unos pocos minutos después de efectuar el cambio. Esta latencia asegura que los cambios estén disponibles para la API, aunque el cambio pueda estar disponible inmediatamente en el cliente.

Flujo de trabajo de notificaciones

Un flujo de trabajo de notificaciones de alto nivel típico es algo como esto:

  1. Se realizan cambios en el bloc de notas de uno de tus usuarios.
  2. OneNote envía una o más solicitudes POST a tu URL de devolución de llamada registrada. Cada solicitud POST representa uno o más cambios.
  3. Tu servicio responde a cada solicitud POST con un código de estado HTTP 200, 202 o 204.
  4. Las notificaciones desencadenan un controlador de eventos en tu API de devolución de llamada.
  5. Luego se realiza una consulta del servicio OneNote para obtener detalles de los cambios.

Las consultas basadas en la marca de hora del último cambio son la mejor manera de garantizar que capturas todos los cambios. Se almacenan las marcas de hora del lastModifiedTime más reciente de los resultados, para utilizarla en tu próxima consulta de cambio.

Esta solicitud utiliza la propiedad de lastModifiedTime para devolver todas las páginas que han cambiado desde que se ha almacenado la marca de hora:

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

Después de consultar los cambios, se actualizan las marcas de hora almacenadas con el último lastModifiedTime.

Nota

El servicio de WebHooks no está destinado a ser utilizado como un mecanismo de sincronización. Debes consultar periódicamente los cambios en caso de que una notificación no pueda enviarse o recibirse.

Suscribirse al servicio de WebHooks

Para suscribirse al servicio WebHooks de OneNote, tendrás que:

  • Registrar una URL de devolución de llamada que sea un punto de conexión público (HTTP o HTTPS) donde recibirás las solicitudes POST HTTP del servicio WebHooks de OneNote. El servicio WebHooks no seguirá los redireccionamientos HTTP.

  • Solicita los siguientes permisos para tu aplicación:

    • wl.offline_access (Permiso de la cuenta de Microsoft)
    • office.onenote, office.onenote_create, office.onenote_update_by_app, o office.onenote_update para la API de OneNote, según lo que haga tu aplicación

Cuando estés listo para suscribirte, ponte en contacto con nosotros a @onenotedev. Alguien de nuestro equipo trabajará contigo para ayudarte con la configuración.

A medida que los usuarios se registren en tu aplicación, deberás hacer una llamada a la API de OneNote en su nombre (por ejemplo: GET .../me/notes/notebooks). Esta llamada:

  • Garantizará que OneNote registre al usuario para las notificaciones de devolución de llamada.
  • Permitirá que recuperes y almacenes las ID de usuario, que se devuelven en el encabezado de respuesta X-AuthenticatedUserId.

Modelo de caducidad

Para las notificaciones de WebHook, registramos las ID de tus usuarios. Cada interacción hecha por un usuario renueve el registro de usuario durante seis meses más.

Un registro se inactiva después de un período de seis meses sin que haya habido llamadas a la API de OneNote en nombre del usuario. No recibirás notificaciones de usuarios inactivos, ni de usuarios que desinstalen tu aplicación o revoquen sus permisos.

Debido a que las notificaciones de cambio no contienen detalles sobre el usuario o el cambio, se mitiga el riesgo potencial para la privacidad del usuario. Los usuarios inactivos se vuelven a registrar cada vez que llamas a la API de OneNote en su nombre.

Vea también