message: delta

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Obtenez un ensemble de messages ajoutés, supprimés ou mis à jour dans un dossier spécifié.

Un appel de fonction delta pour les messages dans un dossier est similaire à une demande GET, sauf qu’en appliquant correctement des jetons d’état dans un ou plusieurs de ces appels, vous pouvez demander des modifications incrémentielles dans les messages de ce dossier. L’utilisation de deltas vous permet de maintenir et de synchroniser progressivement un magasin local des messages d’un utilisateur.

Cette API est disponible dans les déploiements cloud nationaux suivants.

Service global Gouvernement américain L4 Gouvernement américain L5 (DOD) Chine exploitée par 21Vianet
✅ ✅ ✅ ✅

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme étant les moins privilégiées pour cette API. Utilisez une ou plusieurs autorisations privilégiées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, voir Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez la référence des autorisations.

Type d’autorisation Autorisations les moins privilégiées Autorisations à privilèges plus élevés
Déléguée (compte professionnel ou scolaire) Mail.ReadBasic Mail.Read, Mail.ReadWrite
Déléguée (compte Microsoft personnel) Mail.ReadBasic Mail.Read, Mail.ReadWrite
Application Mail.ReadBasic.All Mail.Read, Mail.ReadWrite

Requête HTTP

Pour obtenir toutes les modifications apportées aux messages dans le mailFolder spécifié :

GET /me/mailFolders/{id}/messages/delta
GET /users/{id}/mailFolders/{id}/messages/delta

Pour obtenir uniquement les messages créés, mis à jour ou supprimés dans le dossier mailFolder spécifié :

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

Paramètres de requête

Le suivi des modifications dans les messages entraîne une série d’un ou plusieurs appels de fonction delta . Si vous utilisez une option de requête système OData ou l’option de requête personnalisée, changeTypevous devez la spécifier dans la demande delta initiale. Microsoft Graph code automatiquement les paramètres spécifiés dans la partie jeton du @odata.nextLink ou de l’URL @odata.deltaLink fournie dans la réponse. Il vous suffit de spécifier les paramètres de requête de votre choix la première fois. Dans les demandes suivantes, copiez et appliquez simplement l’URL @odata.nextLink@odata.deltaLink ou de la réponse précédente, car cette URL inclut déjà les paramètres souhaités encodés.

Paramètre de requête Type Description
$deltatoken string Jeton d’état renvoyé dans l’URL @odata.deltaLink de l’appel de fonction delta précédent pour la même collection de messages, indiquant la fin de ce cycle de suivi des modifications. Enregistrez et appliquez l’ensemble de l’URL @odata.deltaLink, y compris ce jeton dans la première requête de la série suivante de suivi des modifications pour cette collection.
$skiptoken string Jeton d’état renvoyé dans l’URL @odata.nextLink de l’appel de fonction delta précédent, indiquant que des modifications supplémentaires doivent être suivies dans la même collection de messages.
changeType string Option de requête personnalisée permettant de filtrer la réponse delta en fonction du type de modification. Les valeurs prises en charge sont created, updated, ou deleted.

Paramètres de requête OData

  • 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.
  • La requête delta prend en charge $select, $top et $expand pour les messages.
  • La prise en charge est limitée pour $filter et $orderby:
    • Les seules expressions $filter prises en charge sont $filter=receivedDateTime+ge+{value} ou $filter=receivedDateTime+gt+{value}.
    • 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.
  • Il n’y a pas de prise en charge pour $search.

Remarque

Les requêtes delta pour les messages peuvent renvoyer des événements de modification qui ne correspondent pas aux conditions de filtre spécifiées dans la requête initiale.
Cela comprend :

  • @removed entrées avec "reason": "deleted" le moment où un élément est supprimé ou déplacé du dossier.
  • Changements d’état Lu/Non lu.

Ces événements ne proviennent pas de modifications apportées au message lui-même. Ils sont émis dans le cadre du processus de synchronisation au niveau dossier sur lequel s’appuient les jetons delta.
Le suivi delta fonctionne au niveau de la collecte , et non au niveau du message, et ces événements ne sont donc pas filtrés.

Les clients doivent être prêts à traiter ces entrées afin de maintenir une vue locale précise et entièrement synchronisée de la collection de messages.

En-têtes de demande

Nom Type Description
Autorisation string Porteur {token}. Obligatoire. En savoir plus sur l’authentification et les autorisations.
Content-Type string application/json. Obligatoire.
Préférence chaîne odata.maxpagesize={x}. Facultatif.

Réponse

Si elle réussit, cette méthode renvoie un code de réponse 200 OK et un objet de la collection message dans le corps de la réponse.

Exemple

Demande

L’exemple suivant montre comment effectuer un seul appel de fonction delta et limiter le nombre maximal de messages dans le corps de réponse à 2.

Pour suivre les modifications dans les messages dans un dossier, vous devez effectuer un ou plusieurs appels de fonction delta pour obtenir l’ensemble des modifications incrémentielles depuis la dernière requête delta. Pour obtenir un exemple illustrant une série d’appels de requête delta, consultez la section Obtenir des modifications incrémentielles apportées aux messages dans un dossier.

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

Prefer: odata.maxpagesize=2

Réponse

Si la demande réussit, la réponse inclura un jeton d’état, qui est soit un skipToken (dans un en-tête de réponse @odata.nextLink ), soit un deltaToken (dans un en-tête de réponse @odata.deltaLink ). Respectivement, ils indiquent si vous devez continuer le tour ou si vous avez fini d’obtenir tous les changements pour ce tour.

La réponse suivante montre un skipToken dans un en-tête de réponse @odata.nextLink .

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.nextLink":"https://graph.microsoft.com/beta/me/mailFolders/{id}/messages/delta?$skiptoken={_skipToken_}",
  "value": [
    {
      "receivedDateTime": "datetime-value",
      "sentDateTime": "datetime-value",
      "hasAttachments": true,
      "internetMessageId": "internetMessageId-value",
      "subject": "subject-value",
      "body": {
        "contentType": "contentType-value",
        "content": "content-value"
      }
    }
  ]
}

Contenu connexe

  • Last updated on