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.

Importante: Los identificadores inmutables solo están disponibles en la versión /beta de Microsoft Graph.Important: Immutable identifiers are only available on the /beta version in Microsoft Graph.

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 archivoThe 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ónThe 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.

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.Note: 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/beta/me/translateExchangeIds

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

RespuestaResponse

HTTP 200 OK

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