属性和交换中的 EWS 中的扩展的属性

项目
03/29/2023

了解如何在 Exchange 中使用 EWS 定义和访问项目和文件夹的属性。

Exchange 邮箱包含大量项目，包括电子邮件、约会、会议等。这些项由属性组成：属性描述项。可以使用项属性来执行搜索、同步项更改和创建自定义属性类型。本文概述了属性以及如何在应用程序中使用属性。

Exchange 项目属性

Exchange 中的项目和文件夹实质上是表中的行。标识项目或文件夹的主属性是其 EWS 标识符。尽管 Exchange 数据库中还有其他与标识符相关的属性，但对于 EWS，EWS 标识符充当描述项的属性集合的主键。 EWS 标识符属性包含两个部分：

用于标识项的 ItemId 或 FolderId 属性
一个 ChangeKey 属性，其中包含有关项目或文件夹是否已更改的有状态信息

邮箱中的所有项目都存储在同一 Exchange 数据库中，并使用相同的数据库架构。项由 ItemClass 属性、属性约束和业务逻辑层的组合来区分，这些层会影响它们在 Exchange 存储中的管理方式。表 1 显示了如何跨不同的项类型应用属性;在此示例中，电子邮件和约会项目。这两项都具有 Subject 属性的值。但请注意，未对电子邮件项目设置 IsAllDayEvent 属性，并且未在约会上设置 IsReadReceiptRequested 属性。幸运的是，不需要知道哪些属性适用于每个项类;EWS 会为你处理此问题。

表 1. 约会和电子邮件属性的比较

项目类型	Item 类	主题	IsAllDayEvent	IsReadReceiptRequested
电子邮件	Ipm。注意	状态报告：项目 X 已完成	NULL	true
Appointment	Ipm。委任	Contoso 公司会议	false	NULL

EWS 架构支持由 Exchange 数据库以及 EWS 和 Exchange 数据库之间的业务逻辑层管理的许多约束。 EWS 架构将定义的一组属性应用于每个项类型。以下是 EWS 提供的强类型 Exchange 数据库项：

电子邮件
约会
联系人
通讯组列表
会议消息
会议请求
会议响应
会议取消
任务
发布项目

EWS 将一般项目作为电子邮件返回。 EWS 托管 API 实现所有这些项类型。

注意

响应对象仅由客户端发送到服务器，以响应从其他人收到的项目。 Exchange 数据库中不存在它们。

EWS 中的属性是什么？

EWS 架构描述在 EWS 客户端和 Exchange 之间发送的数据。架构的很大一部分描述了可以在 Exchange 数据库中访问的项目和文件夹属性。 EWS 架构描述可用于应用程序的 Exchange 数据库属性的 XML 表示形式。实际属性，在哪些属性可用，它们采用何种形式，以及它们返回的值方面，根据你尝试执行的操作而有所不同。例如， Body 属性将仅返回 FindItem 操作中的前 512 个字符，但 GetItem 操作返回项的全文。尽管大多数属性都是可设置的和可检索的，但某些属性仅由 Exchange 设置。每个属性都以 XML 格式存在于架构中，该格式要么反映存储在 Exchange 数据库中的属性，要么从存储在 Exchange 数据库中的属性进行计算。 Subject 属性是可设置属性的示例;文件夹上的 UnreadCount 属性是计算属性的示例。核心项类型共有一组核心属性。

以下因素确定应用程序从 Exchange 获取的属性集：

应用程序正在调用的操作
基本响应形状
项类型
指定的属性路径

请务必了解这些不同因素如何影响可以访问的数据。与前面提到的 Body 属性示例一样，根据各种因素，某些信息有条件地可用。了解这些因素可帮助你选择正确的选项来访问所需信息，从而节省时间。若要发现可访问的属性，需要测试这些因素，以确定如何访问应用程序所需的属性。本部分介绍这些不同因素如何影响 EWS 响应中返回的属性。

EWS 响应形状

