Partager via

Obtenir des modifications incrémentielles de messages dans un dossier

  • Article

La requête delta vous permet d’interroger les ajouts, suppressions ou mises à jour des messages d’un dossier par le biais d’une série d’appels de fonction delta . Les données delta vous permettent de maintenir et de synchroniser un stockage local des messages d'un utilisateur sans avoir à aller chercher l'ensemble des messages de l'utilisateur sur le serveur à chaque fois.

La synchronisation des éléments de message dans un magasin local peut utiliser la requête delta pour la synchronisation complète initiale et les synchronisations incrémentielles suivantes. En règle générale, vous effectuez une synchronisation complète initiale de tous les messages d’un dossier (par exemple, la boîte de réception de l’utilisateur), puis obtenez régulièrement des modifications incrémentielles dans ce dossier.

Pour obtenir des modifications incrémentielles d’un type spécifique uniquement (messages créés, mis à jour ou supprimés depuis la synchronisation initiale), effectuez une série initiale de synchronisation de tous les messages dans le dossier, puis obtenez les modifications incrémentielles d’un type spécifique souhaité dans les cycles suivants. Spécifiez le type de modification souhaité en tant qu’option de requête dans la demande delta initiale ; Microsoft Graph encode automatiquement toutes les options de requête OData et personnalisées dans ou @odata.nextLink@odata.deltaLink fournies dans la réponse.

Suivi des modifications de message dans un dossier

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.

Le suivi des modifications de message dans un dossier de messagerie est généralement une série d’une ou plusieurs requêtes GET avec la fonction delta . La requête GET initiale est très semblable à la façon dont vous recevez les messages, sauf que vous incluez la fonction delta :

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

Une requête GET avec la fonction delta renvoie, soit :

  • @odata.nextLink (qui contient une URL avec un appel de la fonction delta et un jeton skipToken), soit
  • @odata.deltaLink (qui contient une URL avec un appel de la fonction delta et un jeton deltaToken).

Ces jetons sont des jetons d’état opaques pour le client. Pour poursuivre une série de suivi des modifications, copiez et appliquez l’URL retournée à partir de la dernière requête GET à l’appel de fonction delta suivant pour le même dossier. Si @odata.deltaLink est renvoyé, la série de suivis des modifications en cours est terminée. Vous pouvez enregistrer et utiliser l’URL @odata.deltaLink quand vous lancez la série de suivis suivante.

Le reste de cet article comprend 2 exemples :

  • Consultez l’exemple 1 pour savoir comment utiliser les @odata.nextLink URL et @odata.deltaLink .
  • Consultez l’exemple 2 pour savoir comment obtenir de manière incrémentielle uniquement les messages créés depuis la ronde initiale.

Utilisation des paramètres de requête dans une requête delta pour des 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 id propriété est toujours retournée.
  • La requête delta prend en charge $select, $top et $expand pour les messages.
  • Pour $filter et $orderby, la prise en charge est limitée :
    • Les seules expressions $filter prises en charge sont $filter=receivedDateTime+ge+{value} ou $filter=receivedDateTime+gt+{value}.
    • L’application de $filter dans une requête Delta renvoie seulement 5 000 messages maximum.
    • La seule expression $orderby prise en charge est $orderby=receivedDateTime+desc. Si vous n’incluez pas d’expression $orderby , l’ordre de retour n’est pas garanti.
  • $search n’est pas pris en charge.

En outre, pour retourner uniquement certains types de modifications (créées, mises à jour ou supprimées) dans la réponse de la requête delta, vous pouvez éventuellement filtrer le type de modification souhaité à l’aide d’une option changeTypede requête personnalisée . Les valeurs possibles sont created, updated ou 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

En-tête de requête facultatif

Chaque requête GET effectuée avec la fonction delta renvoie une collection d’un ou de plusieurs messages dans la réponse. 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.

Exemple 1 : synchroniser des messages dans un dossier

L’exemple suivant montre 2 séries de synchronisation d’un dossier spécifique qui contient initialement 5 messages.

La première série comprend un ensemble de 3 requêtes pour synchroniser les 5 messages du dossier :

Après la première série, l’un des messages est supprimé et un autre est marqué comme lu. La deuxième série de synchronisation renvoie uniquement la fonction delta (suppression et mise à jour), sans renvoyer les autres messages restés identiques.

Exemple de première requête

Dans cet exemple, le dossier spécifié est synchronisé pour la première fois, de sorte que la demande de synchronisation initiale n’inclut aucun jeton d’état. Cette ronde retourne tous les messages de ce dossier.

