比较 Microsoft Graph 和 Outlook REST API 终结点Compare Microsoft Graph and Outlook REST API endpoints

Outlook REST API 在 Microsoft Graph 和 Outlook API 终结点 (https://outlook.office.com/api) 中都可用。此类 API 通常功能相同,并使用相同的资源类型。The Outlook REST APIs are available in both Microsoft Graph and the Outlook API endpoint (https://outlook.office.com/api). The APIs generally provide the same functionality and use the same resource types.

备注

Outlook REST API 已弃用。The Outlook REST APIs are deprecated.

Outlook REST 终结点将于 2022 年 11 月完全停用。The Outlook REST endpoints will be fully decommissioned in November 2022. 迁移现有应用以使用 Microsoft Graph。Migrate existing apps to use Microsoft Graph.

应使用哪个终结点?Which endpoint should I use?

尽可能使用 Microsoft Graph。Use Microsoft Graph whenever possible. 通过 Microsoft Graph 终结点,可以访问 Outlook 和更多服务和功能,包括其他 Office 365 服务、企业移动性 + 安全性和 Windows 10。The Microsoft Graph endpoint lets you access Outlook and many more services and features, including other Office 365 services, Enterprise Mobility + Security, and Windows 10. 选择 Microsoft Graph 终结点,可便于应用获取访问令牌,从而有权访问 Outlook 数据和其他资源,而无需提出多个令牌请求。Choosing the Microsoft Graph endpoint allows your app to get an access token that can provide access to both Outlook data and other resources, without having to make multiple token requests.

功能差异Feature differences

但是,有些功能要么只能在 Outlook 终结点上使用,要么只能在 Microsoft Graph 的 beta 版本中使用。如果应用需要这些功能,则应通过 Outlook 终结点访问。There are some features that are currently either only available on the Outlook endpoint, or are only in beta in Microsoft Graph. If your app needs these features, you should access them via the Outlook endpoint.

备注

我们一直在努力将 Outlook 终结点当前的所有可用功能都纳入 Microsoft Graph。We are constantly working to incorporate all of the features currently available on the Outlook endpoint into Microsoft Graph. 请务必定期再回来看看,因为此列表会不断更新。Be sure to check back periodically as this list is updated.

功能Feature 终结点差异Difference between endpoints
Outlook 任务Outlook tasks 可通过 待办事项 API 访问 Microsoft Graph 中的用户任务Access to users' tasks in Microsoft Graph is available through the To Do API
富通知Rich notifications 借助 Outlook API,开发人员可以使用 $select 参数,请求与通知有效负载一起随附特定字段。The Outlook API allows developers to request specific fields to be included with the notification payload by using the $select parameter. Microsoft Graph 不支持此项功能。Microsoft Graph does not support this feature.
流式处理通知Streaming notifications Outlook API 支持在 beta 终结点上使用预览版流式处理通知。The Outlook API supports streaming notifications in preview on the beta endpoint. Microsoft Graph 不支持此功能。Microsoft Graph does not support this feature.

从 Outlook 终结点迁移到 Microsoft GraphMoving from Outlook endpoint to Microsoft Graph

Microsoft Graph 终结点和 Outlook 终结点在 API 方面非常相似。The APIs are very similar on the Microsoft Graph endpoint and the Outlook endpoint. 不过,也有一些差异需要注意,尤其是当要迁移到 Microsoft Graph 或在同一应用中使用这两个终结点时。However, there are some differences to be aware of, especially if you are migrating to Microsoft Graph or using both endpoints in the same application.

API 版本API versions

Microsoft Graph API 提供了两个版本:v1.0beta,而 Outlook 提供了 v1.0v2.0beta。Microsoft Graph v1.0 匹配 Outlook v2.0,而 Microsoft Graph beta 匹配 Outlook betaThe Microsoft Graph API offers two versions: v1.0 and beta, while Outlook offers v1.0, v2.0, and beta. Microsoft Graph v1.0 matches Outlook v2.0, and Microsoft Graph beta matches Outlook beta.

OAuth 范围OAuth scopes

虽然 Microsoft Graph 和 Outlook 终结点同时依赖 Azure AD 颁发的令牌,并且所用的权限相同,但应用请求获取这些权限的方式因每个终结点而略有不同。While the Microsoft Graph and Outlook endpoints both rely on Azure AD-issued tokens, and the permissions used are the same, the way that your application requests those permissions is slightly different for each endpoint.

Azure v2 OAuth2 终结点Azure v2 OAuth2 endpoint

如果应用使用 OAuth2 Azure AD v2.0 终结点,应用通过身份验证或令牌请求中的 scope 参数来请求获取权限范围。Apps that use the Azure AD v2.0 endpoint for OAuth2 request permission scopes in the scope parameter in an authentication or token request.

  • 对于 Microsoft Graph,应用指定以 https://graph.microsoft.com/ 为前缀的权限。For Microsoft Graph, apps specify permissions prefixed with https://graph.microsoft.com/. 例如,应用可以在 scope 参数中添加 https://graph.microsoft.com/Mail.Read,从而请求获取 Mail.Read 权限。For example, an app can request the Mail.Read permission by including https://graph.microsoft.com/Mail.Read in the scope parameter.
  • 对于 Outlook 终结点,应用指定以 https://outlook.office.com/ 为前缀的权限。For the Outlook endpoint, apps specify permissions prefixed with https://outlook.office.com/. 例如,应用可以在 scope 参数中添加 https://outlook.office.com/Mail.Read,从而请求获取 Mail.Read 权限。For example, an app can request the Mail.Read permission by including https://outlook.office.com/Mail.Read in the scope parameter.

备注

如果范围中没有域,假定为 Microsoft Graph。If a domain is not included in a scope, Microsoft Graph is assumed.

为一个终结点颁发的令牌对另一个终结点无效。Tokens issued for one endpoint are not valid for the other. 此外,也不能在一个请求中混用两个终结点的权限。Additionally, you cannot mix permissions for one endpoint with permissions for the other in a single request.

Azure AD v2.0 终结点仅支持对 Microsoft Graph 终结点使用客户端凭据流The Azure AD v2.0 endpoint only supports the client credentials flow for the Microsoft Graph endpoint. 如果应用需要对 Outlook 终结点使用仅应用令牌,应用必须使用 Azure AD v1.0 终结点。Apps that need to use an app-only token with the Outlook endpoint must use the Azure AD v1.0 endpoint.

Azure v1 OAuth2 终结点Azure v1 OAuth2 endpoint

如果应用使用 Azure AD v1.0 终结点,应用在 Azure 门户中的应用注册期间指定所需权限。Apps that use the Azure AD v1.0 endpoint specify their required permissions during app registration in the Azure Portal.

  • 对于 Microsoft Graph,在添加所需权限时选择“Microsoft Graph”API。For Microsoft Graph, choose the Microsoft Graph API when adding required permissions.
  • 对于 Outlook 终结点,在添加所需权限时选择“Office 365 Exchange Online”API。For the Outlook endpoint, choose the Office 365 Exchange Online API when adding required permissions.

资源属性名Resource property names

Microsoft Graph 和 Outlook 之间的资源大体相同。但是,两个终结点处理属性名称大小写的方式不同。Microsoft Graph 使用 camelCase 处理属性名称,而 Outlook 使用 PascalCase。两者之间的翻译只需转换大小写。更改的属性名称已在下表中列出。The resources are largely the same between Microsoft Graph and Outlook. However, the two endpoints handle casing of the property names differently. Microsoft Graph uses camelCase for property names, while Outlook uses PascalCase. Translating between the two simply requires converting the case. Property names that are changed are specified in the table below.

例如,Microsoft Graph 消息资源定义 subjectfromreceivedDateTime 等属性。在 Outlook 终结点,这些属性被命名为 SubjectFromReceivedDateTimeFor example, the Microsoft Graph message resource defines properties such as subject, from, and receivedDateTime. On the Outlook endpoint, these properties are named Subject, From, and ReceivedDateTime.

更改的属性名称Changed property names

以下属性名称在 Microsoft Graph 和 Outlook 之间有所不同。The following property names are different between Microsoft Graph and Outlook.

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

跟踪更改(同步)Tracking changes (synchronization)

这两个终结点都支持在集合中查询与同步状态相关的更改。Both endpoints support querying collections for changes relative to a synchronization state. 虽然功能相同,但方法略有不同。While the functionality is the same, the methods are slightly different.

在 Microsoft Graph 终结点上,更改是使用 delta 查询进行查询。On the Microsoft Graph endpoint, changes are queried by using delta queries. 这对集合实现为 delta 函数。This is implemented as a delta function on the collection.

在 Outlook 终结点上,更改是通过将头添加到常规资源集合查询进行查询。On the Outlook endpoint, changes are queried by adding a header to normal resource collection queries.

批处理Batching

这两个终结点都支持将最多 20 个单独请求批处理为一个 HTTP 请求。Both endpoints support batching up to 20 separate requests into one HTTP request.

Microsoft Graph 批处理将多个 API 请求编码成内容类型为 application/json 的 JSON 正文。Microsoft Graph batching encodes multiple API requests into a JSON body with a content type of application/json.

除了 JSON 正文格式以外,Outlook 终结点批处理还支持内容类型为 multipart/mixed 的多部分正文格式。In addition to the JSON body format, Outlook endpoint batching also supports a multi-part body format with a content type of multipart/mixed.

示例:检索邮件Example: retrieving a message

让我们看一个简单的示例。在这种情况下,Web 应用程序请求用户收件箱中的邮件列表。Let's take a look at a simple example. In this scenario, a web app requests a list of messages in the user's inbox.

Microsoft GraphMicrosoft Graph

首先,该应用会让用户登录来授权应用程序。由于应用程序使用 Microsoft Graph 作用域 Mail.Read,授权 URL 如下所示:First, the app has the user sign in to authorize the application. Because the app uses the Microsoft Graph scope Mail.Read, the authorization URL looks like the following:

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

一旦应用程序有了访问令牌,它将发送以下请求:Once the app has an access token, it sends the following request:

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

服务器返回以下响应:The server returns the following response:

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

OutlookOutlook

首先,该应用会让用户登录来授权应用程序。由于应用程序使用 Outlook 作用域 https://outlook.office.com/Mail.Read,授权 URL 如下所示:First, the app has the user sign in to authorize the application. Because the app uses the Outlook scope https://outlook.office.com/Mail.Read, the authorization URL looks like the following:

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>

一旦应用程序有了访问令牌,它将发送以下请求:Once the app has an access token, it sends the following request:

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>

服务器返回以下响应:The server returns the following response:

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