Outlook 扩展属性概述Outlook extended properties overview

扩展属性允许存储自定义数据,当 Outlook MAPI 属性_尚未在 Microsoft Graph API 元数据中公开_时,扩展属性专门用作应用访问这些属性的自定义数据的回退机制。可以使用扩展属性 REST API 在以下用户资源中存储或获取此类自定义数据:Extended properties allow storing custom data and specifically serve as a fallback mechanism for apps to access custom data for Outlook MAPI properties when these properties are not already exposed in the Microsoft Graph API metadata. You can use extended properties REST API to store or get such custom data in the following user resources:

或者,在以下 Office 365 组资源中:Or, in the following Office 365 group resources:

使用扩展属性还是开放扩展?Use extended properties or open extensions?

在大多数的常见情况下,你应该能够使用开放扩展(用 openTypeExtension 表示,以前被称为 Office 365 数据扩展)来存储和访问用户邮箱中资源实例的自定义数据。仅当需要访问尚未通过 Microsoft Graph API 元数据公开的 Outlook MAPI 属性的自定义数据时使用扩展属性。In most common scenarios, you should be able to use open extensions (represented by openTypeExtension, formerly known as Office 365 data extensions) to store and access custom data for resource instances in a user's mailbox. Use extended properties only if you need to access custom data for Outlook MAPI properties that are not already exposed in the Microsoft Graph API metadata.

扩展属性的类型Types of extended properties

根据是否打算将单个值或多个值(相同类型)存储在一个扩展属性中,可以将扩展属性创建为 singleValueLegacyExtendedPropertymultiValueLegacyExtendedPropertyDepending on whether you intend to store a single or multiple values (of the same type) in an extended property, you can create an extended property as a singleValueLegacyExtendedProperty, or multiValueLegacyExtendedProperty.

其中的每种类型都通过其 id 进行标识并将数据存储在 value 中。Each of these types identifies the property by its id and stores data in value.

可以使用 id 获取特定的资源实例以及该扩展属性,或筛选单值扩展属性以获取拥有该属性的所有实例。You can use id to get a specific resource instance together with that extended property, or filter on a single-value extended property to get all the instances that have that property.

注意 不能使用 REST API 在一个调用中获取特定实例的所有扩展属性。Note You cannot use the REST API to get all the extended properties of a specific instance in one call.

id 格式id formats

可以使用以下三种格式之一指定扩展属性的 idYou can specify id of an extended property in one of three formats:

  • 作为命名属性,由扩展属性类型、名称空间和字符串名称标识。As a named property, identified by the extended property type, namespace, and a string name.
  • 作为命名属性,由扩展属性类型、名称空间和数字标识符标识。As a named property, identified by the extended property type, namespace, and a numeric identifier.
  • 采用属性标记格式,由扩展属性类型和 MAPI 属性标记标识。In a proptag format, identified by the extended property type and a MAPI property tag.

接下来的两个表描述了应用于单值和多值扩展属性的这些格式。The next 2 tables describe these formats as applied to single and multi-value extended properties. {type} 表示一个或多个扩展属性值的类型。{type} represents the type of the value or values of the extended property. 示例中使用的是 string、integer 和这些类型的数组。Shown in the examples are string, integer, and arrays of these types.

单值扩展属性的有效 id 格式Valid id formats for single-value extended properties

格式Format 示例Example 说明Description
"{type} {guid} Name {name}""{type} {guid} Name {name}" "String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" 用所属的命名空间 (GUID) 和字符串名称标识属性。Identifies a property by the namespace (the GUID) it belongs to, and a string name.
"{type} {guid} Id {id}""{type} {guid} Id {id}" "Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012" 用所属的命名空间 (GUID) 和数字标识符标识属性。Identifies a property by the namespace (the GUID) it belongs to, and a numeric identifier.
"{type} {proptag}""{type} {proptag}" "String 0x4001001E" 用属性标记标识预定义的属性。Identifies a pre-defined property by its property tag.

多值扩展属性的有效 id 格式Valid id formats for multi-value extended properties

格式Format 示例Example 说明Description
"{type} {guid} Name {name}""{type} {guid} Name {name}" "StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" 用命名空间 (GUID) 和字符串名称标识属性。Identifies a property by the namespace (the GUID) and a string name.
"{type} {guid} Id {id}""{type} {guid} Id {id}" "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" 用命名空间 (GUID) 和数字标识符标识属性。Identifies a property by the namespace (the GUID) and a numeric identifier.
"{type} {proptag}""{type} {proptag}" "StringArray 0x4002101E" 用属性标记标识预定义的属性。Identifies a pre-defined property by its property tag.

使用任一命名属性格式将单值或多值扩展属性定义为自定义属性。Use either of the named property formats to define a single-value or multi-value extended property as a custom property. 在这两种格式中,第一种采用字符串名称 (Name) 的格式是易于参考的首选格式。Among the two formats, the first one that takes a string name (Name) is the preferred format for ease of reference. 命名属性的属性标识符在 0x8000-0xfffe 范围内。Named properties have their property identifiers in the 0x8000-0xfffe range.

使用属性标记格式访问由 MAPI 或客户端或服务器预定义的属性,以及尚未在 Microsoft Graph 中公开的属性。Use the proptag format to access properties predefined by MAPI, or by a client or server, and that have not already been exposed in Microsoft Graph. 这些属性的属性标识符在 0x0001-0x7fff 范围内。These properties have property identifiers in the 0x0001-0x7fff range. 不要尝试使用属性标记格式定义自定义属性。Do not try to define a custom property using the proptag format.

在 [MS-OXPROPS] Microsoft Corporation 的“Exchange Server 协议 Master 属性列表”中,可以了解如何将扩展属性映射到现有 MAPI 属性,如属性标识符和 GUID。You can find information about mapping an extended property to an existing MAPI property, such as the property identifier and GUID, in [MS-OXPROPS] Microsoft Corporation, "Exchange Server Protocols Master Property List".

注意:为 id 选择一种格式后,只能按此格式访问扩展属性。Note After you have chosen one format for the id, you should access that extended property by only that format.

REST API 操作REST API operations

单值扩展属性的操作:Single-value extended property operations:

多值扩展属性的操作:Multi-value extended property operations: