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

La consulta de delta permite a las aplicaciones detectar entidades recién creadas, actualizadas o eliminadas sin realizar una operación de 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.

Tutorial: usar las notificaciones de cambio y realizar el seguimiento de los cambios con Microsoft Graph

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 empieza con una llamada a una solicitud GET con la función delta en el recurso deseado.

2. Microsoft Graph envía una respuesta que contiene el recurso solicitado y un token de estado.

   a. Si se devuelve una dirección URL @odata.nextLink, podría haber más páginas de datos para recuperar en la sesión. La aplicación continúa realizando solicitudes mediante la dirección URL @odata.nextLink para recuperar todas las páginas de datos hasta que se incluya una dirección URL @odata.deltaLink en la respuesta.

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

3. Cuando la aplicación necesita obtener información sobre los cambios en el recurso, realiza una nueva solicitud con la dirección URL @odata.deltaLink recibida en el paso 2. Esta solicitud puede realizarse inmediatamente después de completar el paso 2, o cuando la aplicación comprueba los 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 Azure Active Directory (por ejemplo, usuarios y grupos) admiten los escenarios de "sincronizar 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. En OneDrive y SharePoint, los recursos también son compatibles con esta característica. En el caso de los recursos de OneDrive y SharePoint, anexe token=latest en su lugar.

Nota

En general, se hace referencia a la función de consulta diferencial anexando /delta al nombre del recurso. Sin embargo, /delta es un método abreviado de teclado para el nombre completo /microsoft.graph.delta que verá en las solicitudes generadas por los SDK de Microsoft Graph.

Nota

La solicitud inicial a la función de consulta delta (sin $deltaToken o $skipToken) devolverá los recursos que existen actualmente en la colección. No se devolverán los recursos creados y eliminados 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.

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 dirección URL @odata.nextLink incluye un $skipToken y una dirección URL @odata.deltaLink incluye un $deltaToken.

Estos tokens son opacos para el cliente. A continuación se muestra la información que necesita saber sobre ellos:

• Cada token refleja el estado y representa una instantánea del recurso en esa ronda de seguimiento de cambios.

• Los tokens de estado también codifican e incluyen otros parámetros de consulta (como $select) especificados en la solicitud de consulta de delta inicial. Por lo tanto, no es necesario repetirlos en las solicitudes de consulta de delta siguientes.

• 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 especificado en los @odata.nextLink o @odata.deltaLink proporcionados en la respuesta. La aplicación de llamada solo necesita especificar los parámetros de consulta una vez por adelantado. Microsoft Graph agrega los parámetros especificados automáticamente para todas las solicitudes subsiguientes.

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 de la consulta delta. Suponga que el mismo elemento podría mostrarse en cualquier lugar en la secuencia @odata.nextLink y téngalo en cuenta en la lógica de combinación.

• $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:

• $expand no es compatible.

• $top no es compatible.

• $orderby no es compatible.

• Si se usa un parámetro de consulta $select, este indica que el cliente prefiere registrar los cambios solo en las propiedades o relaciones especificadas en la instrucción $select. Si se produce un cambio en una propiedad que no está activada, el recurso en el que se ha producido el cambio no aparecerá en la respuesta de delta tras 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.

• Definir el ámbito de los filtros le permite hacer un seguimiento de los cambios realizados en uno o varios usuarios o en grupos específicos por id. de objeto. Por ejemplo, la siguiente solicitud devuelve cambios para los grupos que coincidan con los id. especificados en el filtro de 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 están representadas por sus id. con al menos las propiedades que se han actualizado, pero pueden incluirse otras propiedades.

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

Las instancias quitadas se representan mediante sus id. y un objeto @removed. El objeto @removed puede incluir información adicional sobre por qué se eliminó 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 la consulta inicial de delta y en las respuestas de seguimiento (deltaLink). Los clientes con solicitudes de consulta delta deben diseñarse para administrar estos objetos en las respuestas.

Nota

Es posible que una sola entidad se incluya 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. Tenga en cuenta que algunos de los recursos disponibles en v1.0 tienen sus correspondientes funciones delta en el estado de versión preliminar, tal y como se indica.

