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

您可以在三种格式之一指定的扩展属性的id :You 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} 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}" "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}" "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: