Ссылка на расширенные свойства Outlook REST API (версия 2.0)

Статья
06/30/2018

Расширенные свойства REST API Outlook позволяют приложениям хранить пользовательские данные и предоставляют им резервный механизм для доступа к этим данным для свойств MAPI Outlook, когда эти свойства еще не предоставлены при помощи метаданных API REST Outlook. Расширенные свойства API можно использовать для сохранения или получения таких пользовательских данных в сообщении, почтовой папке, событии, календаре, папке контактов, задаче или папке задач в учетной записи вошедшего пользователя. Учетная запись может быть учетной записью Office 365 или Майкрософт (Hotmail.com, Live.com, MSN.com, Outlook.com и Passport.com).

Примечание

Для упрощения в остальной части этой статьи при упоминании «Outlook.com» также подразумеваются и эти домены учетной записи Майкрософт.

Не интересуетесь API версии 2.0? В оглавлении слева перейдите к разделу Справка по API Office 365 и выберите нужную версию.

Использование расширенных свойств REST API

Расширенные свойства или модули обработки данных?

Используйте расширенные свойства и соответствующий REST API, чтобы получить доступ к пользовательским данным для свойств MAPI Outlook, которые еще не предоставлены при помощи метаданных API REST Outlook. В большинстве случаев необходимо использовать модули расширения данных Office 365 и соответствующий REST API для хранения пользовательских данных и доступа к ним для элементов в почтовом ящике пользователя. Можно проверить, какие свойства предоставляются с помощью метаданных, на странице https://outlook.office.com/api/{version}/$metadata, заменив {version} на нужную версию (v2.0, beta и т. д.).

Проверка подлинности

Как и для других REST API Outlook, для каждого запроса к API расширенных свойств необходимо включать допустимый маркер доступа. Получение маркера доступа требует, чтобы вы зарегистрировались и идентифицировали свою программу и получили соответствующее разрешение.

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

Версия API

Этот API был повышен с предварительной версии до общедоступной версии. Он поддерживается в версии 2.0 и бета-версии REST API Outlook.

Поддерживаемые ресурсы REST

Вы можете создавать расширения для экземпляров следующих ресурсов:

Ресурс должен находиться в почтовом ящике зарегистрированного пользователя в Office 365 или Outlook.com.

Параметры URL-адреса

В примерах этой статьи в параметрах URL-адресов запроса REST используются следующие заполнители ИД. Необходимо указать ИД экземпляра ресурса, для которого нужно создать расширение.

Параметр	Тип	Описание
Параметры URL-адреса
calendar_id	string	Идентификатор календаря.
contact_id	string	Идентификатор контакта.
contactFolder_id	string	Идентификатор папки контактов.
event_id	string	Идентификатор события.
mailFolder_id	string	Идентификатор почтовой папки.
message_id	string	Идентификатор сообщения.
propertyId_value	string	Значение PropertyId в одном из поддерживаемых форматов.
property_value	string	Значение расширенного свойства.
task_id	string	Идентификатор задачи.
taskFolder_id	string	Идентификатор папки задач.

Дополнительные сведения, общие для всех подразделов REST API Outlook, см. в разделе Использование REST API Outlook.

Обзор

Можно динамически создавать и хранить данные в расширенном свойстве экземпляра специального символа. В зависимости от того, собираетесь ли вы хранить одно или несколько значений (одинакового типа), можно создать расширенное свойство SingleValueLegacyExtendedProperty, или MultiValueLegacyExtendedProperty.

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

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

Примечание

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

Форматы PropertyId

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

Поскольку расширенные свойства в большинстве случаев взаимодействуют с определенными свойствами MAPI, не представленными в метаданных Outlook REST API, выбранный вами формат должен отражать формат идентификатора свойства MAPI (строка символов или числовое значение). Информацию о соответствии расширенных свойств и существующих свойств MAPI, таких как идентификатор свойства и GUID можно найти в статье [MS-OXPROPS] Microsoft Corporation Список свойств главных протоколов Exchange Server.

