Obtenir des identificateurs non modifiables pour des ressources OutlookGet immutable identifiers for Outlook resources

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.Outlook items (messages, events, contacts, tasks) have an interesting behavior that you've probably either never noticed or has caused you significant frustration: their IDs change. 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.It doesn't happen often, only if the item is moved, but it can cause real problems for apps that store IDs offline for later use. 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.Immutable identifiers enables your application to obtain an ID that does not change for the lifetime of the item.

Notes

Les identificateurs non modifiables, comme tous ceux dans Microsoft Graph, respectent la casse.Immutable identifiers, like all identifiers in Microsoft Graph, are case-sensitive. Gardez ceci à l’esprit lorsque vous comparez des ID.Keep this in mind if you are comparing IDs.

Mode de fonctionnementHow it works

Un ID non modifiable est une fonctionnalité facultative pour Microsoft Graph.Immutable ID is an optional feature for Microsoft Graph. Pour l’utiliser, votre application doit envoyer un en-tête HTTP supplémentaire dans vos demandes API :To opt in, your application needs to send an additional HTTP header in your API requests:

Prefer: IdType="ImmutableId"

Cet en-tête s’applique uniquement à la demande dans laquelle il est inclus.This header only applies to the request it is included with. Si vous souhaitez toujours utiliser des ID non modifiables, vous devez inclure cet en-tête dans chaque demande API.If you want to always use immutable IDs, you must include this header with every API request.

Durée de vie des ID non modifiablesLifetime of Immutable IDs

L’ID non modifiable d’un élément ne change pas tant que celui-ci reste dans la même boîte aux lettres.An item's immutable ID will not change so long as the item stays in the same mailbox. 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.That means that immutable ID will NOT change if the item is moved to a different folder in the mailbox. En revanche, l’ID non modifiable change dans les cas suivants :However, the immutable ID will change if:

  • L’utilisateur déplace l’élément vers une boîte aux lettres d’archivage.The user moves the item to an archive mailbox.
  • 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.The user exports the item (to a PST, as an MSG file, etc.) and re-imports it into their mailbox.

Éléments qui prennent en charge les ID non modifiablesItems that support immutable ID

Les éléments qui prennent en charge les ID non modifiables sont les suivants :The following items support immutable IDs:

Les types de conteneur (mailFolder, agenda, etc.) ne prennent pas en charge les ID non modifiables, mais leurs identifiants standard sont déjà constants.Container types (mailFolder, calendar, etc.) do not support immutable ID, but their regular IDs were already constant.

ID non modifiable pour le courrier d’envoiImmutable ID with sending mail

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 :You can use immutable IDs to find a message in the Sent Items folder after it has been sent, using the following steps:

  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.Create a draft message using the Prefer: IdType="ImmutableId" header and save the id property of the message in the response.
  2. Envoyez le message à l’aide de l’ID de l’étape précédente.Send the message using the ID from the previous step.
  3. Obtenez le message à l’aide de l’ID de la première étape.Get the message using the ID from the first step. Il s’agit de la copie dans les Éléments envoyés.This is the copy in Sent Items.

Notes

L’obtention du message dans les Éléments envoyés peut échouer immédiatement après l’envoi du message.Getting the message in Sent Items may not succeed immediately after sending the 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.The copy of the message is not created until the message successfully sends, which may take time.

ID non modifiable avec notifications de modificationImmutable ID with change notifications

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.You can request that Microsoft Graph send immutable IDs in change notifications by including the Prefer: IdType="ImmutableId" header when creating a subscription. Les abonnements existants créés sans l’en-tête continueront à utiliser le format d’ID par défaut.Existing subscriptions created without the header will continue to use the default ID format. 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.In order to switch existing subscriptions to use immutable IDs, you must delete and recreate them using the header.

ID non modifiable avec requête deltaImmutable ID with delta query

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".You can request that Microsoft Graph return immutable IDs in delta query responses for supported resource types by including the Prefer: IdType="ImmutableId" header. Les valeurs nextLink et 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.The nextLink and deltaLink values returned by delta queries are compatible with both ID formats, so your application does not need to re-synchronize to take advantage of immutable ID. 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.You can use the header to get immutable IDs going forward, and you can update your app's storage separately.

Mise à jour de données existantesUpdating existing data

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.If you've already got a database filled with thousands of regular IDs, you can migrate those IDs to immutable format using the translateExchangeIds function. Vous pouvez fournir un tableau de jusqu’à 1 000 à convertir dans un format cible.You can provide an array of up to 1000 IDs to be translated into a target format.

Notes

Vous pouvez également utiliser translateExchangeIds pour migrer des applications de services web Exchange vers Microsoft Graph.You can also use translateExchangeIds to migrate Exchange Web Services applications to Microsoft Graph.

ExempleExample

L’exemple suivant convertit un ID Graph normal en ID Graph non modifiable.The following example translates a normal Graph ID to an immutable Graph ID.

DemandeRequest

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

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

RéponseResponse

HTTP 200 OK

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