Поделиться через

Справка по REST API потоковых уведомлений в Outlook (предварительная версия)

  • Статья

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

Примечание

Эта версия документа касается API потоковых уведомлений в режиме предварительного просмотра. Параметры предварительного просмотра могут быть изменены до завершения и могут нарушать код, который их использует. Поэтому в своем производственном коде вы должны использовать только производственную версию API. Если она доступна, предпочтительной версией в настоящее время является v2.0.

REST API потоковых уведомлений Outlook отправляет уведомления при прямом подключении, что позволяет клиентским приложениям узнавать об изменениях данных почтового ящика пользователя. Данные могут находиться в почте, календаре, контактах или задачах пользователя, защищенных Azure Active Directory в Office 365, или в учетных записях Microsoft конкретно в этих доменах: Hotmail.com, Live.com, MSN.com, Outlook.com и Passport.com.

Примечание

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

Обзор

Служба потоковых уведомлений Office 365 устанавливает прямое соединение с клиентом и отправляет уведомления об изменении данных, запрошенных клиентским приложением.

Когда приложение подписывается на получение уведомлений об изменениях определенного типа на конкретном ресурсе (например, в сообщениях в папке «Входящие»), между сервером Office 365 и клиентом устанавливается долговременное соединение. Когда происходит триггерное событие (например, в папке «Входящие» поступает новое сообщение), служба Office 365 передает уведомление клиенту. Клиент анализирует уведомление и выполняет действия в соответствии со своей бизнес-логикой, например, получает новое сообщение и обновляет количество непрочитанных сообщений.

Сравнение потоковых и push-уведомлений

Почтовые, календарные и CRM приложения обычно используют уведомления для обновления локального кеша, соответствующих представлений со стороны клиента или серверных систем в случае изменений. Outlook поддерживает как потоковые, так и push -уведомления. уведомления. Для получения рush-уведомлений с сервера Office 365 клиенту необходима веб-служба прослушивателя, в то время для получения потоковых уведомлений требуется только прямое соединение между клиентом и сервером Office 365. После установления соединения с сервером соединение остается открытым в течение определенного периода времени. В течение этого времени клиент отправляет долговременныйGetNotifications запрос лишь один раз; каждый раз, когда происходит триггерное событие, сервер может просто отправить уведомление в потоке ответов. Это продолжается до тех пор, пока не истечет установленный срок соединения, пока клиент не прервет соединение или не возникнет проблема в сети.

Использование REST API потоковых уведомлений

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

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

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

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

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

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

Версия API

В настоящее время этот API находится в состоянии предварительного просмотра и доступен только в конечной точке бета-версии REST API:

https://outlook.office.com/api/beta/

Целевой пользователь

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

Действия с потоковыми уведомлениями

Подписаться на изменения в моей почте, календаре, контактах или задачах

Подписка на получение потоковых уведомлений об изменении почты, событий календаря, контактов или задач в почтовом ящике Office 365 или Outlook.com. Это первый шаг к получению клиентом уведомлений для ресурса (объекты или коллекции объектов).

POST https://outlook.office.com/api/beta/me/subscriptions

В тексте запроса укажите следующие требуемые свойства запроса на оформление подписки на потоковые уведомления. Дополнительную информацию см. в разделе Объекты уведомлений.

  • odata.type - Включить "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription".

  • ChangeType - Указывает типы событий, которые необходимо отслеживать для этого ресурса. Поддерживаемые типы см. в разделе ChangeType.

  • Resource - Указывает ресурс для мониторинга и получения уведомлений. Вы можете использовать дополнительные параметры запроса $filter или $select уточнить условия отправки уведомления или включить в уведомление конкретные свойства. Ниже указаны поддерживаемые ресурсы:

    • Обычная папка или папка поиска сообщений, событий, контактов или задач. Примеры:

      https://outlook.office.com/api/beta/me/mailfolders('inbox')/messages

      https://outlook.office.com/api/beta/me/taskfolders('{folder_id}')/tasks

    • Или коллекция сообщений, событий, контактов или задач верхнего уровня, например:

      https://outlook.office.com/api/beta/me/messages

      https://outlook.office.com/api/beta/me/events

      https://outlook.office.com/api/beta/me/contacts

      https://outlook.office.com/api/beta/me/tasks

