近日，多位 Azure 用户反馈在通过 Azure Data Factory（ADF）连接 SharePoint 在线数据源时，频繁遭遇“Failed to get metadata of OData service (401 Unauthorized)”错误。该问题导致数据管道无法正常获取元数据，影响企业级数据集成与自动化流程。本文将对这一故障的典型场景、根本原因及对应解决方案进行详细解析。

问题现象

当用户在 Azure Data Factory 中创建基于 SharePoint Online 列表或文档库的链接服务时，在测试连接或预览数据阶段，系统返回如下错误信息：

Failed to get metadata of OData service (401 Unauthorized)

该错误通常出现在使用 OData 协议连接 SharePoint 时，且无论采用服务主体（Service Principal）认证还是 Azure AD 应用注册认证，均有可能触发。受影响的操作包括：数据复制活动、查找活动以及数据流中的 SharePoint 源。

技术背景

Azure Data Factory 通过 SharePoint Online REST API（OData 协议）实现数据访问。正确认证需要满足三个条件：Azure AD 应用注册、对应的 API 权限授予、以及正确的令牌获取流程。401 错误明确表示服务器无法验证客户端身份，即访问令牌无效或缺失。

常见原因分析

根据微软官方文档及社区案例，以下为最常见的几类诱因：

  1. API 权限配置不完整：在 Azure AD 应用注册中，仅授予了“Delegated permissions”（委托权限），而未授予“Application permissions”（应用程序权限）。对于后端服务（如 ADF）的无用户交互场景，必须启用 Application permissions 并添加 Sites.Read.All 或 Sites.ReadWrite.All 等权限。

  2. 未授予管理员同意：即使添加了 Application permissions，仍需租户管理员在“API 权限”页面点击“授予管理员同意”。否则令牌请求会被拒绝，返回 401。

  3. 服务主体未加入 SharePoint 站点：对于使用服务主体（Service Principal）认证的情况，需要将对应的应用程序（服务主体）显式添加到 SharePoint 站点的“网站权限”中，否则服务器会拒绝其访问站点的请求。

  4. OAuth 终结点版本不匹配：某些旧版配置仍使用 v1.0 终结点，而 SharePoint Online 要求使用 v2.0 终结点。ADF 连接配置中的“授权终结点”字段需填写正确的 v2.0 URL（例如：https://login.microsoftonline.com/{tenant-id}/v2.0）。

解决方案步骤

结合上述原因，建议按以下顺序排查：

第一步：验证 Azure AD 应用注册权限

  • 登录 Azure 门户 → Azure Active Directory → 应用注册 → 选择对应的应用。
  • 进入“API 权限” → 点击“添加权限” → 选择“Microsoft Graph”或“SharePoint”（具体取决于所用 API）。
  • 对于 ADF 后台服务，必须选择“应用程序权限”，赋予 Sites.Read.All（或更高权限）。
  • 点击“代表 xxx 授予管理员同意”。

第二步：将服务主体添加到 SharePoint 站点

  • 进入目标 SharePoint 站点 → 设置 → 网站权限 → 授予权限。
  • 输入服务主体的名称（即 Azure AD 应用注册的“应用程序 ID”），授予“读取”或更高权限。

第三步：检查 ADF 链接服务配置

  • 在 Azure Data Factory 中，编辑 SharePoint 链接服务。
  • 确保“身份验证类型”选择“服务主体”。
  • “服务主体 ID”填写应用的客户端 ID。
  • “服务主体密钥”填写对应客户端密码。
  • “租户 ID”填写 Azure AD 租户 ID。
  • “授权终结点”建议显式填写 v2.0 终结点（或留空让 ADF 自动选择）。

第四步：测试连接

  • 保存配置后，点击“测试连接”。若仍失败，可尝试清除 ADF 实例缓存或重启集成运行时。

官方资源与社区讨论

微软已在 Azure Data Factory 文档中更新了 Connect to SharePoint 的故障排查章节，重点强调了应用程序权限与管理员同意的必要性。此外，Stack Overflow 及微软技术社区上类似问题的帖子中，多数用户通过上述步骤成功解决问题。

影响与建议

对于依赖 SharePoint 作为核心数据源的业务部门，此类 401 错误可能导致数据报表延迟、流程中断。建议企业 IT 管理员在配置 ADF 链接服务前，预先完成应用权限预授权，并建立自动化脚本定期验证服务主体对 SharePoint 站点的访问状态。同时，关注微软 Graph API 的版本更新，避免因终结点变更引发兼容性问题。

随着混合办公与数据中台需求增长，Azure Data Factory 与 SharePoint 的集成愈发普遍。提前掌握此类认证错误的排查逻辑，有助于企业快速恢复数据管道，保障业务连续性。