n8n 中文文档

Microsoft SharePoint 节点

使用 Microsoft SharePoint 节点自动处理 Microsoft SharePoint 中的工作,并将 Microsoft SharePoint 与其他应用程序集成。n8n 内置支持广泛的 Microsoft SharePoint 功能,包括下载、上传和更新文件,管理列表中的数据项,以及获取列表和列表数据项。

本页列出了 Microsoft SharePoint 节点支持的操作,提供登录和选择站点的说明、节点版本 2 的变更,以及更多资源的链接。

提示

Feature availability 功能可用性

从 n8n 2.37.0 开始,在工作流中添加 Microsoft SharePoint 节点时会创建使用 Microsoft Graph API 的节点版本 2。使用版本 1 构建的工作流会继续使用版本 1,并通过原有凭据保持不变地运行。请参阅版本 1 到版本 2 的变更。

提示

Credentials 凭据

节点版本 2 提供两种登录方式,可通过 Authentication 身份验证 下拉列表选择:

  • Microsoft OAuth2 (Graph):使用通用 Microsoft OAuth2 凭据以用户身份登录。在凭据的 Scope 字段中输入节点所需的 scopes:读取操作使用 Sites.Read.All,写入操作使用 Sites.ReadWrite.All。请包含 openid offline_access,以便凭据刷新 token。例如,要执行节点的所有操作,请输入:openid offline_access Sites.ReadWrite.All。如果组织按站点授予访问权限,请改用 openid offline_access Sites.Selected,并参阅按站点访问。
  • Microsoft Entra Service Principal (App-Only):使用 Microsoft Entra Service Principal 凭据以应用身份登录,适用于没有用户参与的无人值守工作流。请在管理员同意后,为应用注册授予读取所需的 Sites.Read.All 应用程序权限和写入所需的 Sites.ReadWrite.All。若要将应用限制到特定站点,请改为授予 Sites.Selected,并按站点授予访问权限。

节点版本 1 使用节点专用的 Microsoft SharePoint 凭据。版本 2 不提供此凭据:该凭据的 token 针对较旧的 SharePoint REST API 签发,无法用于 Microsoft Graph。

选择登录方式

两种登录方式都支持所有操作。请根据工作流的运行方式选择:

Microsoft OAuth2 (Graph) Microsoft Entra Service Principal (App-Only)
登录身份 用户 应用注册
适用场景 代表您操作的工作流,或试用节点 没有用户参与的无人值守、共享或生产工作流
可访问范围 在所授予 scopes 内,已登录用户可以访问的内容 租户中的所有站点,除非使用按站点访问
同意方式 登录用户在登录时同意(可能需要管理员允许) 管理员一次性授予管理员同意
失效条件 用户会话被撤销,例如用户离开组织或重置密码 client secret 或证书过期
设置指南 Microsoft OAuth2 凭据 Microsoft Entra Service Principal 凭据

操作

  • File 文件:
    • Download 下载:下载文件。
    • Update 更新:重命名文件、替换其内容,或同时执行这两项操作。
    • Upload 上传:将文件上传到文档库。
  • Item 数据项:
    • Create 创建:在现有列表中创建数据项。
    • Create or Update 创建或更新:创建新数据项;如果当前数据项已存在,则更新它(upsert)。
    • Delete 删除:从列表中删除数据项。
    • Get 获取:从列表中检索数据项。
    • Get Many 获取多个:获取列表中的特定数据项或列出多个数据项。
    • Update 更新:更新现有列表中的数据项。
  • List 列表:
    • Get 获取:检索单个列表的详细信息。
    • Get Many 获取多个:检索多个列表。

选择站点

每项操作都从 Site 站点 开始。可通过以下三种方式设置:

  • From List 从列表中选择:按名称搜索组织的站点。站点搜索需要租户范围的读取权限(Sites.Read.All 或 Sites.ReadWrite.All);按站点访问时无法使用此方式。
  • By URL 按 URL:粘贴完整站点地址,例如 https://contoso.sharepoint.com/sites/mysite。
  • By ID 按 ID:按照 Microsoft Graph 文档支持的任一格式粘贴站点 ID:站点选择器和 Graph 返回的复合 ID(contoso.sharepoint.com,<site-GUID>,<web-GUID>)、单独的站点 GUID、hostname(租户根站点)或 root。若要查找站点的复合 ID,请按地址发出请求:GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/mysite。

按站点访问