Если запрос на подписку выполнен успешно, возвращается идентификатор подписки. Срок действия этого идентификатора подписки по умолчанию истекает через 90 минут, если только клиент не начинает ожидаение передачи (прослушивание) уведомлений при подключении. В дальнейшем пока соединение открыто, подписка будет автоматически обновляться.

Пример запроса на оформление подписки

Следующий запрос создает потоковую подписку на получение уведомлений о создании, обновлении и удалении данных в папке «Входящие» пользователя.

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
   ChangeType: "Created,Updated,Deleted"
}

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

В случае успешного выполнения запроса ответ содержит код HTTP 201 и идентификатор подписки. Ниже приведен пример ответа:

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('RUM4OEJFNUIQUQ4MQ==')",
    "Id":"RUM4OEJFNUIQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Уточнение условий получения уведомлений

Вы можете ограничить уведомления подгруппой элементов, используя $filter условие. Например, следующий запрос на оформление подписки ведет к созданию подписки, при которой уведомление отправляется только в случае изменения сообщений с темой «Добавки».

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
   ChangeType: "Created,Updated,Deleted"
}

Успешный ответ на подписку выглядит так:

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('MjcwOUQ2MjEtQUQ4MQ==')",
    "Id":"MjcwOUQ2MjEtQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Подпишитесь на полнофункциональные потоковые уведомления

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

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

Ниже приведен пример запроса на включение в потоковые уведомления свойства Тема при создании события:

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
    @odata.type:"#Microsoft.OutlookServices.StreamingSubscription",
    Resource: "https://outlook.office.com/api/beta/me/events?$select=Subject",
    ChangeType: "Created"
}

После успешной подписки на полнофункциональные потоковые уведомления в полезных данных полнофункциональных уведомлений** будет указано значение свойства** Тема .

Ожидание передачи уведомлений

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

POST https://outlook.office.com/api/beta/Me/GetNotifications

Этот запрос POST не завершается до указанного времени ConnectionTimeoutinMinutes, и сервер завершает большой двоичный объект JSON в ответе, или если есть другие проблемы, и клиент или сервер прерывает соединение.

Пока соединение открыто, все подписки, использующие соединение, автоматически продляются. В случае разрыва соединения срок действия этих подписок также истечет через 90 минут, если только клиент не установит для них новое соединение.

Убедитесь, что код, отправляющий запрос POST, обрабатывает код статуса возврата HTTP 404 Not found, который возвращается в том случае, если указанная подписка действительно истекла. Если это произойдет, отправьте запрос на оформление новой подписки, прежде чем вновь ожидать передачи уведомлений по этой подписке.

Обязательный параметр тела Тип Описание
ConnectionTimeoutInMinutes int32 Количество минут, в течение которых соединение должно оставаться активным.
KeepAliveNotificationIntervalInSeconds int32 Интервал отправки сервером уведомлений keep-alive с целью уведомления клиента о том, что соединение остается открытым.
SubscriptionIds Коллекция (Строка) Идентификаторы подписок, по которым отправляются уведомления по этому соединению.

Примеры запросов на ожидание передачу уведомлений

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg=="
   ]
}

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

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg==",
       "Dc4NS04MTg2LUYwRjFFNUVFNTNDRgN0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtN=="
   ]
}

Пример потока уведомлений

Как только служба уведомлений настроена, клиент получает начало большого двоичного объекта JSON уведомлений.

