Outlook 扩展属性概述

  • 项目

命名空间：microsoft.graph

扩展属性允许存储自定义数据，并特别用作一种回退机制，供应用在 Microsoft 图形 API metadata_中尚未公开这些属性时访问 Outlook MAPI 属性的自定义数据。 可以使用扩展属性 REST API 在以下用户资源中存储或获取此类自定义数据：

或者，在以下 Microsoft 365 组资源中：

使用扩展属性还是开放扩展？

在大多数的常见情况下，你应该能够使用开放扩展（用 openTypeExtension 表示，以前被称为 Office 365 数据扩展）来存储和访问用户邮箱中资源实例的自定义数据。 仅当需要访问尚未在 Microsoft 图形 API元数据中公开的 Outlook MAPI 属性的自定义数据时，才使用扩展属性。

扩展属性的类型

根据是否打算将单个值或多个值（相同类型）存储在一个扩展属性中，可以将扩展属性创建为 singleValueLegacyExtendedProperty 或 multiValueLegacyExtendedProperty。

其中的每种类型都通过其 id 进行标识并将数据存储在 value 中。

可以使用 id 获取特定的资源实例以及该扩展属性，或筛选单值扩展属性以获取拥有该属性的所有实例。

注意 不能使用 REST API 在一次调用中获取特定实例的所有扩展属性。

id 格式

可以使用以下三种格式之一指定扩展属性的 id：

  • 作为命名属性，由扩展属性类型、名称空间和字符串名称标识。
  • 作为命名属性，由扩展属性类型、名称空间和数字标识符标识。
  • 采用属性标记格式，由扩展属性类型和 MAPI 属性标记标识。

接下来的两个表描述了应用于单值和多值扩展属性的这些格式。 {type} 表示一个或多个扩展属性值的类型。 示例中使用的是 string、integer 和这些类型的数组。

单值扩展属性的有效 id 格式

格式 示例 说明
"{type} {guid} Name {name}" "String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" 用所属的命名空间 (GUID) 和字符串名称标识属性。
"{type} {guid} Id {id}" "Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012" 用所属的命名空间 (GUID) 和数字标识符标识属性。
"{type} {proptag}" "String 0x4001" 通过属性标记标识预定义属性。

多值扩展属性的有效 id 格式

格式 示例 说明
"{type} {guid} Name {name}" "StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" 用命名空间 (GUID) 和字符串名称标识属性。
"{type} {guid} Id {id}" "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" 用命名空间 (GUID) 和数字标识符标识属性。
"{type} {proptag}" "StringArray 0x4002" 通过属性标记标识预定义属性。

使用任一命名属性格式将单值或多值扩展属性定义为自定义属性。 在这两种格式中，第一种采用字符串名称 (Name) 的格式是易于参考的首选格式。 命名属性的属性标识符在 0x8000-0xfffe 范围内。

使用 proptag 格式访问 MAPI 或客户端或服务器预定义的属性，这些属性尚未在 Microsoft Graph 中公开。 这些属性的属性标识符在 0x0001-0x7fff 范围内。 不要尝试使用 proptag 格式定义自定义属性。

可以在 [MS-OXPROPS] Microsoft Corporation 的“Exchange Server协议主属性列表”中找到有关将扩展属性映射到现有 MAPI 属性的信息，例如属性标识符和 GUID。

注意：为 id 选择一种格式后，只能按此格式访问扩展属性。

REST API 操作

单值扩展属性的操作：

多值扩展属性的操作：