Usar la consulta delta para realizar el seguimiento de los cambios en datos de Microsoft Graph

  • Artículo

La consulta delta, también denominada seguimiento de cambios, permite a las aplicaciones detectar entidades recién creadas, actualizadas o eliminadas sin realizar una lectura completa del recurso de destino con cada solicitud. Las aplicaciones de Microsoft Graph pueden usar consultas de delta para sincronizar los cambios de forma eficaz con un almacén de datos local.

El uso de consultas delta ayuda a evitar el sondeo constante de Microsoft Graph, ya que la aplicación solo solicita datos que han cambiado desde la última solicitud. Este patrón permite a la aplicación reducir la cantidad de datos que solicita, lo que reduce el costo de la solicitud y, como tal, probablemente limite las posibilidades de que se limiten las solicitudes.

Usar la consulta de delta para realizar el seguimiento de los cambios en una colección de recursos

El patrón de llamada típico es el siguiente:

  1. La aplicación realiza una solicitud GET con la función delta en el recurso deseado. Por ejemplo, GET https://graph.microsoft.com/v1.0/users/delta.

    Sugerencia

    /delta es un acceso directo para el nombre /microsoft.graph.deltacompleto. Las solicitudes generadas por los SDK de Microsoft Graph usan el nombre completo.

  2. Microsoft Graph responde con el recurso solicitado y un token de estado.

    a. Si Microsoft Graph devuelve una @odata.nextLink dirección URL, hay más páginas de datos que recuperar en la sesión, incluso si la respuesta actual contiene un resultado vacío. La aplicación usa la @odata.nextLink dirección URL para seguir realizando solicitudes para recuperar todas las páginas de datos hasta que Microsoft Graph devuelva una @odata.deltaLink dirección URL en la respuesta.

    b. Si Microsoft Graph devuelve una @odata.deltaLink dirección URL, no hay más datos sobre el estado existente del recurso que se devolverá en la sesión actual. Para las solicitudes futuras, la aplicación usa la dirección URL @odata.deltaLink para obtener información sobre los cambios en el recurso.

    Nota:

    La respuesta de Microsoft Graph del paso 2 incluye los recursos que existen actualmente en la colección. No se devuelven los recursos que se eliminaron antes de la consulta delta inicial. Las actualizaciones que se realicen antes de la solicitud inicial se resumen en el recurso devuelto en su último estado.

  3. Cuando la aplicación necesita obtener información sobre los cambios en el recurso, usa la dirección URL que recibió en el @odata.deltaLink paso 2 para realizar solicitudes. La aplicación puede realizar esta solicitud inmediatamente después de completar el paso 2 o cuando comprueba si hay cambios.

  4. Microsoft Graph devuelve una respuesta que describe los cambios en el recurso desde la solicitud anterior, y una dirección URL @odata.nextLink o @odata.deltaLink.

Nota:

  • Los recursos almacenados en Microsoft Entra ID (como usuarios y grupos) admiten escenarios de "sincronización desde ahora". Esto le permite omitir los pasos 1 y 2 (si no le interesa recuperar el estado del recurso completo) y solicitar el último @odata.deltaLink en su lugar. Anexar $deltatoken=latest a la función delta y la respuesta contendrá un @odata.deltaLink sin datos de recursos. Los recursos de OneDrive y SharePoint también admiten esta característica, pero requieren token=latest en su lugar.
  • $select y $deltaLink los parámetros de consulta son compatibles con algunos recursos de Microsoft Entra para que los clientes puedan cambiar las propiedades de las que quieren realizar un seguimiento de un existente @odata.deltaLink. Las consultas delta con y $select$skiptoken no se admiten.

Tokens de estado

Una respuesta GET de consulta de delta siempre incluye una dirección URL especificada en un encabezado de respuesta @odata.nextLink o @odata.deltaLink. La @odata.nextLink dirección URL incluye un $skiptokeny una @odata.deltaLink dirección URL incluye .$deltatoken

Estos tokens son opacos para la aplicación cliente, pero son importantes de la siguiente manera:

  • Cada token refleja el estado y representa una instantánea del recurso en esa ronda de seguimiento de cambios.
  • Los tokens de estado codifican e incluyen parámetros de consulta (como $select) especificados en la solicitud de consulta delta inicial. Por lo tanto, no modifique las solicitudes de consulta delta posteriores para repetir estos parámetros de consulta.
  • Al llevar a cabo consultas de delta, puede copiar y aplicar las direcciones URL @odata.nextLink o @odata.deltaLink a la siguiente llamada a función delta sin tener que examinar el contenido de la dirección URL, incluido su token de estado.

Parámetros de consulta opcionales

