Obtenir des identificateurs immuables pour les ressources Outlook

  • Article

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. Les identificateurs immuables (ID) permettent à votre application d’obtenir un ID qui ne change pas pendant la durée de vie de l’élément.

Remarque

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 immuables

L’ID immuable d’un élément ne change pas tant que l’élément 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. Toutefois, l’ID immuable change si :

  • 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 immuables

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

Les types de conteneurs (mailFolder, calendar, etc.) ne prennent pas en charge l’ID immuable, mais leurs ID standard étaient 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.

Remarque

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 continuent d’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 @odata.nextLink valeurs et @odata.deltaLink retournées par les requêtes delta étant compatibles avec les deux formats d’ID, votre application n’a pas besoin de se resynchroniser pour tirer parti de l’ID immuable. 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.

Remarque

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

Exemple

L’exemple suivant traduit un ID de Microsoft Graph normal en ID de Microsoft Graph immuable.

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..."
    }
  ]
}