EWS 迁移到 Microsoft Graph 指南

弃用时间线

Microsoft 将于 2026 年 10 月 1 日永久封锁 Exchange Online 的 Exchange Web Services (EWS)，并于 2027 年 4 月 1 日完全移除。此弃用影响全球超过 4 亿个 Microsoft 365 商业席位。Microsoft 于 2023 年 9 月首次宣布停用计划，此后已三次收紧时间表。

根据 Microsoft 官方弃用页面，关键日期如下：

如果不采取任何行动，你的 EWS 代码将从 2026 年 10 月起开始返回错误。TechCommunity 公告 确认 Microsoft 将对未选择加入的租户设置 EWSEnabled=False。

本地部署 Exchange：不受影响

EWS 弃用仅适用于 Exchange Online (Microsoft 365)。本地运行的 Exchange Server 2016 和 2019 保留完整的 EWS 支持，且未宣布终止日期。运行混合 Exchange 的组织——Microsoft 估计约占企业 Exchange 部署的 40%——面临分裂：云端邮箱必须迁移到 Graph API，而本地邮箱继续使用 EWS。

这种双协议现实意味着混合环境需要两套身份验证流程和两个 API 接口，或者一个根据邮箱位置将请求路由到正确协议的抽象层。

身份验证模型：从 NTLM/Basic 到 OAuth 2.0

从 EWS 迁移到 Microsoft Graph 需要将 NTLM、Kerberos 或 Basic Auth 替换为通过 Azure AD（现 Entra ID）应用注册的 OAuth 2.0。Microsoft 于 2022 年 10 月弃用了 Exchange Online 的 Basic Auth，Graph API 自发布以来一直要求使用 OAuth 2.0。访问令牌每 60-90 分钟过期，刷新令牌持续 90 天后需要重新认证。

• 注册 Azure AD 应用，配置 Mail.Read、Mail.Send、Calendars.ReadWrite 或其他权限范围
• 选择认证流程：授权码模式（委托）用于用户上下文，客户端凭据模式（应用）用于守护进程/服务应用
• 管理令牌生命周期：访问令牌 60-90 分钟过期，刷新令牌 90 天过期
• 管理员同意：应用级权限需要租户管理员批准

下面的代码展示了 EWS Basic Auth 和 Graph OAuth 2.0 身份验证之间的差异。EWS 只需 3 行代码即可连接，而 Graph 需要先完成 Azure AD 应用注册并配置正确的权限范围，才能进行任何 API 调用。

# EWS (old) - Basic Auth or NTLM
$cred = Get-Credential
$service = New-Object Microsoft.Exchange.WebServices.Data.ExchangeService
$service.Credentials = $cred
$service.Url = "https://outlook.office365.com/EWS/Exchange.asmx"

# Graph API (new) - OAuth 2.0 with MSAL
Connect-MgGraph -Scopes "Mail.Read","Mail.Send"
$messages = Get-MgUserMessage -UserId "me" -Top 10

功能对等差距（截至 2026 年 4 月）

Microsoft Graph API 涵盖了核心邮件、日历和联系人操作，但在至少 4 个方面仍然缺乏与 EWS 的完全对等：归档邮箱访问、公共文件夹 CRUD、邮箱导入/导出和定期事件增量查询。Microsoft 自 2024 年以来按季度发布节奏缩小差距，但尚未承诺完全功能对等的日期。

下表将每个 EWS 功能映射到其 Graph API 状态。数据来自 Microsoft TechCommunity 更新，涵盖了 10 个最常被引用的 EWS 功能：

Microsoft 发布了 Exchange Admin API 作为某些差距的临时过渡方案。但完全消除所有功能差距的确切日期尚未确定。

三种迁移路径

从 EWS 迁移的组织有三个选择：直接迁移到 Microsoft Graph API、注册临时 AppID AllowList 延期，或采用跨提供商的抽象层。正确的选择取决于时间线、混合 Exchange 需求以及你的应用支持多少提供商。根据 Microsoft 自己的规划指南，大多数团队直接迁移到 Graph 需要 2-6 个月。

路径 1：迁移到 Microsoft Graph API

官方路径是将每个 EWS 调用替换为对应的 Graph 等价物。Microsoft 提供了一个 EWS 代码分析器，可以扫描你的代码库并将 EWS 操作映射到 Graph API 等价物。分析器会输出一份 CSV 报告，列出每个 EWS 方法、其调用次数和对应的 Graph 端点。

# EWS: Find emails by subject
$view = New-Object Microsoft.Exchange.WebServices.Data.ItemView(50)
$filter = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+ContainsSubstring(
  [Microsoft.Exchange.WebServices.Data.ItemSchema]::Subject, "invoice")