Exchange 存储大量有关项的信息。有时，应用程序不需要所有这些信息，在许多情况下，最好不要获取全部信息。 EWS 响应形状（也称为属性形状）指示从服务器返回的属性。响应形状的核心元素是基形状。基本形状是强类型项的默认预设属性包。基本形状等效的 EWS 托管 API 是 BasePropertySet。 EWS 包括三个默认响应形状。

表 2. 默认响应形状

默认响应形状名称	EWS 托管 API 等效项	说明
IdOnly	BasePropertySet.IdOnly 值	仅返回 EWS 标识符和更改密钥。除非客户端使用 AllProperties 或 Default 形状返回的所有属性，否则请使用 IdOnly 形状，并使用 PropertySet 类上设置的属性路径指定其他属性。大多数应用程序应使用具有指定其他属性的 IdOnly 响应形状。这可以减少客户端请求的未使用数据量。
默认值	不适用	项类型的一组标准属性。仅当应用程序使用所有属性时，才使用此响应形状。
AllProperties	BasePropertySet.FirstClassProperties 值	比默认形状更大的属性集。尽管名称表示，但此选项不会返回项的所有属性。此属性集返回客户端应用程序最常使用的属性。如果需要其他属性，可以按属性路径请求它们。如果应用程序未使用此响应形状返回的所有属性，请使用具有指定其他属性的 IdOnly 响应形状。

许多 EWS 操作返回项及其属性。无论指定的响应形状如何，不同的操作都可以返回不同的属性集。不同的项类型还会返回不同的属性，具体取决于指定的操作和响应形状。以下操作使用响应形状来确定要返回的属性。

表 3. 使用响应形状的操作

EWS 操作	EWS 托管 API 方法
GetConversationItems	ExchangeService.GetConversationItems 方法
GetFolder	Folder.Bind 方法
GetItem	Item.Bind 方法 ExchangeService.BindToItems 方法
FindConversation	ExchangeService.FindConversation 方法
FindFolder	Folder.FindFolders 方法 ExchangeService.FindFolders 方法
FindItem	Folder.FindItems 方法 ExchangeService.FindItems 方法
FindPeople	未实现。
ResolveNames	ExchangeService.ResolveNames 方法
SearchMailboxes	ExchangeService.SearchMailboxes 方法 ExchangeService.BeginSearchMailboxes 方法
SyncFolderHierarchy	ExchangeService.SyncFolderHierarchy 方法
SyncFolderItems	ExchangeService.SyncFolderItems 方法

属性形状是标识希望应用程序返回的属性的一种基础方法。但是，有时，应用程序需要一组更精细的特定属性。为此，可以使用属性路径。

按属性路径选择属性

EWS 属性路径是用于标识请求或响应中的属性的元数据。

表 4. 属性路径类型

属性路径类型	架构类型	EWS 托管 API 实现	说明
FieldUri	PathToUnindexedFieldType	继承自 ServiceObjectSchema 的类型。	最常见的属性路径。 FieldUri 属性路径在 EWS 托管 API 中的 PropertySet 对象上指定。大多数 EWS 属性都可以由 FieldUri 属性路径指定。 EWS 架构中的 UnindexedFieldURIType 对此进行了描述。 FieldUri 属性路径 XML 如下所示： `XML<FieldURI FieldURI="item:Subject"/>`此属性路径等效于 EWS 托管 API 中的 ItemSchema.Subject。
IndexedFieldUri	PathToIndexedFieldType	继承自 ItemSchema 的类型。	标识需要属性索引来指定要返回的值的字典属性。当属性可以有多个值时，请使用此路径。这由 EWS 架构中的 DictionaryURIType 属性描述。 DictionaryURIType 属性路径在 EWS 托管 API 中的 PropertySet 对象上指定。 IndexedFieldUri 属性路径 XML 如下所示： `XML<IndexedFieldURI FieldURI="contacts:PhysicalAddress:Street FieldIndex="Home"/>`
ExtendedFieldUri	PathToExtendedFieldType	ExtendedPropertyDefinition	标识一个扩展属性定义，该定义标识项上的自定义或非架构化属性。 ExtendedFieldUri 属性路径 XML 如下所示： `XML<ExtendedFieldURI> PropertyTag="0x1234" PropertyType="Integer" />`
ExceptionFieldUri	ExceptionFieldURI	ServiceResponse	指定与 EWS 响应中的错误关联的属性。这由 EWS 架构中的 ExceptionPropertyURIType 类型描述。这仅在处理日历重复模式时发生的错误响应的 MessageXml 元素中发生。

