Поделиться через

Получение неизменяемых идентификаторов для ресурсов 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..."
    }
  ]
}
  • Last updated on