Obtenir des modifications incrémentielles de messages dans un dossierGet incremental changes to messages in a folder

La requête delta vous permet d’effectuer une requête pour des ajouts, suppressions ou mises à jour de messages, au moyen d’une série d’appels de fonction delta. Les données de la requête delta vous permettent de mettre à jour et de synchroniser une collection locale des messages d’un utilisateur, sans avoir à récupérer l’ensemble des messages de l’utilisateur depuis le serveur.Delta query lets you query for additions, deletions, or updates to messages in a folder, by way of a series of delta function calls. Delta data enables you to maintain and synchronize a local store of a user's messages, without having to fetch the entire set of the user's messages from the server every time.

La requête delta s’occupe à la fois de la synchronisation complète qui récupère tous les messages dans un dossier (par exemple, la boîte de réception de l’utilisateur), et de la synchronisation incrémentielle qui récupère tous les messages ayant été modifiés depuis la dernière synchronisation. En règle générale, il est préférable d’effectuer une première synchronisation complète de tous les messages dans un dossier, puis d’apporter régulièrement des modifications incrémentielles à ce dossier.Delta query supports both full synchronization that retrieves all of the messages in a folder (for example, the user's Inbox), and incremental synchronization that retrieves all of the messages that have changed in that folder since the last synchronization. Typically, you would do an initial full synchronization of all the messages in a folder, and subsequently, get incremental changes to that folder periodically.

Suivi des modifications de message dans un dossierTrack message changes in a folder

La requête delta est une opération par dossier. Pour suivre les modifications des messages dans une hiérarchie de dossiers, vous devez effectuer le suivi de chaque dossier individuellement.Delta query is a per-folder operation. To track the changes of the messages in a folder hierarchy, you need to track each folder individually.

Le suivi des modifications apportées aux messages dans un dossier de courrier électronique correspond généralement à une série de requêtes GET envoyées avec la fonction delta. La première requête GET ressemble beaucoup à la façon dont vous obtenez des messages, sauf que vous incluez la fonction delta :Tracking message changes in a mail folder typically is a round of one or more GET requests with the delta function. The initial GET request is very much like the way you get messages, except that you include the delta function:

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

Une requête GET avec la fonction delta renvoie, soit :A GET request with the delta function returns either:

  • nextLink (qui contient une URL avec un appel de la fonction delta et un jeton skipToken), soitA nextLink (that contains a URL with a delta function call and a skipToken), or
  • deltaLink (qui contient une URL avec un appel de la fonction delta et un jeton deltaToken).A deltaLink (that contains a URL with a delta function call and deltaToken).

Ces jetons d’état sont complètement opaques pour le client. Pour réaliser une première série de suivis des modifications, copiez et appliquez l’URL renvoyée par la dernière requête GET à l’autre appel de la fonction delta pour le même dossier. Si deltaLink est renvoyé, la série de suivis des modifications en cours est terminée. Vous pouvez enregistrer et utiliser l’URL deltaLink quand vous lancez la série de suivis suivante.These tokens are state tokens that are completely opaque to the client. To proceed with a round of change tracking, simply copy and apply the URL returned from the last GET request to the next delta function call for the same folder. A deltaLink returned in a response signifies that the current round of change tracking is complete. You can save and use the deltaLink URL when you begin the next round.

Consultez l’exemple ci-dessous pour savoir comment utiliser les URL nextLink et deltaLink.See the example below to learn how to use the nextLink and deltaLink URLs.

Utilisation des paramètres de requête dans une requête delta pour des messagesUse query parameters in a delta query for messages

  • Vous pouvez utiliser un paramètre de requête $select comme dans toute requête GET pour spécifier uniquement les propriétés dont vous avez besoin pour de meilleures performances. La propriété id est toujours renvoyée.You can use a $select query parameter as in any GET request to specify only the properties your need for best performance. The id property is always returned.
  • La requête delta prend en charge $select, $top et $expand pour les messages.Delta query support $select, $top, and $expand for messages.
  • Pour $filter et $orderby, la prise en charge est limitée :There is limited support for $filter and $orderby:
    • Les seules expressions $filter prises en charge sont $filter=receivedDateTime+ge+{value} ou $filter=receivedDateTime+gt+{value}.The only supported $filter expressions are $filter=receivedDateTime+ge+{value} or $filter=receivedDateTime+gt+{value}.
    • L’application de $filter dans une requête Delta renvoie seulement 5 000 messages maximum.Applying $filter in a delta query returns only up to 5,000 messages.
    • La seule expression $orderby prise en charge est $orderby=receivedDateTime+desc. Si vous n’incluez pas d’expression $orderby, l’ordre de renvoi n’est pas garanti.The only supported $orderby expression is $orderby=receivedDateTime+desc. If you do not include an $orderby expression, the return order is not guaranteed.
  • $search n’est pas pris en charge.There is no support for $search.

En-tête de requête facultatifOptional request header

Chaque requête GET effectuée avec la fonction delta renvoie une collection d’un ou de plusieurs messages dans la réponse.Each delta query GET request returns a collection of one or more messages in the response. Vous pouvez spécifier l’en-tête de la requête, Prefer: odata.maxpagesize={x}, pour définir le nombre maximal de messages à inclure dans une réponse.You can optionally specify the request header, Prefer: odata.maxpagesize={x}, to set the maximum number of messages in a response.

Exemple pour synchroniser des messages dans un dossierExample to synchronize messages in a folder

L’exemple suivant montre 2 séries de synchronisation d’un dossier spécifique qui contient initialement 5 messages.The following example shows 2 rounds of synchronization of a specific folder which initially contains 5 messages.

La première série comprend un ensemble de 3 requêtes pour synchroniser les 5 messages du dossier :The first round involves a series of 3 requests to synchronize all 5 messages in the folder:

Après la première série, l’un des messages est supprimé et un autre est marqué comme lu.After the first round, one of the messages is deleted, and another is marked as read. La deuxième série de synchronisation renvoie uniquement la fonction delta (suppression et mise à jour), sans renvoyer les autres messages restés identiques.The second round of synchronization returns only the delta (the deletion and update), without returning the other messages that have remained the same.

Exemple de première requêteSample initial request

Dans cet exemple, le dossier spécifié est synchronisé pour la première fois, c’est pourquoi la synchronisation initiale ne contient aucun jeton d’état. Cette série renvoie tous les messages figurant dans ce dossier.In this example, the specified folder is being synchronized for the first time, so the initial sync request does not include any state token. This round will return all the messages in that folder.

La première requête comprend les éléments suivants :The first request specifies the following:

  • Un paramètre $select pour renvoyer les propriétés subject, sender et isRead de chaque message dans la réponse.A $select parameter to return the subject, sender, and isRead properties for each message in the response.
  • L’en-tête de requête facultatif, odata.maxpagesize, qui renvoie deux messages à la fois.The optional request header, odata.maxpagesize, returning 2 messages at a time.
GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2

Exemple de première réponseSample initial response

La réponse comprend deux messages et un en-tête de réponse @odata.nextLink. L’URL nextLink indique qu’il n’y a plus de messages à récupérer dans le dossier.The response includes two messages and an @odata.nextLink response header. The nextLink URL indicates there are more messages in the folder to get.

{
  "@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.onmicrosoft.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.onmicrosoft.com"
        }
      },
      "id": "AQMkADNkNAAAVRMKAAAAA=="
    }
  ]
}

