Obtenir des identificateurs non modifiables pour des ressources Outlook

Certains éléments Outlook (messages, événements, contacts, tâches) ont un comportement singulier que vous n’avez probablement jamais noté ou qui vous a peut-être considérablement frustré : leurs identificateurs changent. Si ce comportement se produit rarement, uniquement en cas de déplacement, il peut occasionner des problèmes réels pour des applications qui stockent des identifiants hors ligne en vue d’une utilisation ultérieure. Des identificateurs non modifiables permettent à votre application d’obtenir un ID qui ne change pas pendant toute la durée de vie de l’élément.

Notes

Les identificateurs non modifiables, comme tous ceux dans Microsoft Graph, respectent la casse. Gardez ceci à l’esprit lorsque vous comparez des ID.

Mode de fonctionnement

Un ID non modifiable est une fonctionnalité facultative pour Microsoft Graph. Pour l’utiliser, votre application doit envoyer un en-tête HTTP supplémentaire dans vos demandes API :

Prefer: IdType="ImmutableId"

Cet en-tête s’applique uniquement à la demande dans laquelle il est inclus. Si vous souhaitez toujours utiliser des ID non modifiables, vous devez inclure cet en-tête dans chaque demande API.

Durée de vie des ID non modifiables

L’ID non modifiable d’un élément ne change pas tant que celui-ci reste dans la même boîte aux lettres. Cela signifie que l’ID non modifiable ne change PAS si l’élément est déplacé vers un autre dossier dans la boîte aux lettres. En revanche, l’ID non modifiable change dans les cas suivants :

  • L’utilisateur déplace l’élément vers une boîte aux lettres d’archivage.
  • L’utilisateur exporte l’élément (vers un fichier .pst, sous forme de fichier .msg, etc.), puis le réimporte dans sa boîte aux lettres.

Éléments qui prennent en charge les ID non modifiables

Les éléments qui prennent en charge les ID non modifiables sont les suivants :

Les types de conteneur (mailFolder, agenda, etc.) ne prennent pas en charge les ID non modifiables, mais leurs identifiants standard sont déjà constants.

ID non modifiable pour le courrier d’envoi

Vous pouvez utiliser les ID non modifiables pour rechercher un message, une fois qu’il a été envoyé, dans le dossier Éléments envoyés en procédant comme suit :

  1. Créez un brouillon de message à l’aide de Prefer: IdType="ImmutableId"l’en-tête et enregistrezid la propriété du message dans la réponse.
  2. Envoyez le message à l’aide de l’ID de l’étape précédente.
  3. Obtenez le message à l’aide de l’ID de la première étape. Il s’agit de la copie dans les Éléments envoyés.

Notes

L’obtention du message dans les Éléments envoyés peut échouer immédiatement après l’envoi du message. La copie du message n’est pas créée tant que le message n’a pas été envoyé, ce qui peut prendre du temps.

ID non modifiable avec notifications de modification

Vous pouvez demander que Microsoft Graph envoie des ID non modifiables dans des notifications de modification en incluant l’en-tête Prefer: IdType="ImmutableId" lors de la création d’un abonnement. Les abonnements existants créés sans l’en-tête continueront à utiliser le format d’ID par défaut. Pour faire en sorte que des abonnements existants utilisent des ID non modifiables, vous devez le supprimer, puis les recréer à l’aide de l’en-tête.

ID non modifiable avec requête delta

Vous pouvez demander que Microsoft Graph retourne des ID non modifiables dans des réponses de requête delta pour les types de ressources pris en charge en incluant l’en-tête Prefer: IdType="ImmutableId". Les valeurs @odata.nextLink et @odata.deltaLink retournées par des requêtes delta étant compatibles avec les deux formats d’ID, votre application n’a pas besoin de se resynchroniser pour tirer parti d’un ID non modifiable. Vous pouvez dorénavant utiliser l’en-tête pour obtenir des ID non modifiables, et mettre à jour le stockage de votre application séparément.

Mise à jour de données existantes

Si vous disposez d’une base de données contenant des milliers d’identifiants standard, vous pouvez convertir ceux-ci dans un format non modifiable à l’aide de la fonction translateExchangeIds. Vous pouvez fournir un tableau de jusqu’à 1 000 à convertir dans un format cible.

Notes

Vous pouvez également utiliser translateExchangeIds pour migrer des applications de services web Exchange vers Microsoft Graph.

Exemple

L’exemple suivant convertit un ID Graph normal en ID Graph non modifiable.

Demande

POST https://graph.microsoft.com/v1.0/me/translateExchangeIds

{
  "inputIds" :
  [
    "AQMkAGM2…"
  ],
  "targetIdType" : "restImmutableEntryId",
  "sourceIdType" : "restId"
}

Réponse

HTTP 200 OK

{
  "value": [
    {
      "targetId": "AAkALgAA...",
      "sourceId": "AQMkAGM2..."
    }
  ]
}