Outlook 邮件 REST API 的参考（版本 2.0）

项目
06/30/2018

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

备注

为简化引用，本文的其余部分使用 Outlook.com 来包括这些 Microsoft 帐户域。

对 API 的 2.0 版不感兴趣？ 在左侧的目录中，转到 Office 365 REST API 参考部分，然后选择所需的版本。

概述

Office 365 推送通知服务和 API 与提供带回调地址的 Web 服务的客户端协同工作，并使用 Webhook 向客户端应用发送通知。 Webhook 是通常由可信任第三方后端 Web 服务配置的 HTTP 回调。 Web 服务可以配置 Webhook，以便在一个站点上触发事件来调用另一个站点上的行为。

当应用订阅特定资源的通知（例如用户收件箱中的邮件）时，它会在订阅请求中指定 Webhook 回调 URL。当发生触发事件（例如收件箱中的新邮件）时，Office 365 通知服务会通过 Webhook 将通知推送到回调 URL。反过来，应用根据其业务逻辑采取行动，例如获取新邮件并更新未读计数。

应用程序应在到期前续订订阅。它们也可以随时取消订阅，以停止接收通知。

比较流和推送通知

邮件、日历和 CRM 应用通常使用通知更新其本地缓存、相应的客户端视图或后端系统。 Outlook 同时支持流和推送通知。目前，推送通知通常由移动应用使用，因为它不需要客户端轮询更改，并几乎立即向客户端提供更新。

与流式通知相比，推送通知要求客户端提供自己的 Web 服务才能获取通知，而流式通知仅需要客户端与 Office 365 流通知服务之间建立直接连接。

使用推送通知 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 已从预览升级到正式发布 (GA) 状态。它在 Outlook REST API 的 2.0 和 beta 版本中得到支持。

目标用户

推送通知 API 请求始终代表当前用户执行。

有关 Outlook REST API 所有子集的更多信息，请参阅使用 Outlook REST API。

订阅过程

订阅过程如下：

客户端应用程序为特定资源发出订阅请求 (POST)。它包含一个通知 URL 以及其他属性。
Outlook 通知服务尝试使用侦听器服务验证通知 URL。它在验证请求中包含验证令牌。
如果侦听器服务成功验证了 URL，它将在 5 秒内返回成功响应，如下所示：
- 将响应标头中的内容类型设置为 text\plain。
- 在响应主体中包含相同的验证令牌。
- 返回一个 HTTP 200 响应代码。监听器可以随后丢弃验证令牌。
根据 URL 验证结果，Outlook 通知服务将响应发送到客户端应用：
- 如果 URL 验证成功，则该服务使用唯一的订阅 ID 创建订阅，并将响应发送给客户端。
- 如果 URL 验证失败，则该服务会发送一个包含错误代码和其他详细信息的错误响应。
在收到成功响应后，客户端应用将存储订阅 ID，以便将来的通知与此订阅相关联。

订阅请求

订阅侦听器服务，以便在 Office 365 或 Outlook.com 中更改邮件、日历事件、联系人或任务时接收通知。这是客户开始获取资源（实体或实体集合）通知的第一步。

POST https://outlook.office.com/api/v2.0/me/subscriptions

在请求正文中指定推送订阅请求的以下属性。除了 ClientState，所有的属性都是必需的。有关更多信息，请参阅 通知实体。

odata.type - 包含 "@odata.type":"#Microsoft.OutlookServices.PushSubscription"。** ** PushSubscription 实体定义 NotificationURL。
ChangeType - 指定该资源要监视的事件类型。请参阅 ChangeType 了解支持的类型。
ClientState - 可选属性，指示每个通知应以标头发送相同的 ClientState 值。这让侦听器检查每个通知的合法性。
NotificationURL - 指定通知应发送到的位置。该 URL 代表通常由客户端实施的 Web 服务。
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，并将字符串 {token} 定义为验证令牌。如果客户端应用程序在订阅请求中包含一个 ClientState 标头，则 Outlook 服务也会包括该标头。

订阅响应

订阅响应包括请求中的属性以及以下附加属性：

