Outlook Streaming Notifications REST API 参考（预览）

项目
05/31/2017

备注

该版本的文档涵盖了预览版的推送通知 API。预览功能在最终确定之前可能会发生变化，并可能会让使用它们的代码无法正常运行。正因为如此，一般而言，生产代码中只应使用生产版本的 API。如果可用，v2.0 版目前是首选版本。

Outlook Streaming Notifications REST API 通过直接连接发送通知，让客户端应用了解有关用户邮箱数据的更改。这些数据可能位于用户的邮件、日历、联系人或由 Office 365 中的 Azure Active Directory 保护的任务数据，以及特定于以下域中的 Microsoft 帐户：Hotmail.com、Live.com、MSN.com、Outlook .com 和 Passport.com。

备注

为简便起见，本文的其余部分使用 Outlook.com 来指代这些 Microsoft 帐户域。

概述

Office 365 流式通知服务与客户端建立直接连接，并传递客户端应用请求的数据更改通知。

当应用订阅特定资源上的某种更改事件的通知（例如用户收件箱中的邮件）时，Office 365 服务器与客户端之间会建立长期连接。发生触发事件时（例如收件箱中的新邮件），Office 365 服务将通知发送给客户端。客户端解析通知，并根据其业务逻辑采取措施，例如获取新消息和更新未读计数。

比较流式和推送通知

邮件、日历和 CRM 应用程序通常使用通知来更新其本地缓存、相应的客户端视图或更改后的后端系统。Outlook 同时支持流式和推送通知。推送通知要求客户端提供监听器 Web 服务以从 Office 365 服务器获取通知，而流式通知仅需要客户端与 Office 365 服务器之间的直接连接。与服务器建立连接后，连接将在指定的时间期间保持打开。在此期间，客户发布了一个单次长期GetNotifications请求；无论何时发生触发事件，服务器都可以作为响应流的一部分直接发送通知。这一直持续到连接超时，客户端断开连接，或者网络出现问题。

使用流式通知 REST API

身份验证

要订阅、获取并关闭通知，请为要通知的资源类型指定适当的范围。

最低要求的范围

以下阅读范围之一对应于目标资源：

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_日历
wl.basic

与其他 Outlook REST API 类似，对于 Outlook 推送通知 API 的每个请求，都应该包含有效的访问令牌。获取访问令牌需要注册和识别应用，并获得相应的授权。

你可以了解更多有关简化注册和授权选项的信息。在推送通知 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

如果订阅请求成功，则返回订阅 ID。默认情况下，除非客户端开始在连接上收听通知，否则此订阅 ID 将在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 并包含订阅 ID。示例响应如下：

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 条件将通知限制为项目的子集。例如，以下订阅请求会创建一个只有在对主题字段为“Supplements”的消息进行更改时触发通知的订阅。

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

仅为资源集合设置的订阅会返回已更改的资源实例的 ID。您需要分别获取该实例的属性。上面第一个订阅请求是该类型订阅的一个示例。在下一部分的通知流只显示通知中返回的资源 ID。

你也可以使用一个$select 参数，指定感兴趣的属性，并在流式通知中返回这些属性值。

以下是一个请求在创建事件时包含 subject 属性的流通知示例：

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

成功订阅丰富的流式通知后，收听通知得到包含Subject 属性的丰富通知有效载荷。

收听通知

客户端为指定的订阅创建一个长期待用的 POST 连接，以请求服务器启动流式通知。

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

该 POST 请求在指定ConnectionTimeoutinMinutes 到达前未完成，并且服务器在响应中结束 JSON blob，或者如果还有其他问题并且客户端或服务器关闭连接。

只要连接处于打开状态，所有使用连接的订阅都会自动续订。如果连接结束，这些订阅也将在90分钟后过期，除非客户端为这些订阅设置了新的连接。

确保 POST 请求的代码处理返回状态码 HTTP 404 Not found，如果指定的订阅已经过期，将会返回。如果发生，在再次收听其通知之前请求新的订阅。

所需的正文参数	类型	说明
ConnectionTimeoutInMinutes	int32	连接应保持活动的分钟数。
KeepAliveNotificationIntervalInSeconds	int32	服务器用于发送保持活动通知的间隔，以通知客户端连接保持打开状态。
SubscriptionIds	集合（字符串）	此连接上通知的订阅 ID。

示例侦听请求

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

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

通过在 POST 请求中包含多个订阅 ID，您可以使用相同的长连接来侦听多个订阅的通知。

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

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

示例通知流

一旦服务设置完毕，客户端就会收到通知 JSON blob 的开头。

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

服务器以固定的时间间隔发送保持活动通知以保持连接处于打开和活动状态。这个时间间隔由客户端在 KeepAliveNotificationIntervalInSeconds 属性中设置。保持活动通知的格式如下所示：

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

丰富的通知有效负载示例

如果您的订阅请求指定了要返回的某些属性，则通知有效载荷将包含这些属性的值。遵循上面的示例订阅丰富的通知，一个丰富的通知有效载荷中包括如下 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"
      }
    }
  ]
}

关闭连接

当达到 ConnectionTimeoutInMinutes 属性指定的超时时间，服务器关闭连接并发送 JSON blob 的结尾，如下所示。

]
}

在其他情况下，例如网络问题和服务器重新启动等情况，连接可能会丢失。客户端可以使用保持活动通知来确定连接是否仍处于活动状态或已被丢失。在后一种情况下，客户端应尝试使用现有订阅 ID 重新连接。如果订阅 ID 已过期，则应该提出新的订阅请求来重新建立连接。

如果客户端不想再收听订阅，则客户端可以取消 POST 请求并放弃连接。下一次服务器尝试发送通知时，将收到错误，检测到连接丢失，停止保持活动通知并关闭连接。

通知实体和枚举

属性	类型	说明	可写入？	Filterable
资源	string	指定将监视其是否发生更改的资源。	是	无
ChangeType	ChangeType	指示将引发通知的事件类型。请参阅 ChangeType 了解支持的类型。	是	无

通知

基类：实体

属性	类型	说明	可写入？	Filterable
SubscriptionId	string	订阅的唯一标识符。	否	无
SequenceNumber	int32	指示更改通知的序列值。	否	无
ChangeType	string	指示引发通知的事件的类型。请参阅 ChangeType 了解支持的类型。	否	无
资源	string	字符串	否	无
ResourceData	实体	标识已更改的实体。这是一个导航属性。	否	无

ChangeType

一个枚举，用于指定发生在支持资源上的可引发通知的事件类型。

支持的值：

Acknowledgment
Created
Deleted
Missed。当通知服务无法发送请求的通知时，会发生 Missed 通知。
Updated

后续步骤

无论你准备开始构建应用还是只想了解更多信息，我们都已为你考虑周全。

开始使用邮件、日历和联系人 REST API。
想要查看一些示例吗？我们就有。

或者，了解有关使用 Office 365 平台的更多信息：

通过