Примечание

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

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

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

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

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

Операции с расширенными свойствами

Создание расширенного свойства в существующем элементе
Создание расширенного свойства в новом элементе
Возврат элемента с расширенным свойством
Фильтр для расширенного свойства с одним значением

Создание расширенного свойства в существующем элементе

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

PATCH https://outlook.office.com/api/v2.0/me/messages('{message_id}')
PATCH https://outlook.office.com/api/v2.0/me/events('{event_id}')
PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')
PATCH https://outlook.office.com/api/v2.0/me/tasks('{task_id}')
PATCH https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')
PATCH https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')
PATCH https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')
PATCH https://outlook.office.com/api/v2.0/me/taskfolders('{taskFolder_id}')

Минимальная требуемая область

Одна из следующих областей для чтения и записи, соответствующих целевому ресурсу:

https://outlook.office.com/mail.readwrite
https://outlook.office.com/calendars.readwrite
https://outlook.office.com/contacts.readwrite
https://outlook.office.com/tasks.readwrite
wl.imap
wl.calendars_update
wl.events_create
wl.contacts_create

Параметр	Тип	Описание
Параметры текста
SingleValueExtendedProperties	Коллекция (SingleValueLegacyExtendedProperty)	Массив из одного или нескольких расширенных свойств с одним значением.
PropertyId	string	Укажите это значение для каждого свойства в коллекции SingleValueExtendedProperties, чтобы определить свойство. Оно должно быть указано в одном из форматов, поддерживаемых для расширенных свойств с одним значением. Обязательный параметр.
Значение	string	Укажите значение для каждого свойства в коллекции SingleValueExtendedProperties. Обязательный параметр.
MultiValueExtendedProperties	Коллекция (MultiValueLegacyExtendedProperty)	Массив из одного или нескольких расширенных свойств с несколькими значениями.
PropertyId	string	Укажите это значение для каждого свойства в коллекции MultiValueExtendedProperties, чтобы определить свойство. Оно должно быть указано в одном из форматов, поддерживаемых для расширенных свойств с несколькими значениями. Обязательный параметр.
Значение	Collection(string)	Укажите значения для каждого свойства в коллекции MultiValueExtendedProperties. Обязательный параметр.

Пример запроса

В первом примере выполняется создание одного расширенного свойства с одним значением для указанного сообщения. Данное расширенное свойство является единственным элементом в массиве SingleValueExtendedProperties. Текст запроса для расширенного свойства включает следующие параметры.

PropertyId — указывает тип свойства (string), GUID и свойство с именем Color.
Value — указывает Green в качестве значения свойства Color.

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')

Content-Type: application/json

{
  "SingleValueExtendedProperties": [
      {
         "PropertyId":"String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
         "Value":"Green"
      }
    ]
}

Пример ответа

Отклик в результате успешного выполнения обозначен кодом HTTP 200 OK и включает в себя указанное сообщение подобно отклику при обновлении сообщения. Отклик не включает только что созданное расширенное свойство.

Пример запроса

Во втором примере выполняется создание одного расширенного свойства с несколькими значениями для указанного сообщения. Данное свойство является единственным элементом в массиве MultiValueExtendedProperties. Текст запроса включает следующее:

PropertyId — определяет свойство в виде массива строк с заданным идентификатором GUID и именем Palette.
Value — определяет Palette в виде массива из 3 строковых значений ["Green", "Aqua", "Blue"].

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_as77AACHsLrBBBA=')

Content-Type: application/json

{
  "MultiValueExtendedProperties": [
      {
         "PropertyId":"StringArray {66f5a359-4659-4830-9070-00049ec6ac6e} Name Palette",
         "Value":["Green", "Aqua", "Blue"]
      }
    ]
}

Пример ответа

Для просмотра нового расширенного свойства получите развернутое сообщение с этим свойством.

Создайте расширенное свойство в новом элементе

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