Si un cliente usa un parámetro de consulta, debe especificarse en la solicitud inicial. Microsoft Graph codifica automáticamente el parámetro de consulta especificado en o @odata.nextLink@odata.deltaLink en la respuesta y en todas las direcciones URL posteriores @odata.nextLink o @odata.deltaLink .

Tenga en cuenta el soporte limitado general de los siguientes parámetros de consulta opcionales:

  • $orderby

    No suponga una secuencia específica de las respuestas devueltas desde una consulta delta. El mismo elemento puede mostrarse en cualquier lugar en la secuencia de @odata.nextLink. Tenga esto en cuenta en sus combinaciones.

  • $top

    El número de objetos en cada página puede variar en función del tipo de recurso y el tipo de cambios realizados en el recurso.

Para el recurso message, consulte los detalles de soporte de parámetros de consulta en una consulta delta.

Para los recursos user y group, existen restricciones en el uso de algunos parámetros de la consulta:

  • No se admite $expand.

  • No se admite $top.

  • No se admite $orderby.

  • Si se usa un $select parámetro de consulta, el parámetro indica que el cliente prefiere solo realizar un seguimiento de los cambios en las propiedades o relaciones especificadas en la $select instrucción . Si se produce un cambio en una propiedad que no está seleccionada, el recurso para el que cambió la propiedad no aparece en la respuesta diferencial después de una solicitud posterior.

  • $select también admite propiedades de navegación de administrador y miembros para los usuarios y grupos, respectivamente. Seleccionar dichas propiedades permite realizar un seguimiento de los cambios en el administrador y en la pertenencia a grupos de los usuarios.

  • Los filtros de ámbito le permiten realizar un seguimiento de los cambios en uno o más usuarios o grupos específicos, filtrando solo por identificador de objeto. Por ejemplo, la siguiente solicitud devuelve los cambios de los grupos que coinciden con los identificadores especificados en el filtro de la consulta.

https://graph.microsoft.com/beta/groups/delta/?$filter=id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e'

Representación de recursos en la respuesta de consulta delta

  • Las instancias de un recurso compatible recién creadas se representan en la respuesta de consulta de delta con su representación estándar.

  • Las instancias actualizadas se representan mediante su identificador con al menos las propiedades actualizadas, pero es posible que se incluyan otras propiedades.

  • Las relaciones en usuarios y grupos se representan como anotaciones en la representación de recursos estándar. Estas anotaciones usan el formato propertyName@delta. Las anotaciones se incluyen en la respuesta de la solicitud de consulta delta inicial.

  • Las instancias eliminadas se representan mediante su identificador y un objeto @removed . El objeto @removed podría incluir información adicional sobre por qué se quitó la instancia. Por ejemplo, "@removed": {"reason": "changed"}. Las razones posibles de @removed pueden ser changed o deleted.

    • changed indica que el elemento se eliminó y puede restaurarse desde deletedItems.

    • deleted indica que el elemento se ha eliminado y no se puede restaurar.

      El objeto @removed se puede devolver en la respuesta de consulta delta inicial y en las respuestas de seguimiento (@odata.nextLink). Por ejemplo, un objeto de directorio eliminado que todavía se puede restaurar a partir de elementos eliminados se muestra como "@removed": {"reason": "changed"}. Los clientes con solicitudes de consulta delta deben diseñarse para administrar estos objetos en las respuestas.

  • Las instancias restauradas a partir de deletedItems se muestran como instancias recién creadas en la respuesta de consulta delta.

Nota:

Una sola entidad se puede contener varias veces en la respuesta, si esa entidad se cambió varias veces y en determinadas condiciones. Las consultas delta permiten que la aplicación enumere todos los cambios, pero no garantiza que las entidades estén unificadas en una única respuesta.

Recursos admitidos

Actualmente, la consulta delta es compatible con los siguientes recursos. Algunos recursos que están disponibles en la versión 1.0 tienen sus funciones delta correspondientes todavía en estado de vista previa, como se indica.

Nota: La función delta para los recursos marcados con un asterisco (*) solo está disponible en el punto de /beta conexión.

Colección de recursos API
application application: función delta
administrativeUnit administrativeUnit: función delta
callRecording callRecording: función delta
callTranscript callTranscript: función delta
chatMessage chatMessage: función delta
dispositivo device: función delta
directoryRole directoryRole: función delta
directoryObject directoryObject: función delta
driveItem1 driveItem: función delta
educationAssignment educationAssignment: función delta
educationCategory educationCategory: función delta
educationClass educationClass: función delta
educationSchool educationSchool: función delta
educationUser educationUser: función delta
event event: función delta
group group: función delta
listItem1 listItem: función delta
mailFolder mailFolder: función delta
message message: función delta
orgContact orgContact: función delta
oAuth2PermissionGrant oAuth2PermissionGrant: función delta
contactFolder contactFolder: función delta
recurso de contacto contact: función delta
plannerBucket * plannerBucket: función delta
plannerUser2 plannerUser: función delta
sites Función delta del recurso de sitio
servicePrincipal servicePrincipal: función delta
todoTask todoTask: función delta
todoTaskList todoTaskList: función delta
user user: función delta