有些组织不会授予应用对 SharePoint 的租户范围访问权限,而是使用 Sites.Selected 权限,逐个站点授予应用访问权限。该节点完全支持这种方式:除站点搜索外,所有操作和选择器都可以使用,因为 Microsoft Graph 在没有租户范围读取权限时不支持站点搜索。请改为将 Site 站点 字段设为 By URL 按 URL 或 By ID 按 ID;这两种方式都不需要搜索。

设置按站点访问:

  • 以应用身份登录:在管理员同意后,为应用注册授予 Sites.Selected 应用程序权限,然后为该应用授予每个站点的 read 或 write 访问权限。请参阅按站点授予访问权限,或参阅使用 Azure CLI 配置 SharePoint 应用注册,按照其中包含权限 manifest 的可复制设置步骤操作。
  • 以用户身份登录:将凭据的 Scope 字段设为 openid offline_access Sites.Selected。应用注册同样需要按站点授权,并且已登录账户也必须有权访问该站点。

版本 1 到版本 2 的变更

版本 2 基于 Microsoft Graph API 重新构建。现有工作流会继续使用构建时的版本,因此在添加新节点或切换工作流版本之前不会发生变化。切换后有以下变化:

  • 凭据发生变化。版本 2 使用通用 Microsoft OAuth2 凭据登录;此外,版本 2 新增 Microsoft Entra Service Principal 凭据,用于无人值守、仅应用工作流。版本 2 不提供版本 1 的 Microsoft SharePoint 凭据:其 token 针对旧版 SharePoint REST API,无法用于 Microsoft Graph。版本 1 工作流仍会照常使用该凭据。
  • 数据项更新使用 Microsoft 文档中的路由。版本 1 通过一个可以正常工作、但未在 Microsoft 文档中列出的路由更新数据项。版本 2 将更新发送到有文档说明的 Microsoft Graph 端点,并返回与之前相同的输出,因此工作流不会感知差异。当匹配列识别出多个数据项时,版本 2 也更严格:Update 更新 和 Create or Update 创建或更新 都会停止并显示明确错误,而不是像版本 1 的 Create or Update 创建或更新 那样创建重复数据项。
  • 文件下载会先获取下载链接。版本 2 先向 Microsoft Graph 请求文件 metadata 和一个短期有效、预授权的下载链接,再从该链接获取内容。该链接已获授权,因此 n8n 不会在链接请求中附加您的登录信息。下载文件与版本 1 完全相同,包括文件名。

常见问题

  • 使用按站点权限时,站点搜索失败。Microsoft Graph 无法为只有按站点访问权限的凭据列出站点。请将 Site 站点 字段切换为 By URL 按 URL 或 By ID 按 ID 模式;如果需要搜索,请授予租户范围的读取权限(Sites.Read.All 或 Sites.ReadWrite.All)。
  • 403 错误指出缺少权限。节点的权限错误会列出操作所需的 Microsoft Graph 权限,例如 Sites.ReadWrite.All (or Sites.Selected granted with write access for this site)。请授予该权限;对于应用程序权限,还需授予管理员同意,然后重试。使用按站点访问时,还要检查应用是否已获授权访问当前站点。
  • Service Principal 凭据测试通过,但操作失败。从 n8n 2.40.0 开始,连接测试只检查应用注册能否登录,不检查它拥有的权限。请确认 SharePoint 应用程序权限已获得管理员同意;如果使用按站点访问,还要确认应用已获授权访问该站点。请参阅 Microsoft Entra Service Principal 凭据文档。
  • 连接凭据时显示 AADSTS 错误代码。Microsoft 拒绝了登录或 token 交换,例如 AADSTS7000215(client secret 无效)、AADSTS7000222(client secret 已过期)或 AADSTS700027(证书断言被拒绝)。请参阅 Microsoft Entra Service Principal 凭据文档中的常见问题。
  • 上传超过 250 MB 的文件失败。File: Upload 文件:上传 和 File: Update 文件:更新 会在单次请求中发送内容,上限为 250 MB。目前尚不支持分块上传更大的文件。
  • 筛选大型列表失败。对于包含超过 5,000 个数据项的列表,SharePoint 只能按已建立索引的列筛选。请在 SharePoint 中添加索引(List settings > Indexed columns),或按已建立索引的列筛选。
  • 创建或更新数据项时出现唯一约束错误。列表中的某列强制要求值唯一,而要写入的值已存在于另一个数据项中。请更改该值,或放宽 SharePoint 中该列的 Enforce unique values 设置。

模板和示例

浏览 Microsoft SharePoint 节点文档集成模板 或 搜索所有模板

相关资源

节点版本 2 使用 Microsoft Graph API。有关该服务的更多信息,请参阅 Microsoft 的 SharePoint Graph 文档。版本 1 使用 SharePoint REST API。

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。