Obtener los cambios incrementales en los mensajes de una carpeta

  • Artículo

La consulta delta permite consultar las adiciones, eliminaciones o actualizaciones de los mensajes en una carpeta, por medio de una serie de llamadas a función delta. Los datos de delta permiten mantener y sincronizar un almacén local de mensajes de un usuario, sin tener que capturar todo el conjunto de mensajes del usuario desde el servidor cada vez.

La sincronización de elementos de mensaje en un almacén local puede usar la consulta delta para la sincronización completa inicial y las sincronizaciones incrementales posteriores. Normalmente, realizaría una sincronización completa inicial de todos los mensajes de una carpeta (por ejemplo, la Bandeja de entrada del usuario) y, a continuación, obtendría los cambios incrementales en esa carpeta periódicamente.

Para obtener cambios incrementales de solo un tipo determinado (mensajes que se crean, actualizan o eliminan desde la sincronización inicial) realicen una ronda inicial de sincronización de todos los mensajes de la carpeta y, a continuación, obtengan cambios incrementales de un tipo deseado específico en rondas posteriores. Especifique el tipo de cambio deseado como una opción de consulta en la solicitud delta inicial; Microsoft Graph codifica automáticamente las opciones OData y de consulta personalizada en o @odata.nextLink@odata.deltaLink proporcionadas en la respuesta.

Seguimiento de cambios de mensajes en una carpeta

La consulta de delta es una operación por carpeta. Para realizar el seguimiento de los cambios de los mensajes en una jerarquía de carpetas, debe realizar un seguimiento de cada carpeta de forma individual.

El seguimiento de los cambios de mensajes en una carpeta de correo normalmente es una ronda de una o varias solicitudes GET con la función delta. La solicitud GET inicial es muy similar a la forma de obtener mensajes, salvo que se incluye la función delta:

GET https://graph.microsoft.com/v1.0/me/mailFolders/{id}/messages/delta

Una solicitud GET con la función delta función devuelve:

  • Un @odata.nextLink (que contiene una dirección URL con una llamada de función delta y un skipToken), o
  • Un @odata.deltaLink (que contiene una dirección URL con una llamada de función delta y un deltaToken).

Estos tokens son tokens de estado que son opacos para el cliente. Para continuar con una ronda de seguimiento de cambios, copie y aplique la dirección URL devuelta desde la última solicitud GET a la siguiente llamada de función delta para la misma carpeta. Un @odata.deltaLink devuelto en una respuesta significa que la ronda actual de seguimiento de cambios está completa. Se puede guardar y usar la dirección URL @odata.deltaLink cuando se inicia la siguiente ronda.

El resto de este artículo incluye 2 ejemplos:

  • Consulte el ejemplo 1 para obtener información sobre cómo usar las @odata.nextLink direcciones URL y @odata.deltaLink .
  • Vea el ejemplo 2 para obtener información sobre cómo obtener incrementalmente solo los mensajes creados desde la ronda inicial.

Usar parámetros de consulta en una consulta de delta para los mensajes

  • Puede utilizar un parámetro de consulta $select como en cualquier solicitud GET para especificar solo las propiedades que necesita para un mejor rendimiento. La id propiedad siempre se devuelve.
  • Compatibilidad con consultas de delta $select, $top, y $expand para los mensajes.
  • Hay compatibilidad limitada para $filter y $orderby:
    • Las únicas expresiones $filter admitidas son $filter=receivedDateTime+ge+{value} y $filter=receivedDateTime+gt+{value}.
    • La aplicación de $filter en una consulta delta solo devuelve un máximo de 5 000 mensajes.
    • La única expresión $orderby admitida es $orderby=receivedDateTime+desc. Si no incluye una $orderby expresión, no se garantiza el orden de devolución.
  • No hay compatibilidad con $search.

Además, para devolver solo cierto tipo de cambios (creados, actualizados o eliminados) en la respuesta de la consulta delta, puede filtrar opcionalmente el tipo de cambio deseado mediante una opción changeTypede consulta personalizada . Los valores posibles son created, updated o deleted.

GET /me/mailfolders/{id}/messages/delta?changeType=created
GET /me/mailfolders/{id}/messages/delta?changeType=updated
GET /me/mailfolders/{id}/messages/delta?changeType=deleted

Encabezado de solicitud opcional

Cada solicitud GET de la consulta delta devuelve una colección de uno o más mensajes en la respuesta. Opcionalmente se puede especificar el encabezado de solicitud, Prefer: odata.maxpagesize={x}, para establecer el número máximo de mensajes en una respuesta.

Ejemplo 1: sincronizar mensajes en una carpeta

En el siguiente ejemplo se muestran dos rondas de sincronización de una carpeta concreta que inicialmente contiene cinco mensajes.

La primera ronda implica una serie de tres solicitudes para sincronizar los cinco mensajes de la carpeta:

Después de la primera ronda, uno de los mensajes se elimina y otro se marca como leído. La segunda ronda de sincronización devuelve solo el delta (la eliminación y actualización) sin devolver los demás mensajes que se han mantenido iguales.

