大网数据广告活动
Microsoft Graph 接口

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

· 52CE 我爱测

使用不可变标识符 (ID) 使 Outlook 应用程序能够获取在项目生存期内不会更改的 ID。

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

Note: 不可变标识符(如 Microsoft Graph 中的所有标识符)区分大小写。 如果要比较 ID,请记住这一点。

运作方式

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

Prefer: IdType="ImmutableId"

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

不可更改的 ID 生存期

只要项一直在同一邮箱中,它的不可变 ID 就不变。 也就是说,即使项移到邮箱中的其他文件夹中,不可变 ID 也不变。 不过,不可变 ID 在以下情况下会变:

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

支持不可更改 ID 的项

以下项支持不可变 ID:

虽然容器类型(mailFolder、calendar 等)不支持不可变 ID,但其常规 ID 已是常量。

已发送邮件的不可变 ID

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

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

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

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

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

使用 delta 查询发送不可变 ID

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

更新现有数据

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

Note: 还可使用 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..."
    }
  ]
}

历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。

来源与署名:Microsoft 和文档贡献者(原始作者元数据 abheek-das)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。

资料来源与适用范围

资料来源
Microsoft / Microsoft Graph 中文文档历史快照
适用范围
历史中文快照 2023-02-03;详见原文产品版本;文档日期 未标明
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0(文档)/ MIT(示例代码)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。