Идентификаторы EWS в Exchange
Узнайте об идентификаторах в Exchange и о том, как их можно использовать в управляемых API EWS и приложениях EWS.
Каждый объект в хранилище Exchange имеет уникальный идентификатор. Идентификатор объекта можно использовать для ссылки на объект и для его отличия от других объектов. Двумя наиболее распространенными идентификаторами, с которыми можно работать, являются идентификаторы папок и элементов.
Чтобы понять идентификаторы и их важность для приложения, полезно понять связь между объектами в Exchange. Когда управляемый API EWS или приложение EWS взаимодействует с Exchange, вы работаете с иерархией объектов, которая включает объекты почтовых ящиков, папок и элементов. Хранилищем может быть любой из этих типов объектов. Чаще всего это почтовый ящик на сервере Exchange Server, но он также может быть общедоступной папкой на сервере Exchange Server. (Имейте в виду, что в Exchange Online Exchange Online как часть Office 365, а версии Exchange, начиная с Exchange 2013, общедоступные папки являются еще одним типом почтового ящика, а не другим типом хранилища.) Хранилище содержит папки, а папки содержат элементы, и каждая из этих папок и элементов имеет идентификатор, как показано на следующем рисунке.
Рис. 1. Иерархия почтовых ящиков, папок и элементов
Идентификаторы EWS
Идентификаторы, которые EWS использует для папок и элементов, называются идентификаторами EWS или EwsIds. EwsIds можно найти во многих различных объектах в EWS, но они называются другими для разных объектов. Так как вы можете использовать эти объекты в приложении, необходимо понять, как идентификаторы этих объектов связаны с EwsId.
Идентификаторы в EWS также применимы к управляемому API EWS. В управляемом API EWS идентификаторы являются свойствами объектов и внутренне управляются для сопоставления с элементами EWS.
Таблица 1. Идентификаторы объектов в EWS
| Object | Идентификатор | Как это связано с EwsId? |
|---|---|---|
| CalendarItem |
Дочерний элемент ItemId содержит уникальный идентификатор элемента календаря. |
Дочерний элемент ItemId совпадает с EwsId для этого элемента. |
| ConversationId |
Атрибут Id содержит идентификатор беседы, в которую входит этот элемент. |
Атрибут Id совпадает с EwsId для этого элемента. |
| AttachmentId |
Предоставляет уникальный идентификатор вложения. Атрибут RootItemId содержит уникальный идентификатор элемента корневого хранилища, к которому присоединено вложение. |
Вложения могут быть другими элементами в хранилище Exchange. В этом случае AttachmentId совпадает с EwsId. Во всех случаях RootItemId является EwsId, так как ссылается на элемент в хранилище. |
| PersonaId |
Атрибут Id возвращает строку, содержащую идентификатор persona. |
Атрибут Id совпадает с EwsId для persona. |
| ContactId |
Атрибут Id возвращает строку, содержащую идентификатор контакта. |
Атрибут Id совпадает с EwsId для контакта. |
| GroupId |
Атрибут Id возвращает строку, содержащую идентификатор группы. |
Атрибут Id совпадает с EwsId для группы. |
| AssociatedCalendarItemId |
Атрибут Id определяет элемент календаря, связанный с MeetingMessage, MeetingRequest, MeetingResponse или MeetingCancellation. |
Атрибут Id совпадает с EwsId для элемента календаря. |
| UserConfigurationProperties |
Значение Id для этого элемента указывает свойство идентификатора. |
Этот идентификатор не сопоставляется напрямую с EwsId, так как он является идентификатором свойства, а не элементом. |
| OccurrenceItemId |
Атрибут RecurringMasterId идентифицирует хозяин повторяющегося элемента. |
Значение OccurrenceItemId не сопоставляется напрямую с EwsId, но Значение RecurringMasterId делает, так как ссылается на объект верхнего уровня повторяющегося элемента. |
| StoreEntryId |
Содержит идентификатор элемента в хранилище Exchange. |
Значение StoreEntryId не сопоставляется с EwsId, но дает идентификатор хранилища, в котором хранятся элементы. |
Работа с идентификаторами
Сервер Exchange обрабатывает идентификаторы различными способами. При разработке управляемого API EWS или приложения EWS учитывайте следующее:
Значение элемента ItemID для папок и элементов учитывает регистр. Если вы посмотрите на идентификатор элемента для папки или элемента, возвращаемого операцией FindItem (или методом Управляемого API FindItems EWS), вы можете подумать, что это дубликат другого идентификатора элемента; однако один или несколько символов в идентификаторах элементов для двух элементов будут иметь другой регистр.
Если вы собираетесь сохранить идентификатор элемента в базе данных для получения позже, рекомендуется, чтобы размер поля был 512 байт, чтобы оно было достаточно большим для хранения GUID.
Не предполагайте, что идентификатор элемента всегда будет действителен, если вам потребуется получить элемент позже. Если элемент перемещается в хранилище, идентификатор может измениться из-за способа обработки перемещения. Элемент фактически копируется, создается новый идентификатор, после чего исходный элемент удаляется. Обратите внимание, что идентификаторы папок неизменяемы и не изменяются при перемещении в хранилище.
Идентификаторы в Exchange непрозрачны. Например, EwsId создается из нескольких фрагментов информации, которые не важны для разработчика, но важны для Exchange.
При работе с элементами в Exchange еще одно значение, которое следует иметь в виду, — это атрибут ChangeKey . Это значение, в дополнение к идентификатору элемента, используется для отслеживания состояния элемента. При каждом изменении элемента создается новый ключ изменения. Например, при выполнении операции UpdateItem можно использовать атрибут ChangeKey , чтобы сообщить серверу, что обновление применяется к последней версии элемента. Если другое приложение внесло изменения в обновляемый элемент, ключи изменения не будут совпадать, и вы не сможете выполнить обновление.
Различающиеся идентификаторы папок
Exchange включает ряд предопределенных папок почтовых ящиков, каждой из которых назначается идентификатор, известный как идентификатор различающейся папки. Они определяются перечислением EWS Managed API WellKnownFolderName и элементом EWS DistinguishedFolderId . Эти различающиеся идентификаторы папок можно использовать для упрощения ссылок на одну из предопределенных папок. Например, для папки "Входящие" можно просто использовать "Входящие" в качестве идентификатора, а не определять идентификатор папки.
Другие папки, создаваемые для упорядочения элементов электронной почты, также имеют уникальный идентификатор этой папки. Этот идентификатор не меняется, даже если вы изменяете другие свойства папки.
В качестве точки входа для делегированного доступа можно использовать различающиеся идентификаторы папок. При инициации делегированного доступа выполняется поиск элементов или папок и предоставляется идентификатор различающейся папки, чтобы указать, где искать. Когда пользователь-делегат обращается к серверу, элемент Mailbox , который является дочерним элементом элемента DistinguishedFolderId , используется для явного указания почтового ящика для доступа делегата.
Обработка ошибок
Каждая программа должна время от времени получать ошибку, и приложения на основе EWS не являются исключением (каламбур). Вы можете получить некоторые ошибки, связанные с идентификаторами, в элементе ResponseCode EWS или в составе перечисления Управляемого API ServiceError EWS.
В управляемом API EWS или приложении EWS могут возникнуть следующие ошибки. Если вы работаете с приложением управляемого API EWS, обычно ошибки связаны со значениями свойств. Для приложений EWS ошибки связаны со значениями или операциями xml-элементов.
Табл. 2. Ошибки, связанные с идентификатором
| Ошибка | Происходит, когда... | Описание |
|---|---|---|
| ErrorCalendarCannotUseIdForOccurrenceId |
Значение OccurenceID не соответствует допустимому повторяющимся элементу календаря. |
Значение occurenceId , указанное в запросе, может быть допустимым в структуре, но запрос не может сопоставить его с существующим повторяющимся хозяином. Повторяющийся элемент может быть удален из календаря. Убедитесь, что элемент по-прежнему существует и используется правильный идентификатор. |
| ErrorCalendarCannotUseIdForRecurringMasterId |
Атрибут RecurringMasterId не соответствует допустимому вхождаемости элемента OccurrenceId . |
Значение Параметра RecurringMasterId , указанное в запросе, может быть допустимым в структуре, но запрос не может сопоставить его с существующим вхождением элемента. Вхождение элемента может быть удалено из календаря. Убедитесь, что элемент по-прежнему существует и используется правильный идентификатор. |
| ErrorCannotUseFolderIdForItemId |
Переданный идентификатор представляет папку, а не элемент. |
Идентификатор может быть допустимым в формате, но не в том, что сервер ожидал для операции. Убедитесь, что вы ссылаетесь на правильный идентификатор для операции. |
| ErrorCannotUseItemIdForFolderId |
Переданный идентификатор представляет элемент, а не папку. |
Идентификатор может быть допустимым в формате, но не в том, что сервер ожидал для операции. Убедитесь, что вы ссылаетесь на правильный идентификатор операции. |
| ErrorChangeKeyRequiredForWriteOperations |
При выполнении определенных операций обновления необходимо указать допустимый ключ изменения. |
Значение ChangeKey было пропущено при запросе обновления, либо ключ изменения был неверным. Убедитесь, что у вас есть правильный ключ изменения при выполнении операций обновления. |
| ErrorInvalidAttachmentId |
Вложение не найдено в коллекции вложений для элемента. |
Этот код ответа может быть получен, если у вас есть идентификатор вложения, а затем вложение удаляется и вы пытаетесь вызвать операцию GetAttachment для идентификатора вложения. Убедитесь, что вложение существует в коллекции вложений. |
| ErrorInvalidChangeKey |
Передан недопустимый ключ изменения. |
Обратите внимание, что для многих операций и методов не требуется передавать ключ изменения. Однако если вы предоставите ключ изменения, он должен быть действительным, хотя он не обязательно должен быть актуальным. |
| ErrorInvalidFolderId |
Идентификатор папки поврежден. |
Убедитесь, что у вас есть правильно отформатированный и допустимый идентификатор. |
| ErrorInvalidId |
Структура идентификатора и (или) ключа изменения внутренне несогласованна. |
После синтаксического анализа в Exchange возникла проблема с идентификатором . Возможно, в преобразовании произошла ошибка. Это может произойти, например, если у вас есть idFormatType.HexEntryId для элемента в Outlook, но вы преобразуете его в EwsId, думая, что это формат IdFormatType.EntryId . Убедитесь, что используется правильный тип преобразования. |
| ErrorInvalidIdEmpty |
Приложение указало пустой идентификатор . |
Приложение передает пустую строку для идентификатора. Убедитесь, что у вас есть правильно отформатированный и допустимый идентификатор. |
| ErrorInvalidIdMalformed |
Структура идентификатора внутренне несогласовна. |
После синтаксического анализа в Exchange возникла проблема с идентификатором . Возможно, идентификатор был преобразован неправильно. Убедитесь, что используется правильный тип преобразования. |
| ErrorInvalidIdMalformedEwsLegacyIdFormat |
Идентификатор папки или элемента, использующий формат Exchange 2007, был указан для запроса с версией Exchange 2007 с пакетом обновления 1 (SP1) или более поздней. |
Нельзя использовать идентификаторы Exchange 2007 в запросах Exchange 2007 с пакетом обновления 1 (SP1) или более поздней версии. Для их преобразования сначала необходимо использовать операцию ConvertId EWS или метод ConvertId EWS Managed API. |
| ErrorInvalidIdNotAnItemAttachmentId |
Свойство AttachmentId не ссылается на вложение элемента. |
Идентификатор может быть допустимым в формате, но не в том, что сервер ожидал для операции. Убедитесь, что вы ссылаетесь на правильный идентификатор для операции. |
| ErrorInvalidIdReturnedByResolveNames |
Контакт в почтовом ящике поврежден. |
Операция ResolveNames EWS или метод Managed API ResolveName EWS вернули один или несколько идентификаторов, но они недопустимы. Возможно, потребуется повторно создать контакт. |
| ErrorInvalidIdStoreObjectIdTooLong |
Структура идентификатора внутренне несогласовна. |
После синтаксического анализа в Exchange возникла проблема с идентификатором . Возможно, идентификатор был преобразован неправильно. Убедитесь, что используется правильный тип преобразования. |
| ErrorInvalidIdTooManyAttachmentLevels |
Иерархии вложений превышают максимум 255 уровней глубины. |
Значение свойства AttachmentId , указанное в запросе, может быть допустимым в структуре, но запрошенное вложение слишком глубоко в иерархии. Возможно, код пытался прикрепить элемент, превышающий ограничение в 255 уровней. |
| ErrorInvalidImContactId |
Эта ошибка может быть возвращена, если не удается найти контакт в группе обмена мгновенными сообщениями при использовании операции RemoveImContactFromGroup. Эта ошибка применяется к клиентам, предназначенным для Exchange Online и версий Exchange, начиная с Exchange 2013. |
Значение свойства ContactId , указанное в запросе, может быть допустимым в структуре, но никакие контакты в почтовом ящике не соответствуют этой структуре. Возможно, контакт уже удален. |
| ErrorInvalidImGroupId |
Эта ошибка может быть возвращена, если не удается найти группу в почтовом ящике при использовании операции RemoveImGroup. Эта ошибка применяется к клиентам, предназначенным для Exchange Online и версий Exchange, начиная с Exchange 2013. |
Значение свойства GroupId , указанное в запросе, может быть допустимым в структуре, но никакие группы в почтовом ящике не соответствуют этой структуре. Возможно, группа уже удалена. |
| ErrorInvalidReferenceItem |
Идентификатор элемента, на который указывает ссылка, не является MessageType или ExchangeWebServices.CalendarItemTypeType или одним из их потомков. Идентификатор ссылочного элемента предназначен для объекта CalendarItemType , и организатор пытается ответить или ReplyAll. |
Идентификатор может быть допустимым в формате, но не в том, что сервер ожидал для операции. Убедитесь, что вы ссылаетесь на правильный идентификатор для операции. |
| ErrorMissingManagedFolderId |
Свойство идентификаторов политики, тег свойства 0x6732 для папки отсутствует. |
Папка повреждена. Попробуйте воссоздать его. |
Преобразование идентификаторов
Может потребоваться преобразовать идентификатор из одного формата в другой. Например, может потребоваться преобразовать идентификатор извне EWS, например идентификатор, поступающий из подключения MAPI, в формат, который может использовать приложение. Для этого можно использовать операцию ConvertId EWS или метод ConvertId EWS Managed API.
Например, EntryID — это уникальный идентификатор, созданный хранилищем сообщений MAPI, который назначается хранилищем при сохранении элемента. Чтобы использовать EntryID в приложении, сначала необходимо преобразовать его в EwsId.
Outlook Web App использует собственную версию идентификаторов, называемую OwaId, в URL-адресах для доступа к папкам и элементам. Если приложению требуется доступ к элементам в Outlook Web App, необходимо преобразовать OwaId в EwsId.
Для преобразования нескольких различных форматов идентификаторов можно использовать операцию или метод ConvertId .
Табл. 3. Форматы преобразуемых идентификаторов в Exchange
| Format | Описание |
|---|---|
| EwsLegacyId |
EwsId, который применяется к Exchange 2007. |
| EwsId |
EwsId, который применяется к Exchange Online и версиям Exchange, начиная с Exchange 2007 с пакетом обновления 1 (SP1). |
| Storeid |
Идентификатор хранилища Exchange, в котором хранятся папки и элементы. |
| OwaId |
Идентификатор Outlook Web App, используемый с Outlook Web App в Exchange 2007 и Exchange 2010. ПРИМЕЧАНИЕ. Exchange Online и версии Exchange, начиная с Exchange 2013, используют EwsId для Outlook Web App. |
| EntryId |
Идентификатор MAPI, который обычно называется свойством PR_ENTRYID сообщения MAPI. |
| HexEntryId |
Шестнадцатеричное представление свойства PR_ENTRYID , используемого для идентификатора события календаря доступности. Это также формат идентификатора, который использует Outlook. |