Exchange 中的 EWS 标识符

了解 Exchange 中的标识符以及如何在 EWS 托管 API 和 EWS 应用程序中使用这些标识符。

Exchange 存储区中的每个对象都有一个唯一标识符。 可以使用对象的标识符来引用对象，并将其与其他对象区分开来。 可以使用的两个最常见的标识符是文件夹标识符和项标识符。

为了了解标识符及其对应用程序的重要性，了解 Exchange 中对象之间的关系会很有帮助。 当 EWS 托管 API 或 EWS 应用程序与 Exchange 通信时，可以使用包含邮箱、文件夹和项目对象的对象层次结构。 存储可以是这些对象类型中的任何一种。 最常见的是 Exchange 服务器上的邮箱，但也可以是 Exchange 服务器上的公用文件夹。 (请记住，在 Exchange Online，Exchange Online作为Office 365的一部分，以及从 Exchange 2013 开始的 Exchange 版本，公用文件夹只是另一种类型的邮箱，而不是不同类型的存储。) 存储包含文件夹，而文件夹包含项目，其中每个文件夹和项目都有标识符，如下图所示。

图 1. 邮箱、文件夹和项目层次结构

EWS 标识符

EWS 用于文件夹和项的标识符称为 EWS 标识符或 EwsIds。 EwsIds 可以在 EWS 中的许多不同对象中找到，但对于不同的对象，称为不同的对象。 由于可能会在应用程序中使用这些对象，因此需要了解这些对象的标识符与 EwsId 的关系。

EWS 中的标识符也适用于 EWS 托管 API。 在 EWS 托管 API 中，标识符是对象的属性，并在内部进行管理以映射到 EWS 元素。

表 1. EWS 中的对象标识符

Object	标识符	它与 EwsId 有何关系？
CalendarItem	ItemId 子元素包含日历项的唯一标识符。	ItemId 子元素与此项的 EwsId 相同。
ConversationId	Id 属性包含此项目所属的对话的标识符。	Id 属性与此项的 EwsId 相同。
AttachmentId	提供附件的唯一标识符。 RootItemId 属性包含附件所附加到的根存储项的唯一标识符。	附件可以是 Exchange 存储中的其他项目，在这种情况下， AttachmentId 与 EwsId 相同。 在所有情况下， RootItemId 都是 EwsId，因为它引用存储中的项。
PersonaId	Id 属性返回一个字符串，其中包含角色的标识符。	Id 属性与角色的 EwsId 相同。
ContactId	Id 属性返回一个字符串，其中包含联系人的标识符。	Id 属性与联系人的 EwsId 相同。
GroupId	Id 属性返回一个字符串，其中包含组的标识符。	Id 属性与组的 EwsId 相同。
AssociatedCalendarItemId	Id 属性标识与 MeetingMessage、MeetingRequest、MeetingResponse 或 MeetingCancellation 关联的日历项。	Id 属性与日历项的 EwsId 相同。
UserConfigurationProperties	此元素的 Id 值指定标识符属性。	此标识符不会直接映射到 EwsId，因为它是属性标识符而不是项。
OccurrenceItemId	RecurringMasterId 属性标识定期项的主控形状。	OccurrenceItemId 值不直接映射到 EwsId，但定期MasterId 会直接映射到 EwsId，因为它引用定期项的顶级对象。
StoreEntryId	包含项目的 Exchange 存储标识符。	StoreEntryId 值不映射到 EwsId，但会提供保留项的存储的标识符。

使用标识符

Exchange 服务器以许多不同的方式处理标识符。 开发 EWS 托管 API 或 EWS 应用程序时，请考虑以下事项：

• 文件夹和项的 ItemID 元素值区分大小写。 如果查看 FindItem 操作 (或 FindItems EWS 托管 API 方法) 返回的文件夹或项目的项目 ID，则可能认为它是另一个项目 ID 的副本;但是，这两个项目的项目 ID 中的一个或多个字符将采用不同的大小写。

• 如果要将项 ID 存储在数据库中以供以后检索，建议字段大小为 512 字节，使其足够大，可以容纳 GUID。

• 如果以后需要检索项目，请不要认为项目 ID 将始终有效。 如果在存储中移动了项，则 ID 可能会因移动的处理方式而更改。 实际复制项目，并生成新 ID，然后 删除原始项。 请注意，文件夹 ID 是不可变的，在存储中移动时不会更改。

• Exchange 中的标识符是不透明的。 例如，EwsId 是从几个信息创建的，这些信息对你作为开发人员来说并不重要，但对 Exchange 很重要。

• 在 Exchange 中使用项目时，需要记住的另一个值是 ChangeKey 属性。 除了项 ID 之外，此值还用于跟踪项的状态。 每当更改项时，都会生成新的更改密钥。 例如，执行 UpdateItem 操作时，可以使用 ChangeKey 属性让服务器知道更新正在应用于项目的最新版本。 如果另一个应用程序对要更新的项进行了更改，则更改密钥将不匹配，并且你将无法执行更新。

可分辨文件夹 ID

Exchange 包括许多预定义邮箱文件夹，其中每个文件夹都分配有一个标识符，称为可分辨文件夹 ID。 它们由 WellKnownFolderName EWS 托管 API 枚举和 DistinguishedFolderId EWS 元素定义。 可以使用这些可分辨文件夹 ID 更轻松地引用预定义文件夹之一。 例如，对于“收件箱”文件夹，只需将“收件箱”用作标识符，而不是确定文件夹标识符。

为组织电子邮件项目而创建的其他文件夹也具有该文件夹唯一的 ID。 即使更改文件夹上的其他属性，该 ID 也不会更改。

可以使用可分辨文件夹 ID 作为代理访问的入口点。 启动委托访问时，可以搜索项目或文件夹，并提供可分辨文件夹 ID 以指定搜索位置。 当委托用户访问服务器时，将使用作为 DistinguishedFolderId 元素子元素的 Mailbox 元素显式指定要访问的委托的邮箱。

处理错误

每个程序都会不时出现错误，基于 EWS 的应用程序也不例外， (双关语意) 。 可能会在 ResponseCode EWS 元素中或 ServiceError EWS 托管 API 枚举的 中收到一些与标识符相关的错误。

EWS 托管 API 或 EWS 应用程序中可能会出现以下错误。 如果使用 EWS 托管 API 应用程序，则错误通常是属性值问题;对于 EWS 应用程序，错误与 XML 元素值或操作相关联。

表 2. 与标识符相关的错误