La première requête comprend les éléments suivants :

  • Un paramètre $select pour renvoyer les propriétés subject, sender et isRead de chaque message dans la réponse.
  • L’en-tête de requête facultatif, odata.maxpagesize, qui renvoie deux messages à la fois.
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éponse

La réponse comprend deux messages et un en-tête de réponse @odata.nextLink. L’URL @odata.nextLink indique qu’il n’y a plus de messages à récupérer dans le dossier.

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

Exemple de deuxième requête

La deuxième requête comprend l’URL @odata.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 @odata.nextLink le code et l’inclut.

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éponse

La deuxième réponse renvoie les 2 messages suivants dans e dossier et un autre @odata.nextLink, indiquant qu’il est possible de récupérer d’autres messages dans le dossier.

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

Exemple de troisième requête

La troisième requête continue d’utiliser la dernière URL @odata.nextLink renvoyée par la dernière requête de synchronisation.

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éponse

La troisième réponse retourne le seul message restant dans le dossier et une @odata.deltaLink URL qui indique que la synchronisation est terminée pour le moment pour ce dossier. Enregistrez et utilisez l’URL @odata.deltaLink pour synchroniser le même dossier lors de la prochaine série.

{
  "@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 suivante

À l’aide @odata.deltaLink de la dernière requête de la dernière ronde, vous pouvez obtenir uniquement les messages qui ont été modifiés (en étant ajoutés, supprimés ou mis à jour) dans ce dossier depuis lors. 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 :

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 @odata.deltaLink. Cela indique que toutes les modifications apportées dans le dossier de messagerie distant sont désormais synchronisées. Un message a été supprimé et l’autre message a été modifié.

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

Exemple 2 : Synchroniser les messages dans un dossier en fonction du type de modification

L’exemple suivant montre comment obtenir uniquement les messages créés dans un dossier spécifique depuis la synchronisation initiale. L’exemple implique 2 cycles de synchronisation de ce dossier qui contient initialement 4 messages.

La première ronde implique une série de 2 demandes pour synchroniser les 4 messages dans le dossier :

Après la première ronde, deux autres messages sont créés, un message est supprimé et un autre est marqué comme lu.

La deuxième série de synchronisation retourne uniquement les modifications dans le dossier du type de created modification (les deux nouveaux messages créés), sans retourner les autres messages qui sont restés les mêmes, supprimés ou mis à jour depuis la dernière synchronisation.

Exemple de requête initiale avec le type de modification spécifié

Dans cet exemple, le dossier spécifié est synchronisé pour la première fois, de sorte que la demande de synchronisation initiale n’inclut aucun jeton d’état. Cette ronde retourne tous les messages de ce dossier.

La première requête comprend les éléments suivants :

  • Paramètre changeType pour retourner uniquement les messages créés dans la réponse delta suivante.
  • Un paramètre $select pour renvoyer les propriétés subject, sender et isRead de chaque message dans la réponse.
  • L’en-tête de requête facultatif, odata.maxpagesize, qui renvoie deux messages à la fois.
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

Exemple de réponse initiale avec le type de modification spécifié

La réponse comprend deux messages et un en-tête de réponse @odata.nextLink. L’URL @odata.nextLink indique qu’il n’y a plus de messages à récupérer dans le dossier.

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

Exemple de deuxième requête avec le type de modification spécifié

La deuxième requête comprend l’URL @odata.nextLink renvoyée par la réponse précédente. Notez qu’il n’a plus besoin de spécifier le même ou le changeType paramètre $select que dans la requête initiale, car le skipToken dans l’URL @odata.nextLink l’encode et l’inclut.

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

Exemple de deuxième réponse avec le type de modification spécifié

La deuxième réponse retourne les 2 messages suivants dans le dossier et @odata.deltaLink l’URL qui indiquent que la synchronisation est terminée pour le moment pour ce dossier. Enregistrez et utilisez l’URL @odata.deltaLink pour synchroniser le même dossier lors de la prochaine série.

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

Synchroniser les messages dans le même dossier dans la ronde suivante en fonction du type de modification spécifié

À l’aide @odata.deltaLink de la dernière réponse de la dernière ronde, vous pouvez obtenir uniquement les messages qui ont été ajoutés dans ce dossier depuis lors. 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 :

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

La réponse contient un @odata.deltaLink. Cela indique que toutes les modifications apportées dans le dossier de messagerie distant sont désormais synchronisées. Deux messages ont été ajoutés depuis la dernière synchronisation. Les messages mis à jour & supprimés depuis la dernière synchronisation ne sont pas retournés dans cette réponse delta.

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

Contenu connexe