Nota:

1 El patrón de uso de los recursos de OneDrive y SharePoint es similar al de los demás recursos admitidos con algunas diferencias de sintaxis menores. Para obtener más información sobre la sintaxis actual, vea driveItem: delta y listItem: delta.

2 El patrón de uso de los recursos de Planner es similar a otros recursos admitidos con algunas diferencias. Para obtener más información, consulte planner: delta.

Nubes nacionales

Las consultas delta para los recursos admitidos están disponibles para los clientes hospedados en la nube pública, Microsoft Cloud for US Government y Microsoft Cloud China operados por 21Vianet.

Limitaciones

No se realiza el seguimiento de los cambios en las propiedades almacenadas fuera del almacén de datos principal.

Algunos recursos contienen propiedades que se almacenan fuera del almacén de datos principal para el recurso. Por ejemplo, los datos de recursos de usuario se almacenan principalmente en el identificador de Microsoft Entra, pero algunas de sus propiedades, como las aptitudes, se almacenan en SharePoint Online. Actualmente, solo las propiedades almacenadas en el almacén de datos principal desencadenan cambios en la consulta delta; las propiedades almacenadas fuera del almacén de datos principal no se admiten como parte del seguimiento de cambios. Por lo tanto, un cambio en cualquiera de estas propiedades no da lugar a que un objeto aparezca en la respuesta de consulta delta.

Para obtener más información sobre las propiedades almacenadas fuera del almacén de datos principal, consulte la documentación de usuarios y grupos .

Retrasos del procesamiento

Espere retrasos variables entre el momento en que cambia una instancia de recurso y el momento en que el cambio del que se realiza el seguimiento se refleja en una respuesta de consulta diferencial.

A veces, debido a retrasos en la replicación, es posible que los cambios en el objeto no aparezcan inmediatamente al seleccionar @odata.nextLink o @odata.deltaLink. Reintente el @odata.nextLink o @odata.deltaLink después de un tiempo para recuperar los cambios más recientes.

Reproducciones

Su solicitud debe prepararse para las reproducciones, que se producen cuando el mismo cambio aparece en respuestas posteriores. Aunque la consulta delta hace un mejor esfuerzo para reducir las repeticiones, todavía son posibles.

Reinicio de la sincronización

La consulta Delta puede devolver un código de respuesta de 410 Gone y un encabezado de localización que contiene una URL de solicitud con un token delta vacío $deltatoken (igual que la consulta inicial). Este estado suele evitar la incoherencia de datos debido al mantenimiento interno o la migración del inquilino de destino, y es una indicación de que la aplicación debe reiniciarse con una sincronización completa del inquilino de destino.

Duración del token

Los tokens delta solo son válidos durante un período de tiempo específico antes de que la aplicación cliente necesite volver a ejecutar una sincronización completa.

  • Para los objetos de directorio, el límite es de siete días.
  • Para los objetos educativos (educationSchool, educationUser y educationClass), el límite es de siete días.
  • Para las entidades de Outlook (message, mailFolder, event, contact, contactFolder, todoTask y todoTaskList), el límite superior no es fijo; depende del tamaño de la caché de tokens delta interna. Aunque se agregan continuamente tokens delta en la caché, cuando se supera la capacidad de la caché, se eliminan los tokens delta anteriores.

En caso de que el token expire, el servicio debe responder con un error de la serie 40X con códigos de error como syncStateNotFound. Para obtener más información, consulte Códigos de error en Microsoft Graph.

Combinación de notificaciones de cambios y consultas diferenciales

Una aplicación puede usar notificaciones de cambio de Microsoft Graph para suscribirse para recibir notificaciones cuando cambie un recurso específico. A continuación, la aplicación puede usar la consulta delta para solicitar todos los cambios desde la última vez que hizo la solicitud.

Las aplicaciones pueden usar esta estrategia para casi eliminar (solo para los recursos admitidos) la necesidad de sondear con frecuencia Microsoft Graph y procesar esos cambios para mantener sincronizado un almacén de datos local, lo que reduce considerablemente las posibilidades de que se limiten sus solicitudes.

Contenido relacionado

Obtenga más información sobre la consulta delta en los siguientes tutoriales: