使用 Outlook REST API （版本 2.0）

  • 项目

适用于：Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

备注

使用 Microsoft Graph 为包括 Outlook 在内的 Microsoft 365 服务生成更丰富的方案。 了解如何 转换到基于 Microsoft Graph 的 Outlook REST API。

Outlook REST API包含以下子集，以允许访问Office 365、Hotmail.com、Live.com、MSN.com、Outlook.com和Passport.com中的用户邮箱数据。

下表列出了每个子集的核心功能可用的第一个版本。 请注意在子集中，可以在更高版本中随后添加新功能和 API。

API 子集 可用版本
批量处理多个 API 调用 v2.0，beta
日历 API v2.0，v1.0，beta
联系人 API v2.0，v1.0，beta
数据扩展 API v2.0，beta
扩展属性 API v2.0，beta
邮件 API v2.0，v1.0，beta
推送通知 API v2.0，beta
流通知 API（预览） beta
人员 API beta
任务 API v2.0，beta
用户照片 API v2.0，beta

备注

本文的其余部分介绍适用于 Outlook REST API 所有子集的通用信息。 为了简化参考，本文的其余部分使用 Outlook.com 来包括 Hotmail.com、Live.com、MSN.com、Outlook.com 和 Passport.com 等域名中的帐户。

注册并验证您的应用

要使用 Outlook REST API 访问用户的邮箱数据，您的应用程序应处理注册和用户授权：

  1. 首先，注册您的应用程序以访问 Outlook REST API。 然后，您可以在您的应用中实施 API 调用。

  2. 在运行时，获取来自用户的授权并通过 REST API 请求访问用户邮箱。

目前有两种处理应用程序注册和用户授权的方法：

Azure AD v2 身份验证端点

Azure AD v2 身份验证端点简化了构建可与 Microsoft 组织和个人帐户配合使用的应用程序。 实现单个按钮可登陆工作、学校和个人帐户用户。

这个聚合编程模型是最新的方法，由下列选项组成：

这种方法为您提供了无缝的应用程序注册和用户授权体验，以获取适当的令牌访问 Office 365 和/或 Outlook.com 上的用户邮箱数据。 如果您正在为 Outlook.com开发应用程序，则必须使用此方法。

不需要在应用程序注册期间请求权限，v2身份验证端点允许您在运行时根据相应的用户操作动态提示并请求必要的权限。

这个融合的编程模型由几个组件组成，所以如果使用一个组件，您也应该使用其他组件。

要了解更多信息，请参阅 入门示例和 使用 v2 身份验证端点验证 Office 365 和 Outlook.com API。

重要

当您 创建或更新应用程序时，请确保您的应用可以处理已启用的 Outlook.com 邮箱，并且您可以使用 Outlook REST API 和等待启用的邮箱进行访问。 了解更多关于 测试和 Outlook.com 场景处理的信息。

使用Azure AD和OAuth注册并进行身份验证

这是早期仅访问 Office 365 上邮箱数据的方法。 如果您打算访问 Outlook.com上的数据，或者为Office 365创建新的应用程序，请转而使用 v2身份验证端点 。

目前，要访问 Office 365 邮箱数据，您可以像之前一样继续在 Azure AD 中注册应用程序，并指定您的应用程序所需的适当权限范围 。 在运行时，您的应用可以继续使用 Azure AD 和 OAuth 来验证应用程序请求。 您可以在 Office 365 应用程序认证方案中了解更多详情。 您应该计划一个 升级路径。

通过这种方法，您可以选择直接在 Office 365 应用程序中调用，或通过使用 Office 365 客户端库来访问 Outlook REST API。

升级路径

v2身份验证端点已 从预览升级到 Outlook和Outlook.com开发人员的通用（GA）状态。

如果您有一个访问Office 365邮箱数据的生产应用程序，或如果您正在创建一个针对Office 365或Outlook.com的 新 应用程序，计划将v2身份验证端点与最新的Outlook端点配合使用（https://outlook.office.com/，请参阅下面的内容），编写一组同时适用于组织Office 365和个人Outlook.com用户的代码。

如果您有一个使用 Windows Live API 访问 Outlook.com 邮箱数据的生产应用程序，则必须重新编写应用程序以使用 v2 身份验证端点和 Outlook REST API。 由于 Windows Live API 不适用于 Outlook.com，并且 Outlook.com 用户为 Outlook REST API 启用了其邮箱，因此尝试运行此类 Windows Live API 应用时，这些用户将收到 HTTP 404 错误。

另一方面，Outlook REST API 为你提供了新的机会 — 你可以从诸如 Node、Python、Swift、Java 等常用语言列表中进行选择，一次编写应用就可适用于 Web、iOS、Android 或 Windows 设备上的 Outlook.com 和 Office 365 用户。

备注

如果您打算让您的生产应用继续_仅_访问 Outlook.com 邮箱数据，您可以继续使用相同的 Windows Live 作用域来访问大部分 Outlook REST API。 有关更多信息，请参阅使用 Windows Live 范围和 Outlook REST API 访问 Outlook.com 邮箱数据。

无论您采用何种方法进行应用注册和用户授权，或者您的应用以 Office 365 或 Outlook.com 邮箱数据为目标，最新的 Outlook REST 端点都已投入使用，您可以在准备就绪后立即在 REST API 调用中使用：

https://outlook.office.com/api/{version}/{user_context}

对于仅限 Office 365 邮箱数据，以下 Outlook REST 端点将继续运行一段时间：

https://outlook.office365.com/api/{version}/{user_context}

了解更多关于下述支持的 REST 操作、端点和版本信息。

重要

  • Outlook REST API 端点不再支持基本授权https://outlook.office.com。 使用v2身份验证端点或 Azure AD 使用新的 Outlook REST API 端点的应用程序执行授权和身份验证。
  • 为了在使用新的 Outlook REST 端点时获得最佳性能，请x-AnchorMailbox为每个请求添加一个标头并将其设置为用户的电子邮件地址。 例如： x-AnchorMailbox:john@contoso.com
  • 由于在 Outlook.com 上为 Outlook REST API 启用邮箱需要一段时间，因此您现有的 Outlook.com 帐户可能需要一段时间才能启用。 要测试访问已启用的 Outlook.com 邮箱上的数据的应用，你可以通过向 outlookdev@microsoft.com 发送电子邮件，请求一个新的、已启用的 Outlook.com 开发人员预览帐户。
  • 如果您的应用程序访问 Outlook.com 邮箱数据，它应准备处理用户的邮箱尚未启用 Outlook REST API 的情况。 在这种情况下，当您发出 REST 请求时，会出现如下错误：
    • HTTP 错误：404
    • 错误代码： MailboxNotEnabledForRESTAPI or MailboxNotSupportedForRESTAPI
    • 错误消息：“此邮箱尚不支持REST API。
  • 有关使用 v2 身份验证端点的代码示例，请参阅 dev.outlook.com。

使用 Windows Live 作用域和 Outlook REST API 访问 Outlook.com 邮箱数据

如果您的 Outlook.com 的生产应用程序使用 Windows Live 权限范围，并且您不打算针对 Office 365 邮箱数据，则可以针对大部分 Outlook REST API 继续使用这些 Windows Live 范围权限。 下表显示了 Windows Live 作用域如何映射到 Outlook REST API 作用域。 请注意，Mail.Read 没有 Windows Live 作用域直接映射；您的应用可以使用 wl.imap 访问需要 Mail.Read 的 Outlook REST API 操作。

Windows Live 范围 Outlook REST API 范围
wl.basic User.Read，Contacts.Read
wl.calendars Calendars.Read
wl.calendars_update Calendars.ReadWrite
wl.contacts_create Contacts.ReadWrite
wl.contacts_calendars Calendars.Read
wl.emails User.Read
wl.events_create Calendars.ReadWrite
wl.imap Mail.ReadWrite，Mail.Send

支持的REST的操作和端点

若要与Outlook REST API互动，请发送使用支持方法的HTTP请求：GET、POST、MERGE或DELETE。 POST 和 PATCH 请求正文和服务器响应以 JSON 有效载荷形式发送。

路径 URL 资源名称和查询参数不区分大小写。不过，您分配的值、实体 ID 和其他 base64 编码值均区分大小写。

所有 Outlook REST API 请求都使用以下新的根 URL 格式：

https://outlook.office.com/api/{version}/{user_context}

通过适当的用户授权，根 URL 中的 REST API 可以访问 Office 365 和Outlook.com 上的邮箱数据。 本文的其余部分将对端点中的 REST API 进行说明。

如果你的代码使用预先存在的根 URL https://outlook.office365.com/api/{version}/{user_context}，则你的代码将继续在 Office 365 运行一段时间，但你应该计划切换到新的根 URL。

重要

为了获得最佳性能，当使用新的根 URL 创建 REST 请求时，请添加一个 x-AnchorMailbox 标头并将其设置为用户的电子邮件地址。 同样，处理尚未为 Outlook REST API 启用的 Outlook.com 用户邮箱的情况；检查错误代码MailboxNotEnabledForRESTAPI 和 MailboxNotSupportedForRESTAPI。 在这里可查看更多信息。

中国开发者注意事项

  • 如果你正在开发面向中国的 Office 365 应用程序，应继续使用中国的 Office 365 API 端点。

  • 如果你正在为中国的 Outlook.com 创建应用，请尝试 v2 身份验证端点，并使用以下新的 Outlook REST 端点：https://outlook.office.com/api/{version}/{user_context}。

支持的API 版本

{version} 表示指定根 URL 中的 Outlook REST API 版本。 您可以指定下列中的一个值：

  • v1.0。 这是处于公开发行 (GA) 状态中最早的版本，可用于生产代码。 URL 示例：http://outlook.office.com/api/v1.0/me/events。

  • v2.0。 此版本也处于 GA 状态，可用于生产代码。 URL 示例：http://outlook.office.com/api/v2.0/me/events。 此版本包含可能会中断 v1.0 的更改，以及已成熟并已从预览升级到 GA 状态的其他 API 集。

  • beta。 此版本为预览状态，不应在生产代码中使用。 URL 示例：http://outlook.office.com/api/beta/me/events。 此版本包含GA中的最新API以及预览中的其它API集，并且可能会在最终确定前更改。

支持Outlook REST API中的大部分REST操作，其行为与上述所列版本中描述方式相同。

目标用户

除 User Photo REST API 外，因为 Outlook REST API 请求始终代表当前用户执行，{user_context}即为当前登录的用户。

对于用户照片 REST API，{user_context}可以是登录用户，也可以是用户 ID 指定的用户。

无论使用哪种 Outlook REST API，都可以采用以下方式之一指定{user_context}在 REST 中_的请求_：

  • 使用me快捷方式：/api/{version}/me。 根URL变成 https://outlook.office.com/api/{version}/me。

  • 使用users/{upn}格式传递 UPN 或登录用户的代理地址，例如：/api/beta/users/sadie@contoso.com。 在这个示例中，根 URL 将变成 https://outlook.office.com/api/beta/users/sadie@contoso.com。

  • 使用 users/{AAD_userId@AAD_tenandId} 格式，利用 Azure Active Directory 中的用户 ID 和租户 ID。 例如， users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77根 URL 将变为 https://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77。

如何使用是一个偏好问题。

在服务器_响应中_，用户上下文用这种格式标识：users/{AAD_userId@AAD_tenandId}。

访问集合中的项

Outlook REST API 支持在实体集合中指定项目的两种方法。 评价一致，所以使用率是一个优先事项。

  • 在采集后的 URL 段中，例如： /api/{version}/me/events/AAMkAGI3...

  • 在括号中作为引用字符串，例如： /api/{version}/me/events('AAMkAGI3...')

使用客户端库访问 Outlook REST API

Office 365 API 客户端库可以更轻松地与 REST API 交互：

它们帮助管理身份验证令牌，并简化在 Office 365 上查询和使用数据所需的代码。

关闭较早的预览端点

如果您已经在使用https://outlook.office.com/api 或https://outlook.office365.com/api作为根 URL
要访问 Outlook REST API，弃用不会影响您。 如果您仍在使用较早的预览端点，请继续阅读https://outlook.office365.com/ews/odata。

Outlook REST API 于 2014 年 10 月从初始预览版变为 v1.0 公开发行版。 为了完成这个转换，我们于 2015 年 10 月 15 日关闭了旧的预览端点 https://outlook.office365.com/ews/odata。

我们要求所有使用旧端点 https://outlook.office365.com/ews/odata 的应用和服务于 2015 年 10 月 15 日之前移动到 https://outlook.office.com/api/v1.0。 v1.0 是截止该日期之前需要移动到的最低公开发行版 (GA) 端点。

或者，您可以使用首选 GA 端点 v2.0（https://outlook.office.com/api/v2.0），或预览端点（https://outlook.office.com/api/beta）以预览状态尝试最新的 API。 请记住，一般来说，预览状态下的API可能会在最终确定之前发生变化。 如果您使用它们，请准备好验证应用中的功能并进行适当的更改。 当预览 API 完成时，您还可以在 GA 端点中访问这些增强功能。

后续步骤

继续使用 Outlook REST API：