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

Область применения: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Расширенные свойства REST API Outlook позволяют приложениям хранить пользовательские данные и предоставляют им резервный механизм для доступа к этим данным для свойств MAPI Outlook, когда эти свойства еще не предоставлены при помощи метаданных API REST Outlook. Расширенные свойства API можно использовать для сохранения или получения таких пользовательских данных в сообщении, почтовой папке, событии, календаре, папке контактов, задаче или папке задач в учетной записи вошедшего пользователя. Учетная запись может быть учетной записью Office 365 или Майкрософт (Hotmail.com, Live.com, MSN.com, Outlook.com и Passport.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 используются следующие заполнители ИД. Необходимо указать ИД экземпляра ресурса, для которого нужно создать расширение.

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

Обзор

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

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

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

Форматы PropertyId

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

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

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

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

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

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

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

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

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. Текст запроса для расширенного свойства включает следующие параметры.

• 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"]
      }
    ]
}

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

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

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

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

Создание одного или нескольких расширенных свойств для нового экземпляра поддерживаемого ресурса в одном вызове 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, который содержит одно расширенное свойство с одним значением и следующие параметры свойства:

• 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"]
     }
  ]
}

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

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

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

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

Получите развернутый экземпляр поддерживаемого ресурса с расширенным свойством, которое задается фильтром по 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 здесь:

• API REST Outlook для центра разработок Outlook
• Обзор разработки на платформе Office 365
• Справка по REST API «Почта»
• Справка по REST API для Календаря
• Справка по REST API «Контакты»
• Задания для REST API
• Справочные ресурсы по REST API для почты, календаря, контактов и задач
• Справка по API «Люди»
• Справка по API «Модули обработки данных»
• Справка по REST API «Уведомления»
• Справка по API REST «Фотографии пользователя»
• Пакетные запросы Outlook REST