{
    {"@odata.context":"https://outlook.office.com/api/beta/metadata#Notifications", 
    "value": [

Сервер отправляет уведомление keep-alive через фиксированный интервал, чтобы соединение оставалось открытым и активным. Этот интервал задается клиентом в свойствеKeepAliveNotificationIntervalInSeconds. Формат уведомления keep-alive выглядит так:

{
    "@odata.type": "#Microsoft.OutlookServices.KeepAliveNotification",
    "Status": "OK"
}

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

{ 
    "@odata.type": "#Microsoft.OutlookServices.Notification",
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    "SubscriptionExpirationDateTime": "2016-09-09T18:36:42.3454926Z",
    "SequenceNumber": 9, 
    "ChangeType": "Created", 
    "Resource": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
    "ResourceData": { 
        "@odata.type": "#Microsoft.OutlookServices.Message", 
        "@odata.id": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')", 
        "@odata.etag": "W/\"CQAAABYAAAB+0z/4Ly/1ToDr5FGl5k99AAABl5Do\"", 
        "Id": "AAMkADdlAA=" 
    } 
}

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

Примечание

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

,{
    "Id": null, 
    "SubscriptionId": "N0UzMEU4...", 
    ...
}

Пример полезных данных в полнофункциональном уведомлении

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

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Notifications",
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "QjQzNzAwBQQ==",
      "SubscriptionExpirationDateTime": "2017-01-18T00:57:28.6134733Z",
      "SequenceNumber": 1,
      "ChangeType": "Created",
      "Resource": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
      "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Event",
        "@odata.id": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

Закрытие соединения

Когда истекает время, указанное в свойстве ConnectionTimeoutInMinutes, сервер закрывает соединение и отправляет окончание большого лвоичного объекта JSON, как показано ниже.

    ]
}

Соединение может быть разорвано и в других обстоятельствах, например, в случае возникновения проблем с сетью и изменений на сервере, например, перезагрузки. Клиент может использовать уведомления keep-alive, чтобы определить, активно или разорвано соединение. В последнем случае клиент должен попытаться повторно подключиться к серверу, используя идентификатор существующей подписки. Если срок действия идентификатора подписки истек, необходимо отправить новый запрос на оформление подписки, чтобы восстановить соединение.

Если клиент больше не хочет получать подписку, он может отменить запрос POST и разорвать соединение. Когда сервер в следующий раз попытается отправить уведомление, он получит сообщение об ошибке, обнаружит разрыв соединения, остановит отправку уведомлений keep-alive и закроет соединение.

Объекты уведомлений и перечисления

Подписка

Базовая подписка. Это базовый абстрактный класс.

Базовый тип: объект

Свойство Тип Описание Подлежит записи? Фильтруется
Ресурс строка Указывает ресурс, для которого будут отслеживаться изменения. Да Н/Д
ChangeType ChangeType Указывает тип событий, при возникновении которых будет создано уведомление. Поддерживаемые типы см. в разделе ChangeType. Да Н/Д

Уведомление

Уведомление, отправленное клиенту.

Базовый тип: объект

Свойство Тип Описание Подлежит записи? Фильтруется
SubscriptionId строка Уникальный идентификатор подписки. No (Нет) Н/Д
Номер последовательности int32 Указывает порядковое значение уведомления об изменении. No (Нет) Н/Д
ChangeType строка Указывает тип события, вызвавшего отправку уведомления. Поддерживаемые типы см. в разделе ChangeType. No (Нет) Н/Д
Ресурс строка Указывает элемент ресурса, для которого отслеживаются изменения No (Нет) Н/Д
ResourceData Сущность Определяет изменившийся объект. Это свойство навигации No (Нет) Н/Д

ChangeType

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

Поддерживаемые значения:

  • Подтверждение
  • Создано
  • Удалено
  • Пропущено. УведомлениеMissed отправляется, когда служба уведомлений не может отправить запрошенное уведомление.
  • Обновлено

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

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

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