Справка по API REST Push-уведомлений Outlook

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

Примечание

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

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

Примечание

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

Не интересуетесь бета-версией API? В оглавлении слева, перейдите к разделу Ссылка API REST 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-уведомлений

• Подписаться на уведомления
• Обновить подписку
• Удалить подписку

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

Процесс подписки

Процесс подписки выглядит следующим образом:

1. Клиентское приложение делает запрос на подписку (POST) для определенного ресурса. Он включает URL-адрес уведомления, среди других свойств.

2. Служба уведомлений Outlook пытается проверить URL-адрес уведомления с помощью службы прослушивателя. Он включает маркер проверки подлинности в запросе проверки.

3. Если служба прослушивателя успешно проверяет URL-адрес, он возвращает ответ успеха в течение 5 секунд следующим образом:

   • Устанавливает тип контента в заголовке ответа в text \ plain.
   • Включает в тело ответа тот же маркер проверки.
   • Возвращает код ответа HTTP 200. В дальнейшем слушатель может отменить маркер проверки.

4. В зависимости от результата проверки URL-адреса служба уведомлений Outlook отправляет ответ клиентскому приложению:

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

5. Получив успешный ответ, клиентское приложение сохраняет идентификатор подписки для корреляции будущих уведомлений с этой подпиской.

Запрос на подписку

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

POST https://outlook.office.com/api/beta/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/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

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

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

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

{
   "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
   "Resource": "https://outlook.office.com/api/beta/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/beta/me/subscriptions HTTP/1.1 
Content-Type: application/json 
 
{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/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/beta/me/subscriptions HTTP/1.1 
Content-Type: application/json 
 
{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/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/beta/me/subscriptions HTTP/1.1 
Content-Type: application/json 
 
{ 
  @odata.type:"#Microsoft.OutlookServices.PushSubscription", 
  Resource: "https://outlook.office.com/api/beta/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/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/beta/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/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/beta/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/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')",
    "Id": "Mjk3QNERDQQ==",
    "Resource": "https://outlook.office.com/api/beta/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/beta/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/beta/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/beta/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/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
    "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
    "Resource": "https://outlook.office.com/api/beta/me/events?$select=Subject",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myRichNotifyClient",
    "ChangeType": "Created"
}

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

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

{
  "@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"
      }
    }
  ]
}

Обновить подписку

Обновите подписку на максимальную длину с момента запроса продления.

PATCH https://outlook.office.com/api/beta/me/subscriptions/{subscriptionId}

Длина подписки по умолчанию составляет 7 дней для запросов на подписку, для которых не требуются особые свойства экземпляра в ответе, и 1 день для подписки на форматированные уведомления.

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

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

PATCH https://outlook.office.com/api/beta/me/subscriptions/Mjk3QNERDQQ==

{
   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   "SubscriptionExpirationDateTime": "2015-05-28T17:17:45.9028722Z"
}

Ответ

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

Удалить подписку

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

DELETE https://outlook.office.com/api/beta/me/subscriptions('{subscriptionId}')

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

Delete https://outlook.office.com/api/beta/me/subscriptions('Mjk3QNERDQQ==')

Ответ

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

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

Subscription

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

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

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

Уведомление

Обозначает уведомление, отправленное клиенту. В случае push-уведомлений уведомление отправляется в службу прослушивателя, указанную клиентом.

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

Свойство	Тип	Описание	Подлежит записи?	Фильтруемое?
SubscriptionId	string	Уникальный идентификатор подписки.	Нет	Нет
SubscriptionExpirationDateTime	Edm.DateTimeOffset	Указывает дату и время истечения срока действия подписки на уведомления. Время в UTC.	Да	Недоступно
SequenceNumber	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 отправляется, когда служба уведомлений не может отправить запрошенное уведомление.
• Обновлено

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

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

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

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

• API REST Outlook для центра разработок Outlook
• Обзор разработки на платформе Office 365
• Проверка подлинности приложений и авторизация ресурсов в Office 365
• Вручную зарегистрируйте приложение с помощью Azure AD, чтобы оно могло получить доступ к API Office 365
• Справка для REST API Почты
• Справка по REST API для Календаря
• Справка по REST API для Контактов
• REST API для Задачи (предварительная версия)
• Справочник ресурсов по API REST Почты, Календаря, Контактов и Задачи