POST https://outlook.office.com/api/v2.0/me/messages
POST https://outlook.office.com/api/v2.0/me/events
POST https://outlook.office.com/api/v2.0/me/contacts
POST https://outlook.office.com/api/v2.0/me/tasks
POST https://outlook.office.com/api/v2.0/me/mailfolders
POST https://outlook.office.com/api/v2.0/me/calendars
POST https://outlook.office.com/api/v2.0/me/contactfolders
POST https://outlook.office.com/api/v2.0/me/taskfolders

Минимальная требуемая область

Одна из следующих областей для чтения и записи, соответствующих целевому ресурсу:

https://outlook.office.com/mail.readwrite
https://outlook.office.com/calendars.readwrite
https://outlook.office.com/contacts.readwrite
https://outlook.office.com/tasks.readwrite
wl.imap
wl.calendars_update
wl.events_create
wl.contacts_create

Параметр	Тип	Описание
Параметры текста
SingleValueExtendedProperties	Коллекция (SingleValueLegacyExtendedProperty)	Массив из одного или нескольких расширенных свойств с одним значением.
PropertyId	string	Укажите это значение для каждого свойства в коллекции SingleValueExtendedProperties, чтобы определить свойство. Оно должно быть указано в одном из форматов, поддерживаемых для расширенных свойств с одним значением. Обязательный параметр.
Значение	string	Укажите значение для каждого свойства в коллекции SingleValueExtendedProperties. Обязательный параметр.
MultiValueExtendedProperties	Коллекция (MultiValueLegacyExtendedProperty)	Массив из одного или нескольких расширенных свойств с несколькими значениями.
PropertyId	string	Укажите это значение для каждого свойства в коллекции MultiValueExtendedProperties, чтобы определить свойство. Оно должно быть указано в одном из форматов, поддерживаемых для расширенных свойств с несколькими значениями. Обязательный параметр.
Значение	Collection(string)	Укажите значения для каждого свойства в коллекции MultiValueExtendedProperties. Обязательный параметр.

Пример запроса

В первом примере выполняется создание нового события и расширенного свойства с одним значением. Помимо свойств, которые обычно указываются для нового события, текст запроса включает массив SingleValueExtendedProperties, который содержит одно расширенное свойство с одним значением и следующие параметры свойства:

PropertyId — указывает тип свойства (string), GUID и свойство с именем Fun.
Value — указывает Food в качестве значения свойства Fun.

POST https://outlook.office.com/api/v2.0/me/events

Content-Type: application/json

{
  "Subject": "Celebrate Thanksgiving",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together!"
  },
  "Start": {
      "DateTime": "2015-11-26T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-26T23:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    }
  ],
  "SingleValueExtendedProperties": [
     {
           "PropertyId":"String {66f5a359-4659-4830-9070-00040ec6ac6e} Name Fun",
           "Value":"Food"
     }
  ]
}

Пример ответа

Отклик в результате успешного выполнения обозначен кодом HTTP 201 Created и включает в себя новое событие, подобно отклику при создании просто события. Отклик не включает только что созданные расширенные свойства.

Для просмотра нового расширенного свойства получите развернутый элемент с этим свойством.

Пример запроса

Во втором примере выполняется создание расширенного свойства с несколькими значениями в новом событии с использованием одной операции POST. Помимо свойств, которые обычно указываются для нового события, текст запроса включает массив MultiValueExtendedProperties, который содержит одно расширенное свойство.

Текст запроса для расширенного свойства с несколькими значениями включает следующие параметры.

PropertyId — определяет свойство в виде массива строк с заданным идентификатором GUID и именем Recreation.
Value — определяет Recreation в виде массива из 3 строковых значений ["Food", "Hiking", "Swimming"].

POST https://outlook.office.com/api/v2.0/me/events

Content-Type: application/json

{
  "Subject": "Family reunion",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together this Thanksgiving!"
  },
  "Start": {
      "DateTime": "2015-11-26T09:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-29T21:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "Lauren@contoso.com",
        "Name": "Lauren Solis"
      },
      "Type": "Required"
    }
  ],
  "MultiValueExtendedProperties": [
     {
           "PropertyId":"StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
           "Value": ["Food", "Hiking", "Swimming"]
     }
  ]
}