Solicitud inicial de ejemplo

En este ejemplo, la carpeta especificada se sincroniza por primera vez, por lo que la solicitud de sincronización inicial no incluye ningún token de estado. Esta ronda devuelve todos los mensajes de esa carpeta.

La primera solicitud especifica lo siguiente:

  • Un parámetro $select que devuelva las propiedades subject, sender y isRead de cada mensaje de la respuesta.
  • El encabezado de solicitud opcional, odata.maxpagesize, que devuelve dos mensajes a la vez.
GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2

Respuesta inicial de ejemplo

La respuesta incluye dos mensajes y un encabezado de respuesta @odata.nextLink. La dirección URL @odata.nextLink indica que la carpeta contiene más mensajes que recuperar.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
      "subject": "Holiday hours update",
      "isRead": false,
      "sender": {
        "emailAddress": {
          "name": "Dana Swope",
          "address": "danas@contoso.com"
        }
      },
      "id": "AAMkADNkNAAASq35xAAA="
    },
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB/\"",
      "subject": "Holiday promotion sale",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Samantha Booth",
          "address": "samanthab@contoso.com"
        }
      },
      "id": "AQMkADNkNAAAVRMKAAAAA=="
    }
  ]
}

Segunda solicitud de ejemplo

La segunda solicitud especifica la dirección URL @odata.nextLink devuelta de la respuesta anterior. Observe que ya no tiene que especificar el mismo parámetro $select como en la solicitud inicial, dado que el skipToken en la dirección URL @odata.nextLink lo codifica y lo incluye.

GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM HTTP/1.1
Prefer: odata.maxpagesize=2

Segunda respuesta de ejemplo

La segunda respuesta devuelve los dos siguientes mensajes próximos en la carpeta y otro @odata.nextLink, para indicar que hay más mensajes para obtener desde la carpeta.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlqfdAAAEfYB+\"",
      "subject": "Microsoft Virtual Academy at Contoso",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Elliot Hyde",
          "address": "elliot-hyde@tailspintoys.com"
        }
      },
      "id": "AQMkADNkNAAAgWkAAAA"
    },
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB+\"",
      "subject": "New or modified user account information",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Randi Welch",
          "address": "randiw@contoso.com"
        }
      },
      "id": "AQMkADNkNAAAgWJAAAA"
    }
  ]
}

Tercera solicitud de ejemplo

La tercera solicitud continúa usando la última dirección URL @odata.nextLink devuelta desde la última solicitud de sincronización.

GET https://graph.microsoft.com/v1.0/me/mailFolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU HTTP/1.1
Prefer: odata.maxpagesize=2

Tercera y última respuesta de ejemplo

La tercera respuesta devuelve el único mensaje restante en la carpeta y una @odata.deltaLink dirección URL que indica que la sincronización está completa por el momento para esta carpeta. Guarde y use la dirección URL @odata.deltaLink para sincronizar la misma carpeta en la siguiente ronda.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzFPjSbaPPxzjlzOTAAAEfYB+\"",
      "subject": "Fabric CDN now available",
      "isRead": true,
      "sender": {
        "emailAddress": {
          "name": "Jodie Sharp",
          "address": "Jodie.Sharp@contoso.com"
        }
      },
      "id": "AAMkADk0MGFkODE3LWEAAA="
    }
  ]
}

Sincronizar los mensajes de la misma carpeta en la siguiente ronda

Con desde @odata.deltaLink la última solicitud de la última ronda, solo puede obtener los mensajes que han cambiado (al agregar, eliminar o actualizar) en esa carpeta desde entonces. La primera solicitud de la ronda siguiente será similar a la mostrada a continuación, suponiendo que prefiere mantener el mismo tamaño de página máximo en la respuesta:

GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY HTTP/1.1
Prefer: odata.maxpagesize=2

La respuesta contiene un @odata.deltaLink. Esto indica que todos los cambios de la carpeta de correo remota están ahora sincronizados. Un mensaje se ha eliminado y el otro se ha cambiado.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
  "value": [
    {
      "@odata.type": "#microsoft.graph.message",
      "id": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS0Dh_6qB-pB2Sa2pUum19a6YAAKnLuxoAAA=",
      "@removed": {
        "reason": "deleted"
      }
    },
    {
      "@odata.type": "#microsoft.graph.message",
      "@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
      "subject": "Holiday hours update",
      "isRead": "true",
      "sender": {
        "emailAddress": {
          "name": "Dana Swope",
          "address": "danas@contoso.com"
        }
      },
      "id": "AAMkADNkNAAASq35xAAA="
    }
  ]
}

Ejemplo 2: Sincronizar mensajes en una carpeta en función del tipo de cambio

En el ejemplo siguiente se muestran solo los mensajes creados en una carpeta específica desde la sincronización inicial. El ejemplo implica 2 rondas de sincronización de esa carpeta que inicialmente contiene 4 mensajes.

La primera ronda implica una serie de 2 solicitudes para sincronizar los 4 mensajes de la carpeta:

