Obtener identificadores inmutables para recursos de OutlookGet immutable identifiers for Outlook resources

Los elementos de Outlook (mensajes, eventos, contactos, tareas) tienen un comportamiento interesante que probablemente no ha observado nunca o le ha provocado gran frustración: el cambio de ID.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. No sucede con frecuencia, solo si se mueve el elemento, pero puede provocar problemas reales para las aplicaciones que almacenan identificadores sin conexión para su uso posterior.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. Los identificadores inmutables permiten que la aplicación obtenga un ID que no cambia durante toda la duración del elemento.Immutable identifiers enables your application to obtain an ID that does not change for the lifetime of the item.

Nota

Los identificadores inmutables, como todos los identificadores de Microsoft Graph, distinguen mayúsculas de minúsculas.Immutable identifiers, like all identifiers in Microsoft Graph, are case-sensitive. Tenga esto en cuenta si compara ID.Keep this in mind if you are comparing IDs.

Cómo funcionaHow it works

El Identificador inmutable es una característica opcional de Microsoft Graph.Immutable ID is an optional feature for Microsoft Graph. Para habilitarla, la aplicación debe enviar un encabezado HTTP adicional en sus solicitudes de API:To opt in, your application needs to send an additional HTTP header in your API requests:

Prefer: IdType="ImmutableId"

Este encabezado solo se aplica a la solicitud en la que está incluido.This header only applies to the request it is included with. Si quiere usar siempre identificadores inmutables, debe incluir este encabezado en cada solicitud de API.If you want to always use immutable IDs, you must include this header with every API request.

Duración de los ID inmutablesLifetime of Immutable IDs

Un identificador inmutable de un elemento no cambiará siempre y cuando el elemento permanece en el mismo buzón.An item's immutable ID will not change so long as the item stays in the same mailbox. Eso significa que el identificador inmutable no cambiará si el elemento se mueve a otra carpeta del buzón.That means that immutable ID will NOT change if the item is moved to a different folder in the mailbox. Pero, el identificador inmutable cambiará si:However, the immutable ID will change if:

  • El usuario mueve el elemento a un buzón de archivo.The user moves the item to an archive mailbox.
  • El usuario exporta el elemento (a un archivo PST, como un archivo MSG, etc.) y vuelve a importarlo a su buzón.The user exports the item (to a PST, as an MSG file, etc.) and re-imports it into their mailbox.

Elementos que admiten el identificador inmutableItems that support immutable ID

Los siguientes elementos admiten los identificadores inmutables:The following items support immutable IDs:

Los tipos de contenedor (mailFolder, calendario, etc.) no admiten los identificadores inmutables, pero sus identificadores normales ya eran constantes.Container types (mailFolder, calendar, etc.) do not support immutable ID, but their regular IDs were already constant.

Identificador inmutable con el envío de correoImmutable ID with sending mail

Puede usar identificadores inmutables para buscar un mensaje en la carpeta Elementos enviados después de que se haya enviado, siguiendo estos pasos:You can use immutable IDs to find a message in the Sent Items folder after it has been sent, using the following steps:

  1. Cree un borrador de mensaje con el encabezado Prefer: IdType="ImmutableId" y guarde la propiedad id del mensaje en la respuesta.Create a draft message using the Prefer: IdType="ImmutableId" header and save the id property of the message in the response.
  2. Envíe el mensaje con el ID. del paso anterior.Send the message using the ID from the previous step.
  3. Obtenga el mensaje con el ID. del primer paso.Get the message using the ID from the first step. Esta es la copia en Elementos enviados.This is the copy in Sent Items.

Nota

Es posible que la aparición del mensaje en Elementos enviados no se realice inmediatamente después de enviar el mensaje.Getting the message in Sent Items may not succeed immediately after sending the message. La copia del mensaje no se crea hasta que el mensaje se envía correctamente, lo que puede tardar algún tiempo.The copy of the message is not created until the message successfully sends, which may take time.

El identificador inmutable con las notificaciones de cambiosImmutable ID with change notifications

Puede solicitar que Microsoft Graph envíe ID inmutables en las notificaciones de cambios incluyendo el encabezado Prefer: IdType="ImmutableId" al crear una suscripción.You can request that Microsoft Graph send immutable IDs in change notifications by including the Prefer: IdType="ImmutableId" header when creating a subscription. Las suscripciones existentes creadas sin el encabezado seguirán usando el formato ID predeterminado.Existing subscriptions created without the header will continue to use the default ID format. Para pasar de una suscripción existente a usar identificadores inmutables, debe eliminarlos y volver a crearlos con el encabezado.In order to switch existing subscriptions to use immutable IDs, you must delete and recreate them using the header.

El identificador inmutable con consulta deltaImmutable ID with delta query

Puede solicitar que Microsoft Graph devuelva identificadores inmutables en respuestas de consultas delta para los tipos de recursos admitidos, incluyendo el encabezado 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. Los valores nextLink y deltaLink devueltos por las consultas de delta son compatibles con ambos formatos ID, por lo que no es necesario volver a sincronizar la aplicación para aprovechar del ID inmutable.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. Puede usar el encabezado para obtener los identificadores inmutables en el futuro y puede actualizar el almacenamiento de la aplicación por separado.You can use the header to get immutable IDs going forward, and you can update your app's storage separately.

Actualizar los datos existentesUpdating existing data

Si ya tiene una base de datos con miles de identificadores normales, puede migrar esos ID para usar el formato inmutable con la función 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. Puede proporcionar una matriz de hasta 1000 identificadores para convertir en un formato de destino.You can provide an array of up to 1000 IDs to be translated into a target format.

Nota

También puede usar translateExchangeIds para migrar aplicaciones de servicios Web Exchange a Microsoft Graph.You can also use translateExchangeIds to migrate Exchange Web Services applications to Microsoft Graph.

EjemploExample

En el ejemplo siguiente se convierte un ID de Graph normal a un ID de Graph inmutable.The following example translates a normal Graph ID to an immutable Graph ID.

SolicitudRequest

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

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

RespuestaResponse

HTTP 200 OK

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