获取 Outlook 资源的不可变标识符Get immutable identifiers for Outlook resources

Outlook 项(邮件、事件、联系人、任务)有一个有趣行为,你可能从未注意到或已给你带来了极大挫败感,即它们的 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. 虽然这一行为不是经常发生(只在项移动时才会发生),但对于脱机存储 ID 以供日后使用的应用来说,这可能会导致真正的问题出现。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. 借助不可变标识符,应用可以获取在项生存期内不变的 ID。Immutable identifiers enables your application to obtain an ID that does not change for the lifetime of the item.

备注

不可变标识符(如 Microsoft Graph 中的所有标识符)区分大小写。Immutable identifiers, like all identifiers in Microsoft Graph, are case-sensitive. 如果要比较 ID,请记住这一点。Keep this in mind if you are comparing IDs.

运作方式How it works

不可变 ID 是一项可选的 Microsoft Graph 功能。Immutable ID is an optional feature for Microsoft Graph. 若要选择使用此功能,应用必须在 API 请求中发送额外 HTTP 头:To opt in, your application needs to send an additional HTTP header in your API requests:

Prefer: IdType="ImmutableId"

此头仅适用于随附它的请求。This header only applies to the request it is included with. 必须在每个 API 请求中随附此头,才能始终使用不可变 ID。If you want to always use immutable IDs, you must include this header with every API request.

不可变 ID 生存期Lifetime of Immutable IDs

只要项一直在同一邮箱中,它的不可变 ID 就不变。An item's immutable ID will not change so long as the item stays in the same mailbox. 也就是说,即使项移到邮箱中的其他文件夹中,不可变 ID 也不变。That means that immutable ID will NOT change if the item is moved to a different folder in the mailbox. 不过,不可变 ID 在以下情况下会变:However, the immutable ID will change if:

  • 用户将该项移到存档邮箱中。The user moves the item to an archive mailbox.
  • 用户先将该项导出(到 PST 等,作为 MSG 文件),再将它重新导入邮箱。The user exports the item (to a PST, as an MSG file, etc.) and re-imports it into their mailbox.

支持不可变 ID 的项Items that support immutable ID

以下项支持不可变 ID:The following items support immutable IDs:

虽然容器类型(mailFolder、calendar 等)不支持不可变 ID,但其常规 ID 已是常量。Container types (mailFolder, calendar, etc.) do not support immutable ID, but their regular IDs were already constant.

已发送邮件的不可变 IDImmutable ID with sending mail

发送邮件后,可以使用不可变 ID 在“已发送邮件”文件夹中查找邮件,步骤如下:You can use immutable IDs to find a message in the Sent Items folder after it has been sent, using the following steps:

  1. 使用 Prefer: IdType="ImmutableId" 标头创建邮件草稿,并将邮件的 id 属性保存在回复中。Create a draft message using the Prefer: IdType="ImmutableId" header and save the id property of the message in the response.
  2. 使用上一步中的 ID 发送邮件Send the message using the ID from the previous step.
  3. 使用第一步中的 ID 获取邮件Get the message using the ID from the first step. 这是“已发送邮件”中的副本。This is the copy in Sent Items.

备注

发送邮件后,无法立即在“已发送邮件”中获取邮件。Getting the message in Sent Items may not succeed immediately after sending the message. 在成功发送邮件之前,不会创建邮件的副本,这可能需要一些时间。The copy of the message is not created until the message successfully sends, which may take time.

使用更改通知发送不可变 IDImmutable ID with change notifications

可以在创建订阅时添加 Prefer: IdType="ImmutableId" 头,从而请求 Microsoft Graph 在更改通知中发送不可变 ID。You can request that Microsoft Graph send immutable IDs in change notifications by including the Prefer: IdType="ImmutableId" header when creating a subscription. 未使用此头创建的的现有订阅将继续使用默认 ID 格式。Existing subscriptions created without the header will continue to use the default ID format. 为了将现有订阅切换为使用不可变 ID,必须先删除它们,再使用此头重新创建它们。In order to switch existing subscriptions to use immutable IDs, you must delete and recreate them using the header.

使用 delta 查询发送不可变 IDImmutable ID with delta query

可以通过添加 Prefer: IdType="ImmutableId" 头,请求 Microsoft Graph 在受支持资源类型的 delta 查询响应中返回不可变 ID。You can request that Microsoft Graph return immutable IDs in delta query responses for supported resource types by including the Prefer: IdType="ImmutableId" header. 由于 delta 查询返回的 nextLinkdeltaLink 值与两种 ID 格式都兼容,因此应用无需重新同步,即可利用不可变 ID。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. 可以使用此头在以后获取不可变 ID,也可以单独更新应用的存储You can use the header to get immutable IDs going forward, and you can update your app's storage separately.

更新现有数据Updating existing data

如果已获取填充有数千个常规 ID 的数据库,可使用 translateExchangeIds 函数将这些 ID 迁移为不可变格式。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. 可以提供一组要转换为目标格式的 ID(最多 1000 个)。You can provide an array of up to 1000 IDs to be translated into a target format.

备注

还可使用 translateExchangeIds 将 Exchange Web 服务应用程序迁移到 Microsoft Graph。You can also use translateExchangeIds to migrate Exchange Web Services applications to Microsoft Graph.

示例Example

下面的示例将普通 Graph ID 转换为不可变 Graph ID。The following example translates a normal Graph ID to an immutable Graph ID.

请求Request

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

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

响应Response

HTTP 200 OK

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