Пример ответа

Для просмотра нового расширенного свойства получите развернутый элемент с этим свойством.

Возврат элемента с расширенным свойством

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

Строка {propertyId_value}, заданная в фильтре для PropertyId, должна быть указана в одном из форматов, поддерживаемых параметром PropertyId. Убедитесь, что для символов пробела в строке фильтра используется кодирование URL.

Разверните элемент с соответствующими расширенными свойствами с одним значением

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders('{taskfolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Разверните элемент с соответствующими расширенными свойствами с несколькими значениями

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders('{taskfolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Минимальная требуемая область

Одна из следующих областей чтения, соответствующих целевому ресурсу:

https://outlook.office.com/mail.read
https://outlook.office.com/calendars.read
https://outlook.office.com/contacts.read
https://outlook.office.com/tasks.read
wl.imap
wl.calendars
wl.contacts_calendars
wl.basic

Пример запроса

В первом примере показано, как получить и развернуть указанное сообщение путем включения расширенного свойства с одним значением. Фильтр возвращает расширенное свойство, параметр PropertyId которого соответствует строке String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (для наглядности кодирование URL не показано).

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')?$expand=SingleValueExtendedProperties($filter=PropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color')

Пример ответа

При успешном выполнении ответ содержит код отклика HTTP 200 OK.

Текст ответа содержит все свойства указанного сообщения и расширенное свойство, возвращенное фильтром.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE1M2_bs88AACHsLqWAAA=')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H\"",
    "Id": "AAMkAGE1M2_bs88AACHsLqWAAA=",
    "CreatedDateTime": "2015-11-11T02:41:24Z",
    "LastModifiedDateTime": "2015-12-09T04:07:57Z",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H",
    "Categories": [
    ],
    "ReceivedDateTime": "2015-11-11T02:41:24Z",
    "SentDateTime": "2015-11-11T02:41:24Z",
    "HasAttachments": false,
    "InternetMessageId": "<SN2SR0101MB002977E7C30F9CA9AA55961484130@SN2SR0101MB0029.contoso.com>",
    "Subject": "RE: Talk about emergency prep",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=iso-8859-1\">\r\n<style type=\"text/css\" style=\"\">\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n</style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<hr tabindex=\"-1\" style=\"display:inline-block; width:98%\">\r\n<div id=\"divRplyFwdMsg\" dir=\"ltr\"><font face=\"Calibri, sans-serif\" color=\"#000000\" style=\"font-size:11pt\"><b>From:</b> Christine Irwin<br>\r\n<b>Sent:</b> Sunday, November 8, 2015 12:28:31 AM<br>\r\n<b>To:</b> Terrie Barrera<br>\r\n<b>Subject:</b> Talk about emergency prep<br>\r\n<b>When:</b> Sunday, November 8, 2015 7:00 PM-8:00 PM.<br>\r\n<b>Where:</b> The Commons</font>\r\n<div>&nbsp;</div>\r\n</div>\r\n<div>\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt; color:#000000; background-color:#FFFFFF; font-family:Calibri,Arial,Helvetica,sans-serif\">\r\n<p>Please see the attached before you come to the meeting.<br>\r\n</p>\r\n</div>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "________________________________",
    "Importance": "Normal",
    "ParentFolderId": "AQMkAGE1M2jgxCloXP1JupQN7j5uzzwAAAIBDwAAAA==",
    "Sender": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "From": null,
    "ToRecipients": [
        {
            "EmailAddress": {
                "Name": "Christine Irwin",
                "Address": "christine@contoso.com"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVlLTY0YjcxZWUzNTE1MAAQAHWT1sRiMChEmlQCIZUadoU=",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsRead": true,
    "IsDraft": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACHsLqWAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "HashtagDetailsPreview": null,
    "LikesPreview": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "UnsubscribeData": [
    ],
    "UnsubscribeEnabled": false,
    "SingleValueExtendedProperties@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2_bs88AACHsLqWAAA%3D')/SingleValueExtendedProperties",
    "SingleValueExtendedProperties": [
        {
            "PropertyId": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
            "Value": "Green"
        }
    ]
}

Пример запроса

Во втором примере показано, как получить и развернуть указанное событие путем включения расширенного свойства с несколькими значениями. Фильтр возвращает расширенное свойство, параметр PropertyId которого соответствует строке StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation (для наглядности кодирование URL не показано).

GET https://outlook.office.com/api/v2.0/me/events('AAMkAGE1M2_bs88AACbuFiiAAA=')?$expand=MultiValueExtendedProperties($filter=PropertyId%20eq%20'StringArray%20{66f5a359-4659-4830-9070-00050ec6ac6e}%20Name%20Recreation')

Пример ответа

При успешном выполнении ответ содержит код отклика HTTP 200 OK.

Основной текст ответа включает в себя все свойства указанного события и расширенное свойство, возвращенное из фильтра.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE1M2_bs88AACbuFiiAAA=')",
    "@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAAm8k15A==\"",
    "Id": "AAMkAGE1M2_bs88AACbuFiiAAA=",
    "CreatedDateTime": "2015-12-09T05:18:05.9477979Z",
    "LastModifiedDateTime": "2015-12-09T05:18:06.197802Z",
    "ChangeKey": "mODEKWhc/Um6lA3uPm7PPAAAm8k15A==",
    "Categories": [
    ],
    "OriginalStartTimeZone": "Pacific Standard Time",
    "OriginalEndTimeZone": "Pacific Standard Time",
    "ResponseStatus": {
        "Response": "Organizer",
        "Time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "04000000828A332796D9",
    "ReminderMinutesBeforeStart": 15,
    "IsReminderOn": true,
    "HasAttachments": false,
    "Subject": "Family reunion",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nLet's get together this Thanksgiving!\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "Let's get together this Thanksgiving!",
    "Importance": "Normal",
    "Sensitivity": "Normal",
    "Start": {
        "DateTime": "2015-11-26T17:00:00.0000000",
        "TimeZone": "UTC"
    },
    "End": {
        "DateTime": "2015-11-30T05:00:00.0000000",
        "TimeZone": "UTC"
    },
    "Location": {
        "DisplayName": ""
    },
    "IsAllDay": false,
    "IsCancelled": false,
    "IsOrganizer": true,
    "Recurrence": null,
    "ResponseRequested": true,
    "SeriesMasterId": null,
    "ShowAs": "Busy",
    "Type": "SingleInstance",
    "Attendees": [
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Terrie Barrera",
                "Address": "Terrie@contoso.com"
            }
        },
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Lauren Solis",
                "Address": "Lauren@contoso.com"
            }
        }
    ],
    "Organizer": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACbuFiiAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "MultiValueExtendedProperties@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Events('AAMkAGE1M2_bs88AACbuFiiAAA%3D')/MultiValueExtendedProperties",
    "MultiValueExtendedProperties": [
        {
            "PropertyId": "StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
            "Value": [
                "Food",
                "Hiking",
                "Swimming"
            ]
        }
    ]
}