Después de la primera ronda, se crean dos mensajes más, se elimina un mensaje y otro se marca como leído.

La segunda ronda de sincronización devuelve solo los cambios en la carpeta del tipo de created cambio (los dos nuevos mensajes creados), sin devolver los demás mensajes que han permanecido iguales, eliminados o actualizados desde la última sincronización.

Solicitud inicial de ejemplo con el tipo de cambio especificado

En este ejemplo, la carpeta especificada se sincroniza por primera vez, por lo que la solicitud de sincronización inicial no incluye ningún token de estado. Esta ronda devuelve todos los mensajes de esa carpeta.

La primera solicitud especifica lo siguiente:

  • Parámetro changeType para devolver solo los mensajes creados en la respuesta delta posterior.
  • Un parámetro $select que devuelva las propiedades subject, sender y isRead de cada mensaje de la respuesta.
  • El encabezado de solicitud opcional, odata.maxpagesize, que devuelve dos mensajes a la vez.
GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?changeType=created&$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2

Respuesta inicial de ejemplo con el tipo de cambio especificado

La respuesta incluye dos mensajes y un encabezado de respuesta @odata.nextLink. La dirección URL @odata.nextLink indica que la carpeta contiene más mensajes que recuperar.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=P4lmXpjPRrjB6haAQzSkpK89jYTVD2kVtOeXNRnfYzPbCs",
    "value": [
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBP\"",
            "subject": "Inline Attachments Again",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LT2fKdhq8oSKEDSVrdi3lRAAIei5gdAAA=",
            "sender": {
                "emailAddress": {
                    "name": "Megan Brown",
                    "address": "Megan.Brown@contoso.com"
                }
            }
        },
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBR\"",
            "subject": "RE: Test Outlook TimeZone",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMKdhq8oSKEDSVrdi3lRAAIei5geAAA=",
            "sender": {
                "emailAddress": {
                    "name": "Megan Brown",
                    "address": "Megan.Brown@contoso.com"
                }
            }
        }
    ]
}

Segunda solicitud de ejemplo con el tipo de cambio especificado

La segunda solicitud especifica la dirección URL @odata.nextLink devuelta de la respuesta anterior. Tenga en cuenta que ya no tiene que especificar el mismo parámetro o el changeType mismo $select que en la solicitud inicial, ya que en skipToken la @odata.nextLink dirección URL lo codifica e incluye.

GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=P4lmXpjPRrjB6haAQzSkpK89jYTVD2kVtOeXNRnfYzPbCs HTTP/1.1
Prefer: odata.maxpagesize=2

Segunda respuesta de ejemplo con el tipo de cambio especificado

La segunda respuesta devuelve los dos mensajes siguientes en la carpeta y @odata.deltaLink la dirección URL que indican que la sincronización está completa por el momento para esta carpeta. Guarde y use la dirección URL @odata.deltaLink para sincronizar la misma carpeta en la siguiente ronda.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$deltatoken=P4lmXpjPRrjB6haAQ_37roqIbjXe66KoV7SMlLH--Jgi8",
    "value": [
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBu\"",
            "subject": "Your preview of the new Briefing email",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBIJ",
            "sender": {
                "emailAddress": {
                    "name": "Cortana",
                    "address": "cortana@contoso.com"
                }
            }
        },
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBw\"",
            "subject": "Char Coding HTML",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBA=",
            "sender": {
                "emailAddress": {
                    "name": "John Doe",
                    "address": "John.Doe@contoso.com"
                }
            }
        }
    ]
}

Sincronizar mensajes en la misma carpeta en la siguiente ronda en función del tipo de cambio especificado

Con desde @odata.deltaLink la última respuesta de la última ronda, solo puede obtener los mensajes que se han agregado a esa carpeta desde entonces. La primera solicitud de la ronda siguiente será similar a la mostrada a continuación, suponiendo que prefiere mantener el mismo tamaño de página máximo en la respuesta:

GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$deltatoken=P4lmXpjPRrjB6haAQ_37roqIbjXe66KoV7SMlLH--Jgi8 HTTP/1.1
Prefer: odata.maxpagesize=2

La respuesta contiene un @odata.deltaLink. Esto indica que todos los cambios de la carpeta de correo remota están ahora sincronizados. Se agregaron dos mensajes desde la última sincronización. Los mensajes actualizados & eliminar desde la última sincronización no se devuelven en esta respuesta diferencial.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=EPuhZPRDHo-r3EBfscYE444fuGSBRV1eXex3JZkLzT9fRM",
    "value": [
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MCP\"",
            "subject": "Nested Attachment",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBIJ",
            "sender": {
                "emailAddress": {
                    "name": "Patti Fernandez",
                    "address": "PattiF@contoso.com"
                }
            }
        },
        {
            "@odata.type": "#microsoft.graph.message",
            "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MCN\"",
            "subject": "Attachment Testing",
            "isRead": true,
            "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwZA=",
            "sender": {
                "emailAddress": {
                    "name": "Patti Fernandez",
                    "address": "PattiF@contoso.com"
                }
            }
        }
    ]
}

Contenido relacionado