Свойства и расширенные свойства в веб-службах Exchange
Узнайте, как определить свойства элементов и папок и получить доступ к ней с помощью EWS в Exchange.
Почтовый ящик Exchange содержит большое количество элементов, включая сообщения электронной почты, встречи, собрания и т. д. Эти элементы состоят из свойств; свойства описывают элементы. Свойства элемента можно использовать для выполнения поиска, синхронизации изменений элементов и создания настраиваемых типов свойств. В этой статье содержатся общие сведения о свойствах и способах работы со свойствами в приложении.
Свойства элемента Exchange
Элементы и папки в Exchange по сути являются строками в таблицах. Основным свойством, определяющим элемент или папку, является идентификатор EWS. Хотя в базе данных Exchange существуют и другие свойства, связанные с идентификаторами, для EWS идентификатор EWS выступает в качестве первичного ключа для коллекции свойств, описывающих элемент. Свойство идентификатора EWS содержит две части:
Свойство ChangeKey , содержащее сведения о том, изменился ли элемент или папка.
Все элементы в почтовом ящике хранятся в одной базе данных Exchange и используют одну и ту же схему базы данных. Элементы отличаются сочетанием свойства ItemClass , ограничений свойств и уровней бизнес-логики, которые влияют на управление ими в хранилище Exchange. В таблице 1 показано, как свойства применяются к разным типам элементов; в этом примере сообщения электронной почты и встречи. Оба элемента имеют значение свойства Subject . Но обратите внимание, что свойство IsAllDayEvent не задано для элемента электронной почты, а свойство IsReadReceiptRequested не задано для встречи. К счастью, вам не нужно знать, какие свойства применимы для каждого класса элементов. EWS обрабатывает это за вас.
Таблица 1. Сравнение свойств встречи и электронной почты
| Тип элемента | Класс Item | Тема | IsAllDayEvent | IsReadReceiptRequested |
|---|---|---|---|---|
| Электронная почта |
IPM.Note |
Отчет о состоянии: project X complete |
NULL |
true |
| Appointment |
IPM.Appointment |
Собрание компании Contoso |
false |
NULL |
Схема EWS поддерживает многие ограничения, управляемые базой данных Exchange и уровнями бизнес-логики между EWS и базой данных Exchange. Схема EWS применяет определенный набор свойств к каждому типу элементов. Ниже приведены строго типизированные элементы базы данных Exchange, предоставляемые EWS:
Сообщения электронной почты.
Встречи
Контакты
Списки рассылки
Сообщения о собрании
приглашения на собрания;
Ответы на собрания
Отмены собраний
Задачи
Публикация элементов
Универсальные элементы возвращаются службой EWS в виде сообщений электронной почты. Управляемый API EWS реализует все эти типы элементов.
Примечание.
Объекты ответа отправляются клиентом на сервер только в ответ на элементы, полученные от других пользователей. Они не существуют в базе данных Exchange.
Что такое свойства в EWS?
Схема EWS описывает данные, отправляемые между клиентом EWS и Exchange. Большая часть схемы описывает свойства элементов и папок, к которым можно получить доступ в базе данных Exchange. Схема EWS описывает XML-представление свойств базы данных Exchange, доступных вашему приложению. Фактические свойства, с точки зрения доступных свойств, их формы и возвращаемых значений, зависят от того, что вы пытаетесь сделать. Например, свойство Body возвращает только первые 512 символов в операции FindItem , но операция GetItem возвращает полный текст элемента. Хотя большинство свойств можно задать и получить, некоторые свойства задаются только Exchange. Каждое свойство существует в схеме в формате XML, который либо отражает свойство в том виде, в который оно хранится в базе данных Exchange, либо вычисляется на основе свойств, хранящихся в базе данных Exchange. Свойство Subject является примером свойства settable; Свойство UnreadCount в папке является примером вычисляемого свойства. Основной набор свойств является общим для основных типов элементов.
Набор свойств, полученный приложением из Exchange, определяют следующие факторы:
Операция, вызываемая приложением
Базовая фигура отклика
Тип элемента
Указанные пути к свойствам
Важно понимать, как эти различные факторы влияют на данные, к которым можно получить доступ. Как и в примере свойства Body , упомянутого ранее, некоторые сведения условно доступны в зависимости от различных факторов. Понимание этих факторов может сэкономить время, помогая выбрать правильные варианты для доступа к нужной информации. Чтобы узнать, какие свойства доступны, необходимо проверить эти факторы, чтобы определить, как получить доступ к свойствам, необходимым приложению. В этом разделе описывается, как эти различные факторы влияют на то, какие свойства возвращаются в ответах EWS.
Фигуры ответов EWS
Exchange хранит много информации о элементах. Иногда приложению не нужны все эти сведения, и во многих случаях лучше не получать все это. Фигуры ответов EWS, также называемые фигурами свойств, указывают, какие свойства возвращаются с сервера. Основным элементом фигуры ответа является базовая фигура. Базовая фигура — это набор свойств по умолчанию для строго типизированных элементов. Управляемый API EWS, эквивалентный базовой фигуре, является BasePropertySet. EWS включает три фигуры ответа по умолчанию.
Табл. 2. Фигуры ответа по умолчанию
| Имя фигуры ответа по умолчанию | Эквивалент управляемого API EWS | Описание |
|---|---|---|
| IdOnly |
Значение BasePropertySet.IdOnly |
Возвращаются только идентификатор EWS и ключ изменения. Если клиент не использует все свойства, возвращаемые фигурой AllProperties или Default, используйте фигуру IdOnly и укажите дополнительные свойства, используя путь к свойству, заданный в классе PropertySet . Большинство приложений должны использовать фигуру ответа IdOnly с указанными дополнительными свойствами. Это уменьшает объем неиспользуемых данных, запрашиваемых клиентами. |
| По умолчанию |
Недоступно |
Набор стандартных свойств для типа элемента. Используйте эту фигуру ответа, только если приложение использует все свойства. |
| AllProperties |
Значение BasePropertySet.FirstClassProperties |
Больший набор свойств, чем фигура по умолчанию. Хотя имя подразумевает это, этот параметр не возвращает все свойства элемента. Этот набор свойств возвращает свойства, которые клиентские приложения используют чаще всего. Если вам нужны дополнительные свойства, их можно запросить по пути к свойству. Если приложение не использует все свойства, возвращаемые этой фигурой ответа, используйте фигуру ответа IdOnly с указанными дополнительными свойствами. |
Многие операции EWS возвращают элементы и их свойства. Независимо от указанных фигур ответа различные операции могут возвращать разные наборы свойств. Различные типы элементов также возвращают разные свойства в зависимости от операции и указанной формы ответа. В следующих операциях для определения возвращаемых свойств используются фигуры ответов.
Табл. 3. Операции, использующие фигуры ответа
Фигуры свойств — это один из рудиментных способов определения свойств, возвращаемых приложением. Однако иногда приложению требуется более уточненный набор конкретных свойств. Для этого можно использовать путь к свойству.
Выбор свойств по пути к свойству
Путь к свойству EWS — это метаданные, которые используются для идентификации свойств в запросе или ответе.
Табл. 4. Типы путей к свойствам
| Тип пути к свойству | Тип схемы | Реализация управляемого API EWS | Описание |
|---|---|---|---|
| FieldUri |
PathToUnindexedFieldType |
Типы, наследуемые от ServiceObjectSchema. |
Наиболее распространенный путь к свойству. Пути свойств FieldUri указываются в объекте PropertySet в управляемом API EWS. Большинство свойств EWS можно указать с помощью пути к свойству FieldUri. Это описано в unindexedFieldURIType в схеме EWS. XML-путь к свойству FieldUri выглядит следующим образом: XML<FieldURI FieldURI="item:Subject"/>Этот путь к свойству эквивалентен ItemSchema.Subject в управляемом API EWS. |
| IndexedFieldUri |
PathToIndexedFieldType |
Типы, наследуемые от ItemSchema. |
Определяет свойства словаря, для которых требуется индекс свойств для указания возвращаемого значения. Используйте этот путь, если свойство может иметь несколько значений. Это описывается свойством DictionaryURIType в схеме EWS. Пути к свойствам DictionaryURIType указываются в объекте PropertySet в управляемом API EWS. XML-путь к свойству IndexedFieldUri выглядит следующим образом: XML<IndexedFieldURI FieldURI="contacts:PhysicalAddress:Street FieldIndex="Home"/> |
| ExtendedFieldUri |
PathToExtendedFieldType |
ExtendedPropertyDefinition |
Определяет расширенное определение свойства, которое определяет пользовательские или не-схематизированные свойства элементов. XML-путь к свойству ExtendedFieldUri выглядит следующим образом: XML<ExtendedFieldURI> PropertyTag="0x1234" PropertyType="Integer" /> |
| ExceptionFieldUri |
ExceptionFieldURI |
ServiceResponse |
Указывает свойства, связанные с ошибкой в ответе EWS. Это описывается типом ExceptionPropertyURIType в схеме EWS. Это происходит только в элементе MessageXml ответов об ошибках, возникающих при работе с шаблонами повторения календаря. |
Рекомендуется при запросе свойств использовать базовую фигуру IdOnly (BasePropertySet.IdOnly в управляемом API EWS), а затем запрашивать только свойства, необходимые приложению, указав пути к свойствам.
Схематизированные свойства
Большинство свойств, необходимых клиенту EWS, описаны в схеме EWS. Основные определения папок и типов элементов, которые содержат определения свойств, находятся в схеме types.xsd. Следующие типы схем содержат определения свойств для большинства объектов, которые можно использовать.
Табл. 5. Типы схем, содержащие определения свойств
| Тип схемы EWS | Эквивалент типа управляемого API EWS | Определяет... |
|---|---|---|
| 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 type. |
| FolderType |
Класс folder |
Набор свойств типа папки. |
| CalendarFolderType |
Класс CalendarFolder |
Свойство типа SearchFolder задано. |
| ContactsFolderType |
Класс ContactsFolder |
Свойство contactsFolder type set. |
| SearchFolderType |
Класс SearchFolder |
Свойство типа SearchFolder задано. |
| TasksFolderType |
Класс TasksFolder |
TasksFolder type property set. |
| UserConfigurationType |
Класс UserConfiguration |
Набор свойств типа UserConfiguration. |
Хотя свойств в схеме EWS достаточно для многих приложений, некоторые сценарии нельзя реализовать, используя только то, что описано в схеме. Для этих сценариев можно расширить свойства.
Расширенные свойства (не-схематизированные свойства)
Расширенные свойства позволяют создавать пользовательские свойства, которые предоставляют доступ к свойствам элементов и папок в хранилище Exchange, которые не определены в схеме EWS. Их можно использовать для доступа к собственным свойствам элемента MAPI и папки в базе данных Exchange. Для доступа ко всем схематизированным свойствам можно использовать расширенные свойства, так как в описании эти схематизированные свойства являются не чем иным, как свойства MAPI в базе данных Exchange.
Тип схемы PathToExtendedFieldType, расположенный в схеме types.xsd, определяет XML-код, представляющий расширенное свойство. Этот тип схемы определяет элемент ExtendedFieldURI в экземплярах XML; иными словами, он определяет XML-код, отправляемый между службой и клиентом. Тип схемы ExtendedPropertyType определяет как элемент ExtendedFieldURI , так и значение или массив значений, содержащихся в расширенном свойстве. В следующей таблице показано приблизительное сопоставление расширенного свойства XML и его реализация в элементах управляемого API EWS.
Табл. 6. Расширенный XML-код свойства, реализованный в управляемом API EWS
| Реализация управляемого API EWS | Что в ней содержится | Что сопоставляется с |
|---|---|---|
| Свойство Item.ExtendedProperties |
Коллекция расширенных свойств элемента. |
Один или несколько экземпляров расширенных свойств элемента. |
| Класс ExtendedProperty |
Расширенное определение и значения свойства. |
Тип схемы ExtendedPropertyType. |
| Класс ExtendedPropertyDefinition |
Расширенное определение свойства. |
Тип схемы PathToExtendedFieldType. |
Если вы хотите узнать больше о том, как можно использовать расширенные свойства в приложении, ознакомьтесь со следующими примерами кода:
Exchange 2013: программная подготовка пользовательских X-заголовков
Exchange 2013: доступ к именованным свойствам по его идентификатору
Exchange 2013: доступ к свойству по идентификатору GUID и имени набора свойств
Exchange 2013: создание настраиваемых расширенных свойств программным способом