$results = $service.FindItems(
  [Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Inbox, $filter, $view)

# Graph: Same operation
$messages = Get-MgUserMessage -UserId "me" -Filter "contains(subject, 'invoice')" -Top 50

优点： 留在 Microsoft 生态系统内，可使用最新功能。 缺点： 需要 Azure AD 应用注册、OAuth 令牌管理，不支持非 Microsoft 提供商，存在功能对等差距。

路径 2：临时 AppID AllowList

AllowList 将 EWS 访问延长 6 个月，从 2026 年 10 月到 2027 年 4 月 1 日。租户管理员必须在 2026 年 8 月之前注册应用的客户端 ID，否则豁免不会生效。Microsoft 文档警告这是一次性延期，2027 年 4 月之后无法续期。

# Check current EWS settings
Get-OrganizationConfig | Select-Object EwsEnabled, EwsAllowList

# Add your app to the AllowList
Set-OrganizationConfig -EwsAllowList @{Add="your-app-client-id"}
Set-OrganizationConfig -EwsEnabled $true

优点： 无需立即修改代码。 缺点： 只是将问题推迟了 6 个月。EWS 将于 2027 年 4 月 1 日永久移除。

路径 3：使用统一抽象层

跨提供商的抽象层在内部处理 EWS 和 Graph 路由，因此当 Microsoft 停用某个协议时你的代码无需更改。Nylas CLI 通过一个接口连接 Exchange Online、本地 Exchange、Gmail、Outlook、Yahoo、iCloud 和 IMAP。相同的命令在所有 6 个提供商上运行，无需编写针对特定协议的逻辑。

# Install
brew install nylas/nylas-cli/nylas

# Authenticate (handles OAuth, EWS, Graph internally)
nylas auth config

# Read email -- works regardless of whether the mailbox is
# Exchange Online (Graph), Exchange on-prem (EWS), or Gmail
nylas email list --limit 10

# Search
nylas email search "invoice" --limit 50

# Send
nylas email send \
  --to "colleague@company.com" \
  --subject "Report" \
  --body "The report is ready: <report-download-link>"

优点： 无需编写协议特定代码，无需 Azure AD 应用注册，支持所有提供商，本地和云端通过一个接口访问。 缺点： 引入外部依赖。需要 Nylas API 密钥。

并排对比

三种方案在身份验证复杂度、提供商覆盖范围和迁移工作量上各有不同。EWS 支持 3 种身份验证方法（NTLM、Kerberos、Basic），Graph API 仅支持 OAuth 2.0，而 Nylas CLI 通过一条配置命令处理身份验证。下表从影响迁移规划的 7 个运维关注点进行对比。

混合 Exchange：双代码库问题

混合 Exchange 环境在 2026 年 10 月之后必须维护两套独立的代码路径：Microsoft Graph 用于云端邮箱，EWS 用于本地部署的 Exchange Server。Microsoft Graph 不支持本地 Exchange Server，这意味着拥有分布式部署的组织无法统一到单一的 Microsoft API。根据 Microsoft 的混合部署文档，混合配置在企业 Exchange 部署中占有相当大的比例。

这种双协议分裂迫使同一应用中必须包含两套身份验证流程（Azure AD OAuth 用于 Graph，NTLM 或 Kerberos 用于本地 EWS）、两个 API 接口和两套错误处理逻辑。Nylas 平台在内部处理此路由——它检测邮箱是云端还是本地，并使用适当的协议，无需代码更改。

迁移清单

完整的 EWS 迁移涉及身份验证、API 接口、错误处理以及所有受影响许可证类型的测试。Microsoft 建议在 2026 年 10 月截止日期前至少 3 个月开始迁移，以预留 Azure AD 应用注册、管理员同意和测试周期的时间。以下 6 个步骤涵盖了从审计到生产环境切换的端到端流程。

1. 审计你的 EWS 使用情况——运行 Microsoft 的 EWS 代码分析器 来盘点每个 EWS 调用
2. 检查功能对等差距——将你的 EWS 操作与上面的功能差距表进行对比
3. 在 2026 年 8 月前注册你的应用——如果需要更多时间，将应用添加到 AllowList
4. 先用 F1/F3 许可证测试——这些许可证在 2026 年 3 月已被封锁，已经处于新行为模式
5. 规划混合部署——如果你有本地 Exchange，决定如何处理双协议分裂
6. 关注 Microsoft 更新——功能对等差距每季度都在缩小

常见问题

EWS 弃用引发了关于时间线、本地部署影响、功能差距和迁移替代方案的问题。以下是开发者在规划迁移时最常见的 4 个问题，基于 Microsoft TechCommunity 论坛和官方弃用文档中涉及的主题。

Exchange Online 的 EWS 何时停用？

Microsoft 将从 2026 年 10 月 1 日起封锁来自非 Microsoft 应用的 EWS 请求。在 2026 年 8 月之前配置 AppID AllowList 的租户可获得临时豁免。所有 EWS 访问将于 2027 年 4 月 1 日永久移除。

本地部署的 Exchange Server 是否弃用 EWS？

不会。Exchange Server 2016 和 2019 仍然完全支持 EWS。此弃用仅影响 Exchange Online (Microsoft 365)。

Graph API 缺少哪些 EWS 功能？

截至 2026 年 4 月，Graph API 缺少归档邮箱访问、公共文件夹 CRUD、邮箱导入/导出和完整的定期事件增量支持。Microsoft 正在按季度缩小差距，但尚未承诺完全对等的日期。

我能完全跳过迁移吗？

可以，如果你使用抽象层的话。Nylas 平台通过单一接口连接 Exchange Online、本地 Exchange 和其他 4 个提供商。提供商侧的弃用不需要你修改代码。

下一步

在规划好 EWS 迁移路径后，以下指南涵盖了通过 Nylas CLI 执行的具体 Exchange 操作。每篇指南都包含经过测试的命令、提供商特定的故障排除方法以及 6 个受支持提供商的代码示例。

• EWS 停用清单——盘点有风险的脚本并运行 2 条 Exchange 烟雾测试命令
• 从 CLI 列出 Exchange 邮件——无需 EWS 或 Graph 即可读取和搜索 Exchange 邮箱
• 从 CLI 管理 Exchange 日历——创建、更新和删除事件
• 替代 Send-MgUserMessage——从 Graph PowerShell cmdlet 迁移
• 使用 PowerShell 管理 Office 365 邮件——读取、搜索和整理你的 M365 收件箱
• 从终端发送邮件——跨提供商的邮件发送指南
• 完整命令参考——每个标志和子命令的文档