Microsoft Graph还是传统REST接口：2026年决策指南

这个问题有点不对

任何将应用连接到 Microsoft 365、Entra ID、Teams 或 Outlook 数据的人，最终都会面临“REST API 还是 Microsoft Graph？”这样的选择。这听起来像是两者之间的公平抉择，但实际上并非如此。Microsoft Graph 本身就属于 REST API。人们通常想问的是：

是应该继续使用那些较旧的、针对特定服务的 REST 接口（如 Azure AD Graph、Outlook REST API、SharePoint REST、EWS 等），还是转向统一的 Microsoft Graph API？

2026年，这个问题将面临实际的截止期限。微软已花费大约三年的时间来关闭那些零散的API，并引导大家使用Graph API，其中一些API的关闭时间仅在几周之后。下面您将看到分类整理后的名称、仍在使用的API状态说明、并列对比信息，以及可用于新版本开发与旧集成系统的决策流程。

名称分类

REST是一种架构风格，而非可安装的产品。那些使用GET、POST、PATCH和DELETE等HTTP动词，通过URL将事物视为资源，并通常以JSON格式进行数据交换的API，都可以称得上是RESTful API。按照这个定义，Microsoft Graph、Azure AD Graph、已废弃的Outlook REST API以及SharePoint REST API都符合这一标准。

Microsoft Graph 是一个统一的 REST API，涵盖了 Microsoft 365 和 Entra ID 的所有功能。无需在用于邮件、文件和目录数据的不同端点之间切换，所有功能都集中在 https://graph.microsoft.com/ 下：用户、群组、邮件、日历、Teams 聊天、文件、安全警报，以及最近的 AI 智能体功能。

因此，有意义的对比是将统一的 Graph 与那些旧式的、针对特定服务的 REST 接口进行对比。这些旧 API 当前的状态非常重要，因为过去一年里情况变化很快。

2026 年仍可使用的功能

如果你使用的任何服务仍指向 graph.windows.net，那就已经来不及了；从2026年7月中旬开始，这个接口将在几周内关闭。旧的Outlook REST API早已停用超过两年，而通过第三方EWS访问Exchange Online的功能也将在今年秋季被切断。曾经用来支持继续使用原生REST端点的各种理由，如今要么已经失效，要么即将失效。

微软此前曾多次调整这些截止日期，因此在规划迁移时间前，请先在Microsoft Learn上确认最新的截止时间。不过，多年的发展方向始终未变：所有功能都将整合到Graph上。

Graph与旧端点的区别

在日常工作中，有三点差异最为重要。

身份验证

十多年来，各种认证方式不断涌现：基本认证、NTLM、Kerberos，以及SharePoint插件所依赖的Azure访问控制服务。对于Microsoft 365环境中的应用而言，所有这些认证方式都已不再使用。Graph仅接受通过Microsoft Entra ID实现的OAuth 2.0认证。这样一来，获取令牌的方式只有一种，权限模型也统一，同时可以集中查看谁能够访问哪些内容。这不仅为开发者提供了更完善的API，也为管理员带来了更高的安全性。

查询与批量处理

如下所示的Graph请求只需一次往返即可对邮件进行过滤、筛选并分页处理：

GET https://graph.microsoft.com/v1.0/me/messages
    ?$select=subject,receivedDateTime,from
    &$filter=receivedDateTime ge 2026-07-01T00:00:00Z
    &$top=25
    &$orderby=receivedDateTime desc

对于那些较旧、灵活性较低的端点，往往需要通过多次精细的调用或在客户端进行过滤才能得到相同的结果。加入 $batch 后，就可以将多达20个独立的操作整合到一个HTTP请求中，实现针对完全不同资源类型的读写操作混合处理。

限流

Graph会同时应用多种限制：所有租户下的每个应用、每个租户下的所有应用，以及同一租户内的每个应用。具体数值因服务而异，邮件、文件、目录服务以及Teams消息服务各自都有不同的上限。一旦达到其中任何一种限制，系统就会返回429 Too Many Requests错误，并附带Retry-After头信息，指示需要等待的时间。与旧版API相比，后者往往没有对流量限制进行文档说明，用户往往要在实际使用中才发现这些限制，因此Graph在这方面有了显著改进。那条老生常谈的建议依然适用：使用$select仅获取所需字段，优先采用批量查询和增量查询而非轮询方式，始终遵守Retry-After指示再重新尝试，而非立即重复请求。

哪些场景仍适合使用非Graph的方案

Graph 目前还无法覆盖所有功能，有些场景确实需要使用不同的 API。

• 详细的 SharePoint 站点管理。 完整的权限级别细节、部分站点组操作以及内容类型和列表架构管理的部分功能仅存在于 SharePoint REST 的 _api/web/... 下。成熟的 SharePoint 项目通常通过 Graph 处理日常的文件、列表和驱动器相关操作，仅对不足之处使用 SharePoint REST。
• SPFx Web 部件。 SharePoint Framework 运行时已提供现成的 SharePoint REST 上下文，因此对于页面内的自定义需求而言，这通常是最简便的方式，尽管同样的 Web 部件也可以调用 Graph。

本地 Exchange Server。2026 年 10 月的限制仅适用于 Exchange Online，因此 EWS 仍可在本地 Exchange 环境中正常使用。对于完全基于本地的邮件系统，真正的选择是继续使用 EWS，或是先迁移到 Exchange Online。

大规模一次性管理任务。批量权限清理、大规模租户报表生成以及站点配置等工作通常会使用 PnP PowerShell 等高级工具来完成，而这些工具内部又会调用 Graph 和 SharePoint REST 接口。

除了这些特定情况外，今年几乎没有技术上的理由再从那些旧的服务端点开始新的项目，因为大多数这类端点已经停止使用或即将被淘汰。

如何决策

可通过以下问题来决定是否采用新的集成方案：

1. 这是新版本吗？请使用 Microsoft Graph。新功能会首先在此推出，而且这是微软仍在持续投入开发的平台。
2. 现有的应用程序是否调用了 Azure AD Graph、Outlook REST API 或基于 ACS 的 SharePoint 插件？Outlook REST 和 ACS 的支持期限已经结束，而 Azure AD Graph 也将于 2026 年 7 月 31 日停止服务。请将此项视为紧急任务处理。
3. 第三方应用程序是否使用 EWS 与 Exchange Online 进行交互？微软将于 2026 年 10 月 1 日开始阻止此类调用。请立即开始过渡到 Graph 的邮件和日历接口。
4. 您是否需要 SharePoint 中尚不具备的某些功能？对于这类功能，可使用 SharePoint REST 进行调用，其余功能则使用 Graph。请先查阅 SharePoint-in-Graph 的文档，因为功能缺失的清单正在不断缩短。

该环境仅限于本地部署吗？ EWS及其他本地协议在本地环境中仍然有效。Graph以云端优先为设计理念，无法直接连接到本地Exchange或SharePoint服务器。

对几乎所有人而言，规则很简单：除非有明确的、有文档支持的理由，否则应使用Microsoft Graph。

过去与现在的相同请求

以下是已废弃的Outlook REST v2.0调用方式，仅用于对比：

GET https://outlook.office.com/api/v2.0/me/messages
Authorization: Bearer {token}

自2024年3月以来，该端点一直返回HTTP 410 Gone状态。相同请求的Graph版本如下所示：

GET https://graph.microsoft.com/v1.0/me/messages?$select=subject,from,receivedDateTime&$top=10
Authorization: Bearer {token}

目前仍受支持的 SharePoint REST 以如下方式读取列表项：

GET https://{tenant}.sharepoint.com/sites/{site}/_api/web/lists/getbytitle('Documents')/items
Authorization: Bearer {token}
Accept: application/json;odata=verbose

当 Graph 支持相同操作时，调用方式变为：

GET https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/items
Authorization: Bearer {token}

两个时代中的HTTP机制是完全相同的。Graph所增加的只是一个基础URL、一种认证模型以及一种JSON格式规范，无论你实际使用的是哪种Microsoft 365服务。

从旧版API迁移

如果你刚发现自己的租户中仍有部分功能依赖于即将被废弃的API，可按照以下步骤操作：

1. 查明究竟是哪些组件在调用该API。Entra提供了两项建议：“迁移应用程序”和“迁移服务主体”，它们会列出你在过去30天内租户中实际使用的Azure AD Graph功能。这比通过源代码猜测要准确得多。
2. 明确映射权限。旧版API的权限无法直接一一对应到Graph的权限范围。应参考微软官方的权限映射文档，而非假设名称相似的两个权限范围具有同等效力。
3. 将身份验证移至 MSAL。仍在使用旧版 Azure AD Authentication Library（ADAL）的功能都需要单独进行迁移，因为 ADAL 已经多年不再获得支持。
4. 更换 SDK，而不仅仅是 URL。针对 .NET、JavaScript 和 TypeScript、Python、Java、Go 以及 PowerShell 的官方 Graph SDK 可以自动处理批量请求、重试和分页功能。除非确实必要，否则不要手动编写原始 HTTP 请求。
5. 谨慎使用测试版功能。如果某个功能仅存在于 beta 版 Graph 端点上，其接口规范随时可能发生变化。要么做好相应准备，要么等待该功能正式发布。
6. 在测试环境中检测 429 错误。通过模拟真实的请求量进行压力测试，以便在用户遇到问题之前就发现流量限制的问题。
7. 在日历中标注真实的截止日期，并在依赖该日期之前务必对照微软的官方文档进行核实。这些日期此前曾有过变动，因此无论从何处获得的日期，包括此页面上的内容，都应视为临时性的。

Graph也是管理AI智能体的平台

差距持续扩大的原因还有另一个：Graph正在成为微软AI智能体生态系统的控制平面。2026年，微软为管理Microsoft 365 Copilot智能体及应用、维护智能体清单以及获取更详细的Copilot使用报告，新增了Graph端点，同时还支持与Agent 365等新许可证相关的功能。而这些功能在Azure AD Graph、Outlook REST或EWS上均不存在，也永远不会出现。如果您的组织计划基于Copilot的可扩展性或自定义智能体进行开发，那唯一可行的路径就是Graph。

您现在该怎么做

对于标题中的问题，2026年时已有相当明确的答案：

• 要在 Microsoft 365 或 Entra ID 上启动新项目？请使用 Microsoft Graph。再也没有理由要在基于旧服务的专用 REST API 上开展新项目了。
• 正在维护旧有的集成方案？请将其与上方的状态表进行对比。如果该集成涉及 Azure AD Graph、Outlook REST、基于 ACS 的 SharePoint 加载项或第三方 EWS 访问，那么您就面临着截止日期的压力，而且有些截止日期已经非常接近。
• 在 Microsoft Graph 中缺少某项 SharePoint 功能？对于该特定功能，可使用 SharePoint REST，而其他功能则继续使用 Microsoft Graph。

早在2018年，当微软确实同时运行多个相互竞争的REST接口时，“REST API还是Graph”还是一個值得讨论的话题。如今则主要是进行整合工作。整合几乎已经完成，其他替代方案的时间也越来越少了。