Получение неизменяемых идентификаторов для ресурсов Outlook

  • Статья

Элементы Outlook (сообщения, события, контакты, задачи) ведут себя довольно интересно, и вы этого либо никогда не замечали, либо это вызывало серьезные затруднения: их идентификаторы изменяются. Это происходит нечасто (только при перемещении элемента), но может привести к серьезным проблемам для приложений, сохраняющих идентификаторы в автономном режиме для дальнейшего использования. Неизменяемые идентификаторы позволяют приложению получить идентификатор, который не изменяется в течение времени существования элемента.

Примечание.

В неизменяемых идентификаторах, как и во всех других идентификаторах в Microsoft Graph, учитывается регистр. Об этом следует помнить при сравнении идентификаторов.

Принципы работы

Неизменяемый идентификатор — это необязательная функция для Microsoft Graph. Чтобы согласиться на ее использование, ваше приложение должно отправить дополнительный заголовок HTTP в запросах API:

Prefer: IdType="ImmutableId"

Этот заголовок относится только к запросу, в который он входит. Если вы хотите всегда использовать неизменяемые идентификаторы, необходимо включать этот заголовок в каждый запрос API.

Время существования неизменяемых идентификаторов

Неизменяемый идентификатор элемента не изменится до тех пор, пока элемент остается в том же почтовом ящике. Это означает, что неизменяемый идентификатор НЕ изменится, если элемент перемещается в другую папку почтового ящика. Однако неизменяемый идентификатор изменяется, если:

  • пользователь перемещает элемент в архивный почтовый ящик;
  • пользователь экспортирует элемент (в PST-файл, в виде MSG-файла и т. д.) и повторно импортирует его в свой почтовый ящик;

Элементы, поддерживающие неизменяемые идентификаторы

Приведенные ниже элементы поддерживают неизменяемые идентификаторы.

Типы контейнеров (mailFolder, календарь и т. д.) не поддерживают неизменяемый идентификатор, но их обычные идентификаторы уже были постоянными.

Неизменяемый идентификатор с отправляемой почтой

Вы можете использовать неизменяемые идентификаторы для поиска сообщения в папке "Отправленные" после его отправки с помощью следующих действий:

  1. Создайте черновик сообщения, используя заголовок Prefer: IdType="ImmutableId", и сохраните свойство id сообщения в отклике.
  2. Отправьте сообщение, используя идентификатор из предыдущего действия.
  3. Получите сообщение, используя идентификатор из первого действия. Это копия из папки "Отправленные".

Примечание.

Получение сообщения из папки "Отправленные" сразу после отправки сообщения может завершиться неудачей. Копия сообщения не создается, пока сообщение не будет успешно отправлено, что может занять некоторое время.

Неизменяемый идентификатор с уведомлением об изменениях

Можно запросить, чтобы Microsoft Graph отправлял неизменяемые идентификаторы в уведомлениях об изменениях путем включения заголовка Prefer: IdType="ImmutableId" при создании подписки. Существующие подписки, созданные без заголовка, по-прежнему используют формат идентификатора по умолчанию. Чтобы переключить существующие подписки на использование неизменяемых идентификаторов, их нужно удалить и заново создать с использованием заголовка.

Неизменяемый идентификатор с запросом изменений

Можно запросить, чтобы Microsoft Graph возвращал неизменяемые идентификаторы в ответах на запросы изменений для поддерживаемых типов ресурсов путем включения заголовка Prefer: IdType="ImmutableId". @odata.nextLink Значения и@odata.deltaLink, возвращаемые разностными запросами, совместимы с обоими форматами идентификаторов, поэтому приложению не нужно повторно синхронизировать, чтобы воспользоваться преимуществами неизменяемого идентификатора. С помощью заголовка можно получить неизменяемые идентификаторы в дальнейшем и можно отдельно обновить хранилище вашего приложения.

Обновление существующих данных

Если уже имеется база данных, заполненная тысячами обычных идентификаторов, можно перенести эти идентификаторы в неизменяемый формат с помощью функции translateExchangeIds. Вы можете обеспечить массив для перевода в нужный формат с количеством идентификаторов до 1000.

Примечание.

Можно также использовать translateExchangeIds для переноса приложений веб-служб Exchange в Microsoft Graph.

Пример

В следующем примере обычный ИД Microsoft Graph преобразуется в неизменяемый ИД Microsoft Graph.

Запрос

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

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

Отклик

HTTP 200 OK

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