Возврат элемента путем фильтрации по расширенному свойству

Получите экземпляры поддерживаемого ресурса с расширенным свойством, которое указано фильтром для параметров PropertyId и Value. Фильтр применяется ко всем экземплярам ресурса в почтовом ящике вошедшего пользователя. Такая фильтрация поддерживает только расширенные свойства с одним значением, и не поддерживает расширенные свойства с несколькими значениями.

Строка {propertyId_value}, заданная в фильтре для PropertyId, должна быть указана в одном из форматов, поддерживаемых параметром PropertyId.

Если {property_value} не является строкой, убедитесь, что ep/value явно приведен к соответствующему типу данных Edm при сравнении с параметром {property_value}. Примеры таких приведений представлены в примерах запросов для свойств, тип которых отличается от строкового.

Применяйте кодирование URL для следующих символов в строке фильтра: двоеточие, косая черта и пробел.

GET https://outlook.office.com/api/v2.0/me/messages?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/events?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/contacts?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/tasks?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/mailfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/calendars?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/contactfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/v2.0/me/taskfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

Минимальная требуемая область

Одна из следующих областей чтения, соответствующих целевому ресурсу:

https://outlook.office.com/mail.read
https://outlook.office.com/calendars.read
https://outlook.office.com/contacts.read
https://outlook.office.com/tasks.read
wl.imap
wl.calendars
wl.contacts_calendars
wl.basic