错误	在...	说明
ErrorCalendarCannotUseIdForOccurrenceId	OccurenceID 的值与有效的定期日历项不对应。	在请求中指定的 OccurenceId 的值在结构中可能有效，但请求无法将其与现有定期主数据库匹配。 可能会从日历中删除定期项目。 验证该项是否仍然存在，以及是否使用了正确的标识符。
ErrorCalendarCannotUseIdForRecurringMasterId	RecurringMasterId 属性不对应于 OccurrenceId 元素的有效匹配项。	在请求中指定的 定期MasterId 的值在结构中可能有效，但请求无法将其与项的现有匹配项。 项的出现可能会从日历中删除。 验证该项是否仍然存在，以及是否使用了正确的标识符。
ErrorCannotUseFolderIdForItemId	传递的 ID 表示文件夹而不是项目。	标识符的格式可能有效，但服务器对操作的预期无效。 验证是否引用了操作的正确标识符。
ErrorCannotUseItemIdForFolderId	传入的 ID 表示项目而不是文件夹。	标识符的格式可能有效，但服务器对操作的预期无效。 验证是否引用了操作的正确 ID 。
ErrorChangeKeyRequiredForWriteOperations	执行某些更新操作时，必须提供有效的更改密钥。	请求更新时省略了 ChangeKey 值，或者更改密钥不正确。 在执行更新操作时，验证是否具有正确的更改密钥。
ErrorInvalidAttachmentId	在项的附件集合中找不到附件。	如果你有附件 ID ，然后附件被删除，并且你尝试对附件 ID 调用 GetAttachment 操作 ，你可能会收到此响应代码。 验证附件集合中是否存在附件。
ErrorInvalidChangeKey	传入了无效的更改密钥。	请注意，许多操作和方法不需要传递更改密钥。 但是，如果确实提供了更改密钥，则它必须有效，尽管它不一定是最新的。
ErrorInvalidFolderId	文件夹 ID 已损坏。	确保具有格式正确且有效的标识符。
ErrorInvalidId	ID 和/或更改密钥的结构在内部不一致。	Exchange 在分析 ID 后遇到了问题。 转换中可能存在错误。 例如，如果 Outlook 中的项目有 IdFormatType.HexEntryId ，但将其转换为 EwsId，认为它是 IdFormatType.EntryId 格式，则可能会出现这种情况。 请确保使用正确的转换类型。
ErrorInvalidIdEmpty	应用程序指定的 ID 为空。	应用程序传入了标识符的空字符串。 确保具有格式正确且有效的标识符。
ErrorInvalidIdMalformed	ID 的结构在内部不一致。	Exchange 在分析 ID 后遇到了问题。 ID 可能未正确转换。 请确保使用正确的转换类型。
ErrorInvalidIdMalformedEwsLegacyIdFormat	为具有 Exchange 2007 SP1 或更高版本的请求指定了使用 Exchange 2007 格式的文件夹或项目 ID 。	不能在 Exchange 2007 SP1 或更高版本的请求中使用 Exchange 2007 ID。 必须先使用 ConvertId EWS 操作或 ConvertId EWS 托管 API 方法进行转换。
ErrorInvalidIdNotAnItemAttachmentId	AttachmentId 属性不引用项目附件。	标识符的格式可能有效，但服务器对操作的预期无效。 验证是否引用了操作的正确标识符。
ErrorInvalidIdReturnedByResolveNames	邮箱中的联系人已损坏。	ResolveNames EWS 操作或 ResolveName EWS 托管 API 方法返回了一个或多个标识符，但它们无效。 可能需要重新创建联系人。
ErrorInvalidIdStoreObjectIdTooLong	ID 的结构在内部不一致。	Exchange 在分析 ID 后遇到了问题。 ID 可能未正确转换。 请确保使用正确的转换类型。
ErrorInvalidIdTooManyAttachmentLevels	附件层次结构超过最大深度 255 个级别。	在请求中指定的 AttachmentId 属性的值在结构中可能有效，但请求的附件在层次结构中太深。 代码可能已尝试附加超出 255 个级别的限制的项。
ErrorInvalidImContactId	使用 RemoveImContactFromGroup 操作时，在 IM 组中找不到联系人时，可能会返回此错误。 此错误适用于面向从 Exchange 2013 开始的 Exchange Exchange Online和版本的客户端。	在请求中指定的 ContactId 属性的值在结构中可能有效，但邮箱中没有任何联系人与此结构匹配。 联系人可能已被删除。
ErrorInvalidImGroupId	使用 RemoveImGroup 操作时，在邮箱中找不到组时，可能会返回此错误。 此错误适用于面向从 Exchange 2013 开始的 Exchange Exchange Online和版本的客户端。	在请求中指定的 GroupId 属性的值在结构中可能有效，但邮箱中没有组与此结构匹配。 组可能已被删除。
ErrorInvalidReferenceItem	引用的项目标识符不是 MessageType 、 ExchangeWebServices.CalendarItemType 或其后代之一。 引用项标识符适用于 CalendarItemType 对象，并且组织者正在尝试 Reply 或 ReplyAll。	标识符的格式可能有效，但服务器对操作的预期无效。 验证是否引用了操作的正确标识符。
ErrorMissingManagedFolderId	缺少文件夹的策略 ID 属性、属性标记0x6732。	文件夹已损坏。 请考虑重新创建它。

转换标识符

可能需要将标识符从一种格式转换为另一种格式。 例如，可能需要将 EWS 外部的标识符（例如来自 MAPI 连接的标识符）转换为应用程序可以使用的格式。 为此，可以使用 ConvertId EWS 操作或 ConvertId EWS 托管 API 方法。

例如，EntryID 是由 MAPI 消息存储区生成的唯一标识符，在保存项目时由存储区分配。 若要在应用程序中使用 EntryID，首先需要将其转换为 EwsId。

Outlook Web App在 URL 中使用自己的标识符版本（称为 OwaId）来访问文件夹和项目。 如果应用程序需要访问 Outlook Web App 中的项，则需要将 OwaId 转换为 EwsId。

可以使用 ConvertId 操作或方法转换多种不同的标识符格式。

表 3. Exchange 中的可转换标识符格式

Format	说明
EwsLegacyId	适用于 Exchange 2007 的 EwsId。
EwsId	从 Exchange 2007 SP1 开始，适用于 exchange Exchange Online和版本的 EwsId。
StoreId	存储文件夹和项目的 Exchange 存储标识符。
OwaId	exchange 2007 和 Exchange 2010 中用于 Outlook Web App 的Outlook Web App标识符。 注意：从 Exchange 2013 开始的Exchange Online和 Exchange 版本使用 EwsId Outlook Web App。
EntryId	通常称为 MAPI 消息的 PR_ENTRYID 属性的 MAPI 标识符。
HexEntryId	用于可用性日历事件标识符的 PR_ENTRYID 属性的十六进制编码表示形式。 这也是 Outlook 使用的标识符格式。

另请参阅

• 开发 Exchange Web 服务客户端
• ConvertId 操作
• ServiceError 枚举
• 使用 Exchange 中的 EWS 删除项目