比较 Microsoft Graph 和 Outlook REST API 终结点
本文内容
应使用哪个终结点?
功能差异
从 Outlook 终结点迁移到 Microsoft Graph
Outlook REST API 在 Microsoft Graph 和 Outlook API 终结点中均可用, https://outlook.office.com/api
() 。 API 通常提供相同功能,并使用相同的资源类型。
使用 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 或在同一应用中使用这两个终结点时。
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
。
虽然 Microsoft Graph 和 Outlook 终结点同时依赖 Azure AD 颁发的令牌,并且所用的权限 相同,但应用请求获取这些权限的方式因每个终结点而略有不同。
如果应用使用 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 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 作用域 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 作用域 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"
}
}
}
]
}