Exemple de deuxième requêteSample second request

La deuxième requête comprend l’URL nextLink renvoyée par la réponse précédente. Notez qu’il est inutile de repréciser le paramètre $select, puisque le skipToken dans l’URL nextLink le code et l’inclut.The second request specifies the nextLink URL returned from the previous response. Notice that it no longer has to specify the same $select parameter as in the initial request, as the skipToken in the nextLink URL encodes and includes it.

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

Exemple de deuxième réponseSample second response

La deuxième réponse renvoie les 2 messages suivants dans e dossier et un autre nextLink, indiquant qu’il est possible de récupérer d’autres messages dans le dossier.The second response returns the next 2 messages in the folder and another nextLink, indicating there are more messages to get from the folder.

{
  "@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.onmicrosoft.com"
        }
      },
      "id": "AQMkADNkNAAAgWJAAAA"
    }
  ]
}

Exemple de troisième requêteSample third request

La troisième requête continue d’utiliser la dernière URL nextLink renvoyée par la dernière requête de synchronisation.The third request continues to use the latest nextLink URL returned from the last sync request.

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

Exemple de troisième et dernière réponseSample third and final response

La troisième réponse renvoie le dernier message restant dans le dossier et une URL deltaLink indiquant que la synchronisation de ce dossier est terminée pour le moment. Enregistrez et utilisez l’URL deltaLink pour synchroniser le même dossier lors de la prochaine série.The third response returns the only remaining message in the folder, and a deltaLink URL which indicates synchronization is complete for the time being for this folder. Save and use the deltaLink URL to synchronize the same folder in the next round.

{
  "@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="
    }
  ]
}

Synchroniser les messages dans le même dossier lors de la série suivanteSynchronize messages in the same folder in the next round

En utilisant l’URL deltaLink renvoyée par la dernière requête de la série précédente, vous pouvez récupérer uniquement les messages qui ont été ajoutés, supprimés ou mis à jour dans ce dossier. Voici à quoi ressemblera la première requête de cette deuxième série de suivis, à condition que vous conserviez le même format de page maximal dans la réponse :Using the deltaLink from the last request in the last round, you will be able to get only those messages that have changed (by being added, deleted, or updated) in that folder since then. Your first request in the next round will look like the following, assuming you prefer to keep the same maximum page size in the response:

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

La réponse contient un deltaLink.The response contains a deltaLink. Cela indique que toutes les modifications apportées dans le dossier de messagerie distant sont désormais synchronisées.This indicates that all changes in the remote mail folder are now synchronized. Un message a été supprimé et l’autre message a été modifié.One message was deleted and the other message was changed.

{
  "@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.onmicrosoft.com"
        }
      },
      "id": "AAMkADNkNAAASq35xAAA="
    }
  ]
}

Voir aussiSee also