Пример запроса

В первом примере показано, как получить сообщения с указанным в фильтре расширенным свойством с одним значением. Фильтр возвращает расширенное свойство, которое имеет следующие параметры.

Параметр PropertyId соответствует строке String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (для наглядности здесь убрано кодирование URL).
Параметр Value имеет значение Green.

GET https://outlook.office.com/api/v2.0/Me/Messages?$filter=SingleValueExtendedProperties%2FAny(ep%3A%20ep%2FPropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color'%20and%20ep%2FValue%20eq%20'Green')

В следующих двух примерах показано, как получить сообщения с расширенными свойствами с одним значением, тип которых отличается от строкового. Необходимое URL кодирование не показано для удобства чтения. В следующем примере показан фильтр, выполняющий поиск расширенного свойства со следующими параметрами:

Параметр PropertyId соответствует строке CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid.
Параметр Value имеет значение GUID b9cf8971-7d55-4b73-9ffa-a584611b600b. Чтобы сравнить значение свойства с идентификатором GUID, приведите ep/Value к Edm.Guid.

GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid' and cast(ep/Value, Edm.Guid) eq (b9cf8971-7d55-4b73-9ffa-a584611b600b))

В третьем и последнем примере показан фильтр, выполняющий поиск расширенного свойства со следующими параметрами:

Параметр PropertyId соответствует строке Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete.
Параметр Value имеет целочисленное значение 12. Чтобы сравнить значение свойства с целым числом, приведите ep/Value к Edm.Int32.

GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete' and cast(ep/Value, Edm.Int32) eq 12)

Пример ответа

В случае успешного выполнения возвращается код ответа HTTP 200 OK, а текст ответа включает все свойства сообщений, имеющих расширенное свойство, соответствующее указанному фильтру. Текст ответа аналогичен ответу при получении коллекции сообщений. Ответ не содержит соответствующее расширенное свойство.

Дальнейшие действия

Независимо от того, готовы ли вы приступить к созданию приложения или хотите изучить больше материалов, у нас есть все необходимое.

Начало работы с REST API для почты, календаря и контактов.
Нужны примеры? Вот они.

Или узнайте больше об использовании платформы Office 365 здесь:

Ссылка на расширенные свойства Outlook REST API (версия 2.0)

Использование расширенных свойств REST API

Расширенные свойства или модули обработки данных?

Проверка подлинности

Версия API

Поддерживаемые ресурсы REST

Параметры URL-адреса

Обзор

Форматы PropertyId

Операции с расширенными свойствами

Создание расширенного свойства в существующем элементе

Минимальная требуемая область

Пример запроса

Пример ответа

Пример запроса

Пример ответа

Создайте расширенное свойство в новом элементе

Минимальная требуемая область

Пример запроса

Пример ответа

Пример запроса

Пример ответа

Возврат элемента с расширенным свойством

Разверните элемент с соответствующими расширенными свойствами с одним значением

Разверните элемент с соответствующими расширенными свойствами с несколькими значениями

Минимальная требуемая область

Пример запроса

Пример ответа

Пример запроса

Пример ответа

Возврат элемента путем фильтрации по расширенному свойству

Минимальная требуемая область

Пример запроса

Пример ответа

Дальнейшие действия

Дополнительные ресурсы