Obtener identificadores inmutables para recursos de Outlook

  • Artículo

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. 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. Los identificadores inmutables (IDENTIFICADOR) permiten a la aplicación obtener un identificador que no cambia durante la vigencia del elemento.

Nota:

Los identificadores inmutables, como todos los identificadores de Microsoft Graph, distinguen mayúsculas de minúsculas. Tenga esto en cuenta si compara ID.

Cómo funciona

El Identificador inmutable es una característica opcional de Microsoft Graph. Para habilitarla, la aplicación debe enviar un encabezado HTTP adicional en sus solicitudes de API:

Prefer: IdType="ImmutableId"

Este encabezado solo se aplica a la solicitud en la que está incluido. Si quiere usar siempre identificadores inmutables, debe incluir este encabezado en cada solicitud de API.

Duración de los ID inmutables

El identificador inmutable de un elemento no cambiará siempre que el elemento permanezca en el mismo buzón. Eso significa que el identificador inmutable no cambiará si el elemento se mueve a otra carpeta del buzón. Sin embargo, el identificador inmutable cambia si:

  • El usuario mueve el elemento a un buzón de archivo.
  • El usuario exporta el elemento (a un archivo PST, como un archivo MSG, etc.) y vuelve a importarlo a su buzón.

Elementos que admiten los identificadores inmutables

Los siguientes elementos admiten los identificadores inmutables:

Los tipos de contenedor (mailFolder, calendar, etc.) no admiten el identificador inmutable, pero sus identificadores normales ya eran constantes.

Identificador inmutable con el envío de correo

Puede usar identificadores inmutables para buscar un mensaje en la carpeta Elementos enviados después de que se haya enviado, siguiendo estos pasos:

  1. Cree un borrador de mensaje con el encabezado Prefer: IdType="ImmutableId" y guarde la propiedad id del mensaje en la respuesta.
  2. Envíe el mensaje con el ID. del paso anterior.
  3. Obtenga el mensaje con el ID. del primer paso. Esta es la copia en Elementos enviados.

Nota:

Es posible que la aparición del mensaje en Elementos enviados no se realice inmediatamente después de enviar el mensaje. La copia del mensaje no se crea hasta que el mensaje se envía correctamente, lo que puede tardar algún tiempo.

El identificador inmutable con las notificaciones de cambios

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. Las suscripciones existentes creadas sin el encabezado siguen usando el formato de identificador predeterminado. Para pasar de una suscripción existente a usar identificadores inmutables, debe eliminarlos y volver a crearlos con el encabezado.

El identificador inmutable con consulta delta

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". Los @odata.nextLink valores y @odata.deltaLink devueltos por las consultas delta son compatibles con ambos formatos de identificador, por lo que la aplicación no necesita volver a sincronizarse para aprovechar el identificador inmutable. Puede usar el encabezado para obtener los identificadores inmutables en el futuro y puede actualizar el almacenamiento de la aplicación por separado.

Actualizar los datos existentes

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. Puede proporcionar una matriz de hasta 1000 identificadores para convertir en un formato de destino.

Nota:

También puede usar translateExchangeIds para migrar aplicaciones de servicios Web Exchange a Microsoft Graph.

Ejemplo

En el ejemplo siguiente se convierte un ID de Microsoft Graph normal a un ID de Microsoft Graph inmutable.

Solicitud

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

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

Respuesta

HTTP 200 OK

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