Microsoft SharePoint Trigger 触发器节点
当 Microsoft SharePoint 中的文件或列表项发生变化时,使用 Microsoft SharePoint Trigger 节点启动工作流。
该节点监视一个站点中的一个文档库或一个列表,并按照您设置的计划检查变化。每次检查最多启动一次工作流。如果自上次检查后有多个数据项发生变化,它们会一起进入本次执行,检查读取的每个条目对应一个数据项。如果没有任何变化,节点不会启动执行。
本页介绍节点监视的内容、生成的事件,以及使用该节点构建工作流前应了解的常见问题。
提示
Credentials 凭据
该节点支持 Microsoft OAuth2 凭据和 Microsoft Entra Service Principal 凭据,但不支持 Microsoft SharePoint 凭据。
对于 OAuth2 凭据,请在 Scope 字段中输入 openid offline_access Sites.Read.All。对于 Service Principal 凭据,请向 app registration 授予 Sites.Read.All application 权限。如果您的 organization 按站点授予访问权限,请改用 Sites.Selected,并由管理员授予 app 对每个站点的访问权限。
即使没有用户登录,触发器也会继续检查,因此请在生产环境中使用 Service Principal 凭据。用户 session 被撤销后,对应的用户凭据将停止工作。
提示
Government cloud support 政府云支持
如果使用政府云 tenant(US Government、US Government DOD 或 China),请在 Microsoft 凭据配置中选择相应的 Microsoft Graph API Base URL。
节点监视的内容
选择 Site 站点,然后将 Resource 资源设为要在该站点上监视的内容:
- Document Library 文档库:监视一个文档库中的文件。在 Document Library 文档库中选择要监视的库。
- List 列表:监视一个列表中的数据项。在 List 列表中选择要监视的列表。
每个字段都支持选择器和手动输入值。除非选择器无法访问所需内容(例如您的 organization 按站点授予访问权限),否则请使用选择器。Site 站点字段在 By URL 按 URL 模式下也接受站点地址。
该节点监视整个文档库或整个列表,无法将范围缩小到单个文件夹。Microsoft Graph 的 change feed 无法在服务器端过滤,也不会报告已更改文件的文件夹路径,因此没有可靠的过滤依据。
事件
在 Events 事件中选择事件。默认情况下两者都处于启用状态。
- Changed 已更改:添加、编辑、重命名或移动了文件或数据项,或者其 metadata 发生了变化。
- Deleted 已删除:删除了文件或数据项。
对于这两种资源,文件夹都不会生成事件。
为什么没有单独的 Created 事件
Microsoft Graph 的 change feed 报告每个数据项的最新状态,而不是每一次变化。新建的数据项和编辑过的数据项到达时看起来相同,因此节点会将两者都报告为 Changed 已更改,而不会进行猜测。
如果需要区分新数据项和已编辑的数据项,请在工作流中比较 createdDateTime 与 lastModifiedDateTime,并将结果视为提示而非确定事实。在两次检查之间创建后又被编辑的数据项只会到达一次,且两个时间戳不同。
节点检查频率
Poll Times 轮询时间设置节点检查变化的频率。默认为每分钟一次。
预设选项最低为每分钟一次。Custom 自定义 cron 表达式可以将频率细化到秒,但在这种频率发挥作用之前,Microsoft 就会对请求进行限流。
变化会在下一次检查时被检测到。使用默认设置时,一次检查会读取约 40 页变化;如果时间耗尽,则会提前停止。如果还有更多变化等待处理,节点会保存当前位置,并在下次检查时继续。因此,大量突发变化会分多次执行到达,清理它们所需的时间可能超过一个检查间隔。
输出
节点会按照 Microsoft Graph 返回的原始格式输出每个已变化的条目,不会重塑数据。输出字段取决于监视的资源以及数据项发生的变化。
带有 deleted 属性的条目表示删除;不带该属性的条目表示变化。
监视列表时,条目会包含数据项的身份信息。节点读取 Microsoft Graph 的默认 payload,不会展开数据项的 fields,因此不要依赖条目携带列值。如需读取某一列,请在触发器后添加 Microsoft SharePoint 节点,并通过 id 获取数据项。
删除条目携带的信息远少于变化条目,因为 Microsoft Graph 会移除其中的大多数字段。您可以预期其中包含数据项的 id 和 deleted 属性,但不要依赖其他内容一定存在。如果工作流需要已删除数据项的名称,请自行保存已见数据项的记录,并以 id 为 key。
监视文档库时,不要依赖条目携带 parentReference.path。请使用 webUrl 查找文件所在位置。
常见问题
现有文件和数据项不会触发工作流
发布工作流时,节点会从该时刻开始监视。已经存在的文件和数据项不会触发事件。如需处理文档库中的现有内容,请改用 Microsoft SharePoint 节点。
编辑节点后缺少变化
更改 Authentication 身份验证方式、Site 站点、Resource 资源、Document Library 文档库或 List 列表会重置已保存的位置。节点会从该时刻开始监视,不会报告更早的变化。改为选择同一类型的其他凭据则会保留位置。
工作流停用后缺少变化
如果节点长时间未运行,其保存的位置可能会在 Microsoft 端过期。此后节点会从当前时刻重新开始监视,并记录警告。位置过期期间发生的变化不会被报告。
同一数据项多次到达
在一次检查中,节点会合并同一数据项的重复变化。处理大量突发变化时,同一数据项可能会跨多次检查重复到达。请将工作流设计为即使同一数据项重复出现也不会产生不良影响。
测试显示数据项,但未显示我的变化
在编辑器中测试节点不会移动保存的位置,因此测试不会消耗真实事件。测试最多列出文档库或列表中一页已经存在的数据项。它不会等待变化,也绝不会显示删除。请使用测试查看条目的数据形状,而不是检查事件选择。
节点报告找不到文档库或列表
如果无法再访问被监视的文档库或列表(例如有人将其删除),节点会报告错误,指出文档库或列表的名称以及执行查找的站点。节点会保留保存的位置,因此目标恢复后可以继续运行。由于节点按 ID 监视,重命名不会中断节点。但如果您在 By ID or Title 按 ID 或标题模式下输入的是列表标题,重命名会导致节点中断。
权限错误未指出文档库或列表名称
如果凭据失去访问权限,Microsoft Graph 通常会返回权限错误。节点会原样报告该错误,因此其中不会指出文档库或列表名称。请检查凭据的 scopes,以及已登录账户对该站点的访问权限。
同一错误不会在每次检查时都出现
检查失败时,节点会报告失败。如果同一故障持续重复,节点最多每小时再次报告一次,并在此期间将警告写入日志,从而避免持续性问题填满执行列表。不同的故障会立即报告,检查成功则会清除记录。在编辑器中进行测试时,节点始终会报告故障。
相关资源
n8n 为 Microsoft SharePoint 提供了 app 节点。有关更多信息,请参阅 Microsoft SharePoint 节点文档。
有关该节点读取的 change feeds 的详细信息,请参阅 Microsoft 的 driveItem delta 文档和 listItem delta 文档。