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。