Id - 客户端应用程序应该保存以便与未来通知相匹配的唯一订阅 ID。
changeType - 除了请求中指定的值之外，响应还包括额外的 Missed 通知类型。
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"
}

查询订阅

您可以通过指定其订阅 ID 来查找任何登录用户的现有订阅的详细信息。例如，查询在上一个示例中创建的订阅：

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 - 客户端应用程序想要通知的事件类型（例如，收到邮件时的 Created 事件类型，或阅读邮件时的 Update 事件类型）。
Resource - 正在监视的特定资源项目的 URL（例如，更改的邮件或事件的 URL）。
ResourceData - 与资源更改相关的通知（例如接收、读取或删除邮件）具有此附加属性，其中包含已更改项目的资源 ID。客户端可以使用此资源 ID 根据其业务逻辑来处理此项目（例如，获取此项目、同步其文件夹）。

备注

Id 属性未用于通知实体。

更改通知有效负载

在以下示例中，如果 ChangeType 设置为 "Created"，当用户收到新事件时，通知服务会发送一个通知。通知标头将包含初始订阅请求中指定的 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="
            }
        }
    ]
}

通过订阅丰富的通知获取实例属性

如前一例子的更改通知有效负载那样，为资源集合设置的推送通知订阅仅返回已更改的资源实例的 ID。您需要分别获取该实例的属性。

如果在订阅请求中使用 $select 参数并指定感兴趣的属性，可以保存一个单独的 GET API 调用。以下是一个请求在创建事件时包含 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"
}

丰富的通知有效负载示例

丰富的通知有效负载包括预订请求中指定的属性的值。在上一个例子中，丰富的通知包括的 Subject 属性类似于：

{
  "@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 响应代码表示响应成功。

删除订阅

通过指定订阅 ID 来删除订阅。

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 实体和枚举

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

通知

代表发送给客户端的通知。在推送通知的情况下，通知被发送到由客户端指定的监听器服务。

基本类型：实体

属性	类型	说明	可写入？	可筛选？
SubscriptionId	字符串	订阅的唯一标识符。	否	否
SubscriptionExpirationDateTime	Edm.DateTimeOffset	指定通知订阅过期的日期和时间。时间是 UTC。	是	无
SequenceNumber	int32	指示更改通知的序列值。	否	无
ChangeType	ChangeType	指示引发通知的事件的类型。枚举值为：创建= 1，更新= 2，删除= 4，错过= 16。当通知服务无法发送请求的通知时，会发生“错过”通知。	否	无
资源	字符串	指定正在监视更改的资源项目。	是	无
ResourceData	实体	标识已更改的实体。这是一个导航属性。	否	无

PushSubscription

代表使用推送通知机制的订阅。

基本类型：订阅

属性	类型	说明	可写入？	可筛选？
NotificationURL	字符串	将接收推送通知的应用程序的 URL。	是	无
SubscriptionExpirationDateTime	Edm.DateTimeOffset	指定通知订阅过期的日期和时间。时间是 UTC。	是	无
ClientState	字符串	指定服务为每个通知发送的 ClientState 标头的值。最大长度为 255 个字符。客户端可以通过比较 ClientState 属性上设置的值与每个通知中收到的 ClientState 标头的值来检查通知是否来自服务。	是	否

ChangeType

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

支持的值：

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

后续步骤

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

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

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

Outlook 邮件 REST API 的参考 （版本 2.0）

概述

比较流和推送通知

使用推送通知 REST API

身份验证

最低要求的范围

API 的版本

目标用户

推送通知操作

订阅我的邮件、日历、联系人或任务中的更改

订阅过程

订阅请求

示例请求

优化通知条件

验证请求

订阅响应

示例响应数据

查询订阅

通知

更改通知有效负载

通过订阅丰富的通知获取实例属性

丰富的通知有效负载示例

续订订阅

示例请求

响应

删除订阅

示例请求

响应

通知 API 实体和枚举

订阅

通知

PushSubscription

ChangeType

后续步骤

其他资源

Outlook 邮件 REST API 的参考（版本 2.0）