获取 Outlook 资源的不可变标识符

Outlook 项（邮件、事件、联系人、任务）有一个有趣行为，你可能从未注意到或已给你带来了极大挫败感，即它们的 ID 会变。 虽然这一行为不是经常发生（只在项移动时才会发生），但对于脱机存储 ID 以供日后使用的应用来说，这可能会导致真正的问题出现。 不可变标识符 (ID) 使应用程序能够获取在项目生存期内不会更改的 ID。

注意

不可变标识符（如 Microsoft Graph 中的所有标识符）区分大小写。 如果要比较 ID，请记住这一点。

运作方式

不可变 ID 是一项可选的 Microsoft Graph 功能。 若要选择使用此功能，应用必须在 API 请求中发送额外 HTTP 头：

Prefer: IdType="ImmutableId"

此头仅适用于随附它的请求。 必须在每个 API 请求中随附此头，才能始终使用不可变 ID。

不可更改的 ID 生存期

只要项目保留在同一邮箱中，项目不可变 ID 就不会更改。 也就是说，即使项移到邮箱中的其他文件夹中，不可变 ID 也不变。 但是，在以下的情况下，不可变 ID 会更改：

• 用户将该项移到存档邮箱中。
• 用户先将该项导出（到 PST 等，作为 MSG 文件），再将它重新导入邮箱。

支持不可更改 ID 的项

以下项支持不可变 ID：

• message 资源类型
• attachment 资源类型
• event 资源类型
• eventMessage 资源类型
• contact 资源类型
• outlookTask 资源类型

容器类型 (mailFolder、calendar 等 ) 不支持不可变 ID，但其常规 ID 已保持不变。

已发送邮件的不可变 ID

发送邮件后，可以使用不可变 ID 在“已发送邮件”文件夹中查找邮件，步骤如下：

1. 使用 Prefer: IdType="ImmutableId" 标头创建邮件草稿，并将邮件的 id 属性保存在回复中。
2. 使用上一步中的 ID 发送邮件。
3. 使用第一步中的 ID 获取邮件。 这是“已发送邮件”中的副本。

注意

发送邮件后，无法立即在“已发送邮件”中获取邮件。 在成功发送邮件之前，不会创建邮件的副本，这可能需要一些时间。

使用更改通知发送不可变 ID

可以在创建订阅时添加 Prefer: IdType="ImmutableId" 头，从而请求 Microsoft Graph 在更改通知中发送不可变 ID。 在没有 标头的情况下创建的现有订阅继续使用默认 ID 格式。 为了将现有订阅切换为使用不可变 ID，必须先删除它们，再使用此头重新创建它们。

使用 delta 查询发送不可变 ID

可以通过添加 Prefer: IdType="ImmutableId" 头，请求 Microsoft Graph 在受支持资源类型的 delta 查询响应中返回不可变 ID。 @odata.nextLink增量查询返回的 和 @odata.deltaLink 值与这两种 ID 格式兼容，因此应用程序无需重新同步即可利用不可变 ID。 可以使用此头在以后获取不可变 ID，也可以单独更新应用的存储。

更新现有数据

如果已获取填充有数千个常规 ID 的数据库，可使用 translateExchangeIds 函数将这些 ID 迁移为不可变格式。 可以提供一组要转换为目标格式的 ID（最多 1000 个）。

注意

还可使用 translateExchangeIds 将 Exchange Web 服务应用程序迁移到 Microsoft Graph。

示例

下面的示例将普通 Microsoft Graph ID 转换为不可更改的 Microsoft Graph ID。

请求

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

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

响应

HTTP 200 OK

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