Общие сведения о расширенных свойствах Outlook

  • Статья

Пространство имен: microsoft.graph

Расширенные свойства позволяют хранить пользовательские данные и, в частности, служат резервным механизмом для приложений для доступа к пользовательским данным для свойств MAPI Outlook, если эти свойства еще не предоставляются в API Graph metadata_ Майкрософт. Можно использовать расширенные свойства API REST, чтобы хранить или получать такие пользовательские данные в следующих пользовательских ресурсах:

Или в следующих ресурсах группы Microsoft 365:

Что использовать — расширенные свойства или открытые расширения

В большинстве распространенных сценариев вы должны иметь возможность использовать открытые расширения (представленные openTypeExtension, ранее известные как расширения данных Office 365) для хранения пользовательских данных для экземпляров ресурсов в почтовом ящике пользователя и доступа к ней. Используйте расширенные свойства, только если требуется доступ к пользовательским данным для свойств MAPI Outlook, которые еще не представлены в метаданных Microsoft API Graph.

Типы расширенных свойств

В зависимости от того, собираетесь ли вы хранить одно или несколько значений (одинакового типа) в расширенном свойстве, можно создавать расширенное свойство singleValueLegacyExtendedProperty или multiValueLegacyExtendedProperty.

Каждый из этих типов определяет свойство по идентификатору id и хранит данные в значении value.

Можно использовать идентификатор id для получения конкретного экземпляра ресурса с расширенным свойством или фильтровать расширенное свойство с одним значением для получения всех экземпляров с таким свойством.

Примечание Вы не можете использовать REST API для получения всех расширенных свойств конкретного экземпляра в одном вызове.

Форматы идентификаторов

Идентификатор расширенного свойства можно указать в одном из трех форматов:

  • Как именованное свойство, определенное по типу расширенного свойства, пространству имен и имени строки.
  • Как именованное свойство, определенное по типу расширенного свойства, пространству имен и числовому идентификатору.
  • В формате proptag, определенном по типу расширенного свойства и тегу свойства MAPI.

В следующих двух таблицах описаны эти форматы, применяемые к расширенным свойствам с одним и несколькими значениями. {тип} представляет собой тип значения или значений расширенного свойства. В примерах показаны типы string, integer и массивы этих типов.

Действительные форматы идентификаторов для расширенных свойств с одним значением

Формат Пример Описание
"{тип} {guid} Name {имя}" "String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Определяет свойство по пространству имен (GUID), к которому оно принадлежит, и имени строки.
"{тип} {guid} Id {идентификатор}" "Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012" Определяет свойство по пространству имен (GUID), к которому оно принадлежит, и числовому идентификатору.
"{тип} {proptag}" "String 0x4001" Определяет предопределенное свойство по тегу свойства.

Действительные форматы идентификаторов для расширенных свойств с несколькими значениями

Формат Пример Описание
"{тип} {guid} Name {имя}" "StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Определяет свойство по пространству имен (GUID) и имени строки.
"{тип} {guid} Id {идентификатор}" "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" Определяет свойство по пространству имен (GUID) и числовому идентификатору.
"{тип} {proptag}" "StringArray 0x4002" Определяет предопределенное свойство по тегу свойства.

Чтобы определить расширенное свойство с одним или несколькими значениями в качестве настраиваемого свойства, используйте любой из форматов именованных свойств. Первый из двух форматов, который использует имя строки (Name), является предпочтительным для упрощения ссылки. У именованных свойств есть идентификаторы свойств в диапазоне 0x8000-0xfffe.

Используйте формат proptag для доступа к свойствам, предопределенным MAPI, клиентом или сервером, которые еще не были предоставлены в Microsoft Graph. У этих свойств есть идентификаторы в диапазоне 0x0001-0x7fff. Не пытайтесь определить пользовательское свойство с помощью формата proptag.

Сведения о сопоставлении расширенного свойства с существующим свойством MAPI, такие как идентификатор свойства и GUID, можно найти в разделе Microsoft Corporation [MS-OXPROPS] "Список основных свойств протоколов Exchange Server".

Примечание. После выбора формата для свойства id получайте доступ к этому расширенному свойству, используя только этот формат.

Операции с API REST

Ниже приведены операции с расширенными свойствами с одним значением.

Ниже приведены операции с расширенными свойствами с несколькими значениями.