Справка по API REST Push-уведомлений для Outlook (версия 2.0)
Область применения: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com
Outlook Push уведомления REST API отправляет уведомления веб-службе на стороне клиента, чтобы приложения могли узнать об изменениях в данных почтового ящика пользователя. Данные могут находиться в почте, календаре, контактах или задачах пользователя, защищенных Azure Active Directory в Office 365, или в учетных записях Microsoft конкретно в этих доменах: Hotmail.com, Live.com, MSN.com, Outlook.com и Passport.com.
Примечание
Для упрощения этой справки в остальной части этой статьи при упоминании Outlook.com также подразумеваются и эти домены учетной записи Майкрософт.
Не интересуетесь API версии 2.0? В оглавлении слева перейдите к разделу Справка по API Office 365 и выберите нужную версию.
Обзор
Служба push уведомлений Office 365 и API работают с клиентами, которые предоставляют веб-службе обратный вызов, и используют веб-камеры для доставки уведомлений в клиентские приложения. Webhooks - это HTTP-обратные вызовы, настроенные обычно доверенным сторонним веб-сервисом. Веб-служба может настраивать webhooks, чтобы вызвать запуск событий на одном сайте, чтобы вызвать поведение на другом.
Когда приложение подписывается на уведомления определенного ресурса (например, сообщения в папке «Входящие»), он указывает URL-адрес обратного вызова веб-хоста в запросе на подписку. Когда происходит триггерное событие (например, новое сообщение в папке «Входящие»), служба уведомлений Office 365 подталкивает уведомление через webhook к URL-адресу обратного вызова. Приложение, в свою очередь, предпринимает действия в соответствии со своей бизнес-логикой, например, получение нового сообщения и обновление непрочитанного счета.
Приложения должны обновлять свои подписки до истечения срока их действия. Они могут также отказаться от подписки в любое время, чтобы прекратить получать уведомления.
Сравнение потоковых и push-уведомлений
Почтовые, календарные и CRM приложения обычно используют уведомления для обновления локального кеша, соответствующих представлений со стороны клиента или серверных систем в случае изменений. Outlook поддерживает как потоковые, так и push-уведомления. В настоящее время push-уведомления обычно используются мобильными приложениями, так как не требуют от клиентов опроса для изменений и почти мгновенно становятся доступными для клиентов.
Сравнивая с потоковыми уведомлениями, push-уведомления требуют, чтобы клиент предоставлял свою собственную веб-службу для получения уведомлений, а для потоковых уведомлений требуется только прямое соединение между клиентом и службой уведомлений потоковой передачи Office 365.
Использование REST API Push-уведомлений
Проверка подлинности
Чтобы подписаться, запросить, обновить и удалить подписки, укажите соответствующие области для типов ресурсов, на которые вы хотите получать уведомления.
Минимальная требуемая область
Одна из следующих областей чтения, соответствующих целевому ресурсу:
- 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
Как и во всех других REST API Outlook, каждый запрос к API Push-уведомлениям Outlook должен включать действительный маркер доступа. Получение маркера доступа требует, чтобы вы зарегистрировались и идентифицировали свою программу и получили соответствующее разрешение.
Вы можете получить дополнительные сведения о некоторых оптимизированных параметрах регистрации и авторизации. Помните об этом, когда выполняете конкретные действия в API Push-уведомлениях.
Версия API
Этот API был повышен с предварительной версии до общедоступной версии. Он поддерживается в версиях v2.0 и бета-версиях REST API Outlook.
Целевой пользователь
Запросы к API Push-уведомлений всегда выполняются от имени текущего пользователя.
Дополнительные сведения, общие для всех подразделов API REST Outlook, см. в разделе Использование API REST Outlook.
Операции с push-уведомлениями
Подписаться на изменения в Моей почте, Календаре, Контактах или Задачах
Процесс подписки
Процесс подписки выглядит следующим образом:
Клиентское приложение делает запрос на подписку (POST) для определенного ресурса. Он включает URL-адрес уведомления, среди других свойств.
Служба уведомлений Outlook пытается проверить URL-адрес уведомления с помощью службы прослушивателя. Он включает маркер проверки подлинности в запросе проверки.
Если служба прослушивателя успешно проверяет URL-адрес, он возвращает ответ успеха в течение 5 секунд следующим образом:
- Устанавливает тип контента в заголовке ответа в text \ plain.
- Включает в тело ответа тот же маркер проверки.
- Возвращает код ответа HTTP 200. В дальнейшем слушатель может отменить маркер проверки.
В зависимости от результата проверки URL-адреса служба уведомлений Outlook отправляет ответ клиентскому приложению:
- Если проверка URL была успешной, служба создает подписку с уникальным идентификатором подписки и отправляет ответ клиенту.
- Если проверка URL была неудачной, служба отправляет ответ об ошибке с кодом ошибки и другими сведениями.
Получив успешный ответ, клиентское приложение сохраняет идентификатор подписки для корреляции будущих уведомлений с этой подпиской.
Запрос на подписку
Подписывается на службу прослушивания для получения уведомлений при изменении почты, событий календаря, контактов или задач в Office 365 или Outlook.com. Это первый шаг к получению клиентом уведомлений для ресурса (объекта или коллекции объектов).
POST https://outlook.office.com/api/v2.0/me/subscriptions
В тексте запроса укажите следующие требуемые свойства запроса на оформление подписки на push-уведомления. За исключением ClientState, требуются все свойства. Дополнительную информацию см. в разделе Объекты уведомлений
- odata.type - Включить
"@odata.type":"#Microsoft.OutlookServices.PushSubscription"
. Объект PushSubscription определяет NotificationURL. - ChangeType - Указывает типы событий, которые необходимо отслеживать для этого ресурса. Поддерживаемые типы см. в разделе ChangeType.
- ClientState - Необязательное свойство, указывающее, что каждое уведомление должно быть отправлено с заголовком, с тем же значением ClientState. Это позволяет слушателю проверить легитимность каждого уведомления.
- NotificationURL - Указывает, куда отправлять уведомления. Этот URL-адрес представляет собой веб-сервис, который обычно реализуется клиентом.
- Resource - Указывает ресурс для мониторинга и получения уведомлений. Вы можете использовать дополнительный параметр запроса
$filter
, чтобы уточнить условия отправки уведомления, или использовать параметр$select
, чтобы включить в форматированное уведомление конкретные свойства.
Ниже указаны поддерживаемые ресурсы:
Обычная папка или папка поиска сообщений, событий, контактов или задач. Примеры:
https://outlook.office.com/api/v2.0/me/mailfolders('inbox')/messages
https://outlook.office.com/api/v2.0/me/taskfolders('{folder_id}')/tasks
Или коллекция сообщений, событий, контактов или задач верхнего уровня, например:
https://outlook.office.com/api/v2.0/me/messages
https://outlook.office.com/api/v2.0/me/events
https://outlook.office.com/api/v2.0/me/contacts
https://outlook.office.com/api/v2.0/me/tasks
Пример запроса
В следующем примере показано, как подписаться на новые события.
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json
{
"@odata.type":"#Microsoft.OutlookServices.PushSubscription",
"Resource": "https://outlook.office.com/api/v2.0/me/events",
"NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
"ChangeType": "Created",
"ClientState": "c75831bd-fad3-4191-9a66-280a48528679"
}
Уточнение условий получения уведомлений
Вы можете дополнительно уточнить условия для уведомления, используя параметр запроса $filter
.
В следующем примере запрашивается уведомление для Сообщения создаваемого в папке Черновики, содержащей одно или несколько вложений, и важности High
:
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json
{
@odata.type:"#Microsoft.OutlookServices.PushSubscription",
Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('Drafts')/messages?$filter=HasAttachments%20eq%20true%20AND%20Importance%20eq%20%27High%27",
NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
ChangeType: "Created",
ClientState: "Has attachments and high importance"
}
В следующем примере запрашивается уведомление на Событие, создаваемое на весь день:
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json
{
@odata.type:"#Microsoft.OutlookServices.PushSubscription",
Resource: "https://outlook.office.com/api/v2.0/me/events?$filter=IsAllDay%20eq%20true",
NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
ChangeType: "Created",
ClientState: "Notifications for events that IsAllDay."
}
В следующем примере запрашивается уведомление на Контакт, создаваемое компанией Contoso:
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json
{
@odata.type:"#Microsoft.OutlookServices.PushSubscription",
Resource: "https://outlook.office.com/api/v2.0/me/contacts?$filter=CompanyName%20eq%20%27Contoso%27",
NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
ChangeType: "Created",
ClientState: "Contacts in Contoso."
}
Одно общее применение $filter
заключается в получении уведомления об изменении конкретного свойства указанного ресурса.
Например, вы можете использовать $filter
подписку на непрочитанные сообщения в папке ( IsRead свойство false) и включать все типы изменений:
- Сообщение, добавленное или помеченное непрочитанным в папке, вызовет
Created
уведомление. - Чтение сообщения или его маркировка, считанное в папке, вызовет
Deleted
уведомление. - Изменение любого свойства, кроме IsRead, сообщения в папке вызовут
Updated
уведомление.
Вы можете создать такую подписку следующим образом:
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json
{
@odata.type:"#Microsoft.OutlookServices.PushSubscription",
Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('folder_id')/messages$filter=IsRead%20eq%20false",
NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
ChangeType: "Created,Deleted,Updated",
ClientState: "Message unread"
}
Если вы не используете $filter
при создании подписки (как показано ниже):
- Добавление сообщения в папку приведет к
Created
уведомлению. - Чтение сообщения в папке, маркировка сообщения как прочитанного или изменение любого другого свойства сообщения в этой папке приведет к
Updated
уведомлению. - Удаление сообщения вызовет уведомление
Delete
.
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json
{
@odata.type:"#Microsoft.OutlookServices.PushSubscription",
Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('folder_id')/messages,
NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
ChangeType: "Created,Deleted,Updated",
ClientState: "Message unread"
}
Запрос проверки
В запросе проверки делается попытка проверить адрес NotificationURL, указанный клиентским приложением в запросе на подписку:
POST https://{notificationUrl}?validationToken={token}
Служба Outlook указывает NotificationURL в запросе на подписку в {notificationUrl} и определяет строку {маркер} как маркер проверки. Служба Outlook также включает заголовок ClientState, если клиентское приложение включает такой заголовок в запросе на подписку.
Ответ на подписку
Ответ на подписку включает свойства в запросе и следующие дополнительные свойства:
- Id - Уникальный идентификатор подписки, который должно сохранить клиентское приложение, чтобы соответствовать будущим уведомлениям.
- ChangeType - Помимо значений, указанных в запросе, ответ включает дополнительный тип уведомления, Пропущено.
- SubscriptionExpirationDateTime - дата и время окончания подписки. Если в запросе на подписку не указано время истечения срока действия или если запрос указывает время истечения, превышающее максимально допустимое, это свойство будет установлено на эту максимально допустимую длину с момента отправки запроса. Для подписки, запрашивающей форматированные уведомления о конкретных свойствах, максимально допустимый составляет 1 день. Для других подписчиков максимум составляет 7 дней.
- Другие свойства, связанные с OData.
Пример данных ответа
Этот ответ указывает, что служба прослушивания должна ожидать получения уведомлений о новых событиях и пропущенных изменениях. Если есть пропущенные изменения, клиенту необходимо будет синхронизироваться с сервисом для их захвата.
{
"@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Subscriptions/$entity",
"@odata.type": "#Microsoft.OutlookServices.PushSubscription",
"@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')",
"Id": "Mjk3QNERDQQ==",
"Resource": "https://outlook.office.com/api/v2.0/me/events",
"ChangeType": "Created, Missed",
"ClientState": "c75831bd-fad3-4191-9a66-280a48528679",
"NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
"SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z"
}
Запрос подписки
Вы можете найти информацию о любых существующих подписках пользователя, указав свой идентификатор подписки. Например, чтобы запросить подписку, созданную в последнем примере:
GET https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')
В случае успеха ответ будет таким же, как и последние данные ответа в примере, с той разницей, что он исключает любой объект ClientState, указанный клиентским приложением, чтобы избежать потенциальных угроз безопасности.
Уведомления
Каждое уведомление содержит следующие свойства, независимо от его типа:
- ЗаголовокClientState- присутствует только в том случае, если клиент указал свойствоClientStateв запросе на подписку. Используется слушателем для проверки легитимности уведомления.
- SubscriptionId - Определяет подписку клиентского приложения, к которой относится это уведомление.
- SubscriptionExpirationDateTime - Срок действия и время подписки.
- SequenceNumber - Число в последовательности для уведомления, чтобы помочь клиентскому приложению определить, не было ли пропущенно уведомление.
- ChangeType - Типы событий, на которые клиентское приложение хочет получать уведомление (например, Созданный тип события при получении почты или Обновлённый тип события при чтении сообщения).
- Ресурс - URL-адрес определенного элемента ресурса, который отслеживается (например, URL-адрес измененного сообщения или события).
- ResourceData - Уведомление, связанное с изменением ресурса (например, получение, чтение или удаление сообщения), имеет это дополнительное свойство, которое содержит идентификатор ресурса, который был изменен. Клиент может использовать этот идентификатор ресурса для обработки этого элемента в соответствии с его бизнес-логикой (например, извлечение этого элемента, синхронизация его папки).
Примечание
Свойство Id в сущностях Notification не используется.
Изменить полезную нагрузку уведомления
В следующем примере, когда пользователь получает новое событие, служба уведомлений отправляет уведомление с ChangeType, установленным в «Создано». Заголовок уведомления будет включать ClientState, как указано в первоначальном запросе на подписку. Уведомление о событии приема имеет полезную нагрузку, подобную этой:
{
"value": [
{
"@odata.type": "#Microsoft.OutlookServices.Notification",
"Id": null,
"SubscriptionId": "Mjk3QNERDQQ==",
"SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z",
"SequenceNumber": 1,
"ChangeType": "Created",
"Resource" : "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
"ResourceData": {
"@odata.type": "#Microsoft.OutlookServices.Event",
"@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
"Id": "AAMkADNkNmAA="
}
}
]
}
Получить свойства экземпляра, подписавшись на форматированные уведомления
Как видно из последнего примера полезной нагрузки уведомления об изменении, подписка на push-уведомление, настроенная для коллекции ресурсов, возвращает только идентификатор экземпляра ресурса, который был изменен. Свойства этого экземпляра получают отдельно.
Вы можете сохранить отдельный вызов API GET, если используете $select
параметр в запросе на подписку и укажите интересующие вас свойства. Ниже приведен пример запроса на включение в уведомления свойства subject при создании события:
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json
{
"@odata.type":"#Microsoft.OutlookServices.PushSubscription",
"Resource": "https://outlook.office.com/api/v2.0/me/events?$select=Subject",
"NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myRichNotifyClient",
"ChangeType": "Created"
}
Пример полезных данных в форматированном уведомлении
Полезная нагрузка с форматированным уведомлением включает значения свойств, указанных в запросе на подписку. После последнего примера, форматированное уведомление включает в себя свойство Предмет, выглядящее как:
{
"@odata.context": "https://outlook.office.com/api/v2.0/$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/v2.0/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/v2.0/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
"@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
"Id": "AAMkAGAAAAACisAAA=",
"Subject": "Quarterly meeting CY17Q1"
}
}
]
}
Обновить подписку
Обновите подписку на максимальную длину с момента запроса продления.
PATCH https://outlook.office.com/api/v2.0/me/subscriptions/{subscriptionId}
Длина подписки по умолчанию составляет 7 дней для запросов на подписку, для которых не требуются особые свойства экземпляра в ответе, и 1 день для подписки на форматированные уведомления.
Вы можете отправить запрос на продление без полезной нагрузки, и подписка будет продлена на соответствующий максимальный период.
Пример запроса
PATCH https://outlook.office.com/api/v2.0/me/subscriptions/Mjk3QNERDQQ==
{
@odata.type:"#Microsoft.OutlookServices.PushSubscription",
"SubscriptionExpirationDateTime": "2015-05-28T17:17:45.9028722Z"
}
Ответ
При успешной отмене подписки в отклике содержится код HTTP-отклика 200.
Удалить подписку
Удалите подписку, указав идентификатор подписки.
DELETE https://outlook.office.com/api/v2.0/me/subscriptions('{subscriptionId}')
Пример запроса
Delete https://outlook.office.com/api/v2.0/me/subscriptions('Mjk3QNERDQQ==')
Ответ
При успешном выполнении ответ содержит код отклика HTTP 204 No Content
.
Сущности и перечисления API Уведомлений
Подписка
Базовая подписка. Это базовый абстрактный класс.
Базовый тип: Объект
Свойство | Тип | Описание | Подлежит записи? | Фильтруемое? |
---|---|---|---|---|
Resource | string | Указывает ресурс, для которого будут отслеживаться изменения. | Да | Недоступно |
ChangeType | ChangeType | Указывает тип событий, при возникновении которых будет создано уведомление. Поддерживаемые типы см. в разделе ChangeType. | Да | Недоступно |
Notification
Обозначает уведомление, отправленное клиенту. В случае push-уведомлений уведомление отправляется в службу прослушивателя, указанную клиентом.
Базовый тип: Объект
Свойство | Тип | Описание | Подлежит записи? | Фильтруемое? |
---|---|---|---|---|
SubscriptionId | string | Уникальный идентификатор подписки. | Нет | Нет |
SubscriptionExpirationDateTime | Edm.DateTimeOffset | Указывает дату и время истечения срока действия подписки на уведомления. Время в UTC. | Да | Недоступно |
Номер последовательности | int32 | Указывает порядковое значение уведомления об изменении. | Нет | Недоступно |
ChangeType | ChangeType | Указывает тип события, вызвавшего отправку уведомления. Значения перечисления: Создано = 1, Обновлено = 2, Удалено = 4, Пропущено = 16. Уведомление отправляется, когда служба уведомлений не может отправить запрошенное уведомление. | Нет | Недоступно |
Resource | string | Указывает элемент ресурса, для которого отслеживаются изменения | Да | Недоступно |
ResourceData | Entity | Определяет изменившийся объект. Это свойство навигации. | Нет | Недоступно |
PushSubscription
Представляет подписку, которая использует механизм push-уведомлений.
Базовый тип: Подписка
Свойство | Тип | Описание | Подлежит записи? | Фильтруемое? |
---|---|---|---|---|
NotificationURL | string | URL-адрес приложения, получающего push-уведомления. | Да | Недоступно |
SubscriptionExpirationDateTime | Edm.DateTimeOffset | Указывает дату и время истечения срока действия подписки на уведомления. Время в UTC. | Да | Недоступно |
ClientState | string | Задает значение заголовка ClientState, отправляемого службой для каждого уведомления. Максимальная длина — 255 символов. Клиент может проверить, что уведомление поступило от службы, путем сравнения значения, установленного в свойстве ClientState, со значением заголовка ClientState, получаемого с каждым уведомлением. | Да | Нет |
ChangeType
Перечисление типов событий на поддерживаемых ресурсах, которые могут вызвать отправку уведомления.
Поддерживаемые значения:
- Подтверждение
- Created
- Удалено
- Missed. Уведомление
Missed
отправляется, когда служба уведомлений не может отправить запрошенное уведомление. - Updated
Дальнейшие действия
Независимо от того, готовы ли вы приступить к созданию приложения или хотите изучить больше материалов, у нас есть все необходимое.
- Начало работы с API REST Почты, Календаря и Контактов.
- Хотите увидеть примеры? Вот они.
Или узнайте больше об использовании платформы Office 365 здесь:
- API REST Outlook для центра разработок Outlook
- Обзор разработки на платформе Office 365
- Проверка подлинности приложений и авторизация ресурсов в Office 365
- Вручную зарегистрируйте приложение с помощью Azure AD, чтобы оно могло получить доступ к API Office 365
- Справка для REST API Почты
- Справка по REST API для Календаря
- Справка по API REST Контактам
- Ссылочные ресурсы для Почты, Календаря, Контактов и Задания API-интерфейсов REST