Colección de recursos	API
Aplicaciones	Función delta del recurso application
Unidades administrativas (versión preliminar)	Función delta (versión preliminar) del recurso administrativeUnit
Mensajes de chat en un canal	Función delta (versión preliminar) de chatMessage
Roles de directorio	Función delta del recurso directoryRole
Elementos de la unidad*	Función delta del recurso driveItem
Tareas educativas	Función delta del recursoeducationAssignment
Categorías educativas	Funcióndelta del recursoeducationCategory
Clases educativas	Función delta del recurso educationClass
Centros educativos	Función delta del recurso educationSchool
Usuarios educativos	Función delta del recurso educationUser
Eventos en una vista de calendario (intervalo de fechas) del calendario principal	La función delta del recurso event
Grupos	La función delta del recurso group
Elementos de lista*	La función delta del recurso listItem
Carpetas de correo	La función delta del recurso mailFolder
Mensajes de una carpeta	La función delta del recurso message
Contactos de la organización	La función delta del recurso orgContact
OAuth2PermissionGrants	La función delta del recurso oauth2permissiongrant
Carpetas de contactos personales	La función delta del recurso contactFolder
Contactos personales en una carpeta	La función delta del recurso contact
Elementos del** planificador (vista previa)	Función delta (versión preliminar) de todos los segmentos del recurso plannerUser
Entidades de servicio	Función delta del recursoservicePrincipal
Tareas pendientes en una lista de tareas	Función delta del recurso todoTask
Listas de tareas pendientes	Función delta del recurso todoTaskList
Usuarios	La función delta del recurso user

* El patrón de uso para los recursos de OneDrive y SharePoint es similar a los demás recursos compatibles con algunas diferencias secundarias de sintaxis. La consulta delta para unidades se actualizará en el futuro para que sea coherente con otros tipos de recursos. Para obtener más información sobre la sintaxis actual, consulte driveItem: delta y listItem: delta.

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

Limitaciones

Propiedades almacenadas fuera del almacén de datos principal

Algunos recursos contienen propiedades que se almacenan fuera del almacén de datos principal del recurso (por ejemplo, el recurso de usuario se almacena principalmente en el sistema Azure AD, mientras que algunas propiedades, como skills, se almacenan en SharePoint Online). Actualmente, no se admiten estas propiedades como parte del seguimiento de cambios. Cambiar una de esas propiedades no hará que se muestre un objeto en la respuesta de consulta delta. Actualmente, sólo las propiedades almacenadas en el almacén de datos principal desencadenan cambios en la consulta delta.

Para comprobar que una propiedad puede usarse en una consulta delta, pruebe a realizar una operación GET normal en la colección de recursos y seleccione la propiedad que le interesa. Por ejemplo, puede probar la propiedad aptitudes en la colección de usuarios.

GET https://graph.microsoft.com/v1.0/users/?$select=skills

Como la propiedad skills se almacena fuera de Azure AD, la respuesta es la siguiente:

HTTP/1.1 501 Not Implemented
Content-type: application/json

{
    "error": {
        "code": "NotImplemented",
        "message": "This operation target is not yet supported.",
        "innerError": {
            "request-id": "...",
            "date": "2019-09-20T21:47:50"
        }
    }
}

Esto indica que la propiedad skills no es compatible con la consulta delta en el recurso user.

Propiedades de navegación

No se admiten propiedades de navegación. Por ejemplo, no puede realizar un seguimiento de los cambios de la colección de usuarios que incluyan cambios de la propiedad photo, porque photo es una propiedad de navegación almacenada fuera de la entidad de usuario y realizar cambios en ella no hace que el objeto de usuario se incluya en la respuesta delta.

Retrasos del procesamiento

Es posible que se produzcan retrasos variables entre el momento en que se realiza un cambio en una instancia de recurso, que puede realizarse mediante una interfaz de aplicación o API, y la hora en que se reflejará el cambio en una respuesta de consulta diferencial.

A veces, es posible que los cambios que se han producido en el objeto no se indiquen al seleccionar el @odata.nextLink o @odata.deltaLink. Esto se debe a que algunas solicitudes pueden tener retrasos de replicación para los objetos que se crearon, actualizaron o eliminaron recientemente. Reintente el @odata.nextLink o @odata.deltaLink después de un tiempo para recuperar los cambios más recientes.

Nubes nacionales

Las consultas diferenciales solo están disponibles para los clientes alojados en la nube pública y Microsoft Graph China ofrecido por 21Vianet.

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 gran esfuerzo para reducir las reproducciones, aún 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). Esto es una indicación de que la aplicación debe reiniciarse con una sincronización completa del inquilino de destino. Esto suele ocurrir para evitar la incoherencia de los datos debido al mantenimiento interno o la migración 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 (mensaje, mailFolder, evento, contacto, contactFolder, todoTask y todoTaskList) no se ha fijado el límite superior, sino que depende del tamaño de la memoria caché del token delta interno. Aunque se agregan continuamente tokens delta en la caché, cuando se supera la capacidad de la caché, se eliminan los tokens delta anteriores.

En el caso de un token expirado, 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.

Requisitos previos

Los mismos permisos que se requieren para leer un recurso específico también son necesarios para realizar la consulta delta en ellos.

Ejemplos de solicitud de consulta delta

• Obtener los cambios incrementales en los eventos en una vista de calendario
• Obtener los cambios incrementales en los mensajes de una carpeta
• Obtener los cambios incrementales en los grupos
• Obtener los cambios incrementales en los usuarios