作为最佳做法，在请求属性时，请在 EWS 托管 API) 中使用 IdOnly 基形状 (BasePropertySet.IdOnly ，然后通过指定属性路径仅请求应用程序所需的属性。

架构化属性

EWS 架构描述了 EWS 客户端所需的大多数属性。主文件夹和项类型定义（包含属性定义）位于 types.xsd 架构中。以下架构类型包含可使用的大多数对象的属性定义。

表 5. 包含属性定义的架构类型

EWS 架构类型	EWS 托管 API 类型等效项	定义...
ItemType	Item 类	基项类型属性集。此类型可以从客户端创建，但 Exchange 永远不会返回。 Exchange 为所有泛型对象返回 MessageType 对象。
MessageType	EmailMessage 类	Email消息对象属性集和所有泛型对象的属性集。
CalendarItemType	Appointment 类	日历项属性集;这包括单次约会和定期约会。
ContactItemType	Contact 类	联系人项目属性集。
DistributionListType	ContactGroup 类	个人通讯组列表属性集。
MeetingMessageType	MeetingMessage 类	会议消息类型属性集。
MeetingRequestMessageType	MeetingRequest 类	会议请求类型属性集。
MeetingResponseMessageType	MeetingResponse 类	会议响应类型属性集。
MeetingCancellationMessageType	MeetingCancellation 类	会议取消类型属性集。
TaskType	任务类	任务类型属性集。
PostItemType	PostItem 类	Postitem 类型属性集。
FolderType	Folder 类	文件夹类型属性集。
CalendarFolderType	CalendarFolder 类	SearchFolder 类型属性集。
ContactsFolderType	ContactsFolder 类	ContactsFolder 类型属性集。
SearchFolderType	SearchFolder 类	SearchFolder 类型属性集。
TasksFolderType	TasksFolder 类	TasksFolder 类型属性集。
UserConfigurationType	UserConfiguration 类	UserConfiguration 类型属性集。

虽然 EWS 架构中的属性足以满足许多应用程序的需求，但某些方案不能仅使用架构中所述的内容来实现。对于这些方案，可以扩展属性。

扩展属性 (也称为非架构化属性)

通过扩展属性，可以创建自定义属性，从而可以访问 Exchange 存储中未在 EWS 架构中定义的项目和文件夹的属性。可以使用它们访问 Exchange 数据库中的本机 MAPI 项和文件夹属性。可以使用扩展属性来访问所有架构化属性，因为在封面上，这些架构化属性只不过是 Exchange 数据库中的 MAPI 属性。

PathToExtendedFieldType 架构类型（位于 types.xsd 架构中）定义表示扩展属性的 XML。此架构类型定义 XML 实例中的 ExtendedFieldURI 元素;换句话说，它定义在服务和客户端之间发送的 XML。 ExtendedPropertyType 架构类型定义 ExtendedFieldURI 元素以及扩展属性包含的值或值数组。下表显示了扩展属性 XML 的大致映射，以及如何在 EWS 托管 API 中的项上实现它。

表 6. 在 EWS 托管 API 中实现的扩展属性 XML

EWS 托管 API 实现	它包含的内容	它映射到的内容
Item.ExtendedProperties 属性	项上的扩展属性的集合。	项上的一个或多个扩展属性实例。
ExtendedProperty 类	扩展的属性定义和值。	ExtendedPropertyType 架构类型。
ExtendedPropertyDefinition 类	扩展属性定义。	PathToExtendedFieldType 架构类型。

若要详细了解如何在应用程序中使用扩展属性，可以浏览以下代码示例：