比较 Microsoft Graph 和 Outlook REST API 终结点

  • 项目

Outlook REST API 在 Microsoft Graph 和 Outlook API 终结点中均可用， https://outlook.office.com/api () 。 API 通常提供相同功能，并使用相同的资源类型。

注意

Outlook REST API 已弃用。

Outlook REST 终结点将于 2024 年 3 月完全停用。 迁移现有应用以使用 Microsoft Graph。 这不包括使用 OAuth 对 IMAP、POP 或 SMTP 连接进行身份验证中所述的 OAuth2 令牌受众。

应使用哪个终结点？

使用 Microsoft Graph，Outlook REST v2.0 正在取消授权。 通过 Microsoft Graph 终结点，可以访问 Outlook 和更多服务和功能，包括其他 Office 365 服务、企业移动性 + 安全性和 Windows 10。 选择 Microsoft Graph 终结点，可便于应用获取访问令牌，从而有权访问 Outlook 数据和其他资源，而无需提出多个令牌请求。

功能差异

部分功能暂时只适用于 Outlook 终结点，或只适用于 Microsoft Graph 的 beta 版本。

注意

我们一直在努力将 Outlook 终结点当前的所有可用功能都纳入 Microsoft Graph。 请务必定期再回来看看，因为此列表会不断更新。

功能 终结点差异
Outlook 任务 可通过 待办事项 API 访问 Microsoft Graph 中的用户任务
富通知 借助 Outlook API，开发人员可以使用 $select 参数，请求与通知有效负载一起随附特定字段。 Microsoft Graph 目前仅在 beta 终结点中支持此功能，并计划尽快将其发布到 v1.0。
流式处理通知 Outlook API 支持在 beta 终结点上使用预览版流式处理通知。 Microsoft Graph 不支持此功能，它不是路线图的一部分。

从 Outlook 终结点迁移到 Microsoft Graph

Microsoft Graph 终结点和 Outlook 终结点在 API 方面非常相似。 不过，也有一些差异需要注意，尤其是当要迁移到 Microsoft Graph 或在同一应用中使用这两个终结点时。

API 版本

Microsoft Graph API 有 v1.0 和 beta 这两个版本，而 Outlook API 则有 v1.0、v2.0 和 beta 这三个版本。 Microsoft Graph v1.0 匹配 Outlook v2.0，Microsoft Graph beta 匹配 Outlook beta。

OAuth 范围

虽然 Microsoft Graph 和 Outlook 终结点同时依赖 Azure AD 颁发的令牌，并且所用的权限相同，但应用请求获取这些权限的方式因每个终结点而略有不同。

Azure v2 OAuth2 终结点

如果应用使用 OAuth2 Azure AD v2.0 终结点，应用通过身份验证或令牌请求中的 scope 参数来请求获取权限范围。

  • 对于 Microsoft Graph，应用指定以 https://graph.microsoft.com/ 为前缀的权限。 例如，应用可以在 scope 参数中添加 https://graph.microsoft.com/Mail.Read，从而请求获取 Mail.Read 权限。
  • 对于 Outlook 终结点，应用指定以 https://outlook.office.com/ 为前缀的权限。 例如，应用可以在 scope 参数中添加 https://outlook.office.com/Mail.Read，从而请求获取 Mail.Read 权限。

注意

如果范围中没有域，假定为 Microsoft Graph。

为一个终结点颁发的令牌对另一个终结点无效。 此外，也不能在一个请求中混用两个终结点的权限。

Azure AD v2.0 终结点仅支持对 Microsoft Graph 终结点使用客户端凭据流。 如果应用需要对 Outlook 终结点使用仅应用令牌，应用必须使用 Azure AD v1.0 终结点。

Azure v1 OAuth2 终结点

如果应用使用 Azure AD v1.0 终结点，应用在 Azure 门户中的应用注册期间指定所需权限。

  • 对于 Microsoft Graph，在添加所需权限时选择“Microsoft Graph”API。
  • 对于 Outlook 终结点，在添加所需权限时选择“Office 365 Exchange Online”API。

资源属性名

Microsoft Graph 和 Outlook 之间的资源大致相同。 但是，两个端点以不同方式处理属性名称的大小写。 Microsoft Graph 将 camelCase 用于属性名称，而 Outlook 使用 PascalCase。 两者之间的转换只需转换大小写。 下表中指定了更改的属性名称。

例如，Microsoft Graph 消息资源定义 subject、from 和 receivedDateTime 等属性。 在 Outlook 终结点，这些属性被命名为 Subject、From 和 ReceivedDateTime。

更改的属性名称

以下属性名称在 Microsoft Graph 和 Outlook 之间有所不同。

资源类型 Microsoft Graph 属性 Outlook 属性
contact mobilePhone MobilePhone1

跟踪更改（同步）

这两个终结点都支持在集合中查询与同步状态相关的更改。 虽然功能相同，但方法略有不同。

在 Microsoft Graph 终结点上，更改是使用 delta 查询进行查询。 这对集合实现为 delta 函数。

在 Outlook 终结点上，更改是通过将头添加到常规资源集合查询进行查询。

批处理

这两个终结点都支持将最多 20 个单独请求批处理为一个 HTTP 请求。

Microsoft Graph 批处理将多个 API 请求编码成内容类型为 application/json 的 JSON 正文。

除了 JSON 正文格式以外，Outlook 终结点批处理还支持内容类型为 multipart/mixed 的多部分正文格式。

示例：检索邮件

让我们看一个简单的示例。 在这种情况下，Web 应用程序请求用户收件箱中的邮件列表。

Microsoft Graph

首先，该应用会让用户登录来授权应用程序。 由于应用程序使用 Microsoft Graph 作用域 Mail.Read，授权 URL 如下所示：

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+Mail.Read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

一旦应用程序有了访问令牌，它将发送以下请求：

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject,from,receivedDateTime,isRead
Accept: application/json
Authorization: Bearer <token>

服务器返回以下响应：

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('b63d5fb9-4f43-44c4-8f9d-fd0727842876')/mailFolders('inbox')/messages(subject,from,receivedDateTime,isRead)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject%2cfrom%2creceivedDateTime%2cisRead&$skip=1",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "id": "AAMkAGI2...",
      "receivedDateTime": "2015-11-03T03:21:04Z",
      "subject": "Scrum",
      "isRead": false,
      "from": {
        "emailAddress": {
          "name": "user0TestUser",
          "address": "user0@contoso.com"
        }
      }
    }
  ]
}

Outlook

首先，该应用会让用户登录来授权应用程序。 由于应用程序使用 Outlook 作用域 https://outlook.office.com/Mail.Read，授权 URL 如下所示：

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+https%3A%2F%2Foutlook.office.com%2Fmail.read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

一旦应用程序有了访问令牌，它将发送以下请求：

GET https://outlook.office.com/api/v2.0/me/mailfolders/inbox/messages?$top=1&$select=Subject,From,ReceivedDateTime,IsRead
Accept: application/json
Authorization: Bearer <token>

服务器返回以下响应：

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "@odata.nextLink": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "Id": "AAMkAGI2...",
      "ReceivedDateTime": "2015-11-03T03:21:04Z",
      "Subject": "Scrum",
      "IsRead": false,
      "From": {
        "EmailAddress": {
          "Name": "user0TestUser",
          "Address": "user0@contoso.com"
        }
      }
    }
  ]
}