Databricks Trigger 触发器节点
使用 Databricks Trigger 触发器节点可以响应 Databricks 中的事件,并将 Databricks 与其他应用集成。当 Databricks 作业的一次运行或 Databricks 管道的一次更新开始、成功或失败时,此节点会启动工作流。
提示
Credentials 凭据
有关设置身份验证的指南,请参阅 Databricks 凭据。此节点接受 Databricks(访问令牌)和 Databricks OAuth2 API 凭据。
设置触发器
- 向工作流添加 Databricks Trigger 触发器节点。在节点选择器中搜索
Databricks,然后打开 Databricks 条目。该条目会将作业事件列为触发器;任选一个事件,然后在节点中设置 Resource 资源和 Events 事件。 - 将 Authentication 身份验证设置为 Access Token 访问令牌或 OAuth2,然后选择凭据。对于 OAuth2 凭据,服务主体应将 Grant Type 授权类型设置为 Client Credentials (Service Principal);登录用户应设置为 Authorization Code (User)。请参阅使用服务主体。
- 将 Resource 资源设置为 Job 作业以监视作业运行,或设置为 Pipeline 管道以监视 Databricks 管道更新。
- 在 Job 作业中选择作业,或在 Pipeline 管道中选择管道。两个字段都提供三种模式:
- From List 从列表中选择:从工作区中选择。输入文本可按名称筛选。管道列表还会匹配 ID。Databricks 只会列出凭据身份拥有 CAN VIEW 权限的作业。
- By ID 按 ID:输入 ID。作业 ID 是整数,例如
281874479417551。管道 ID 是 UUID,例如8199cd89-e2f5-4169-a6aa-656a24c8886d。 - By URL 按 URL:粘贴 Databricks 中的页面 URL,例如
https://<your-workspace>/jobs/<job-id>或https://<your-workspace>/pipelines/<pipeline-id>。节点也接受这两类页面的哈希形式,例如https://<your-workspace>/?o=<workspace-id>#job/<job-id>和https://<your-workspace>/?o=<workspace-id>#joblist/pipelines/<pipeline-id>。
- 选择启动工作流的 Events 事件。请参阅事件。
- 保持开启 Simplify 简化以获取输出中描述的内容。关闭它可获取原始 Databricks 对象。
- 在 Poll Times 轮询时间下选择轮询 Mode 模式,设置触发器检查 Databricks 的频率。默认值为 Every Minute 每分钟。请参阅触发器如何轮询。
- 选择 Fetch Test Event 获取测试事件以检查设置。请参阅测试触发器。
- 发布工作流。
事件
触发器会针对每次运行或更新的每个事件启动一次工作流。报告某次运行或更新已完成后,便不会再次报告,例如修复作业运行后也不会重复报告。
作业事件
当 Resource 资源为 Job 作业时可用。默认选择 Run Failed 运行失败和 Run Succeeded 运行成功。
- Run Failed 运行失败:运行以完全成功以外的任何结果结束,包括已取消、已跳过和部分失败的运行(
SUCCESS_WITH_FAILURES)。 - Run Started 运行开始:触发器发现了该作业的新运行。
- Run Succeeded 运行成功:运行中的每个任务都成功结束,终止代码为
SUCCESS。
如果一次运行在两次轮询之间开始并结束,并且你同时选择了 Run Started 运行开始和对应的最终事件,则同一次执行会产生两个数据项。两个数据项都包含完成后的时间信息。
管道事件
当 Resource 资源为 Pipeline 管道时可用。默认选择 Update Completed 更新完成和 Update Failed 更新失败。
- Update Completed 更新完成:更新运行完毕。
- Update Failed 更新失败:更新失败或被 Databricks 取消。停止管道会取消正在运行的更新,因此停止操作会产生此事件。
- Update Started 更新开始:触发器发现了管道的新更新。
提示
Continuous pipelines 连续管道
连续管道会一直运行一次更新,直到你将其停止,因此不会产生 Update Completed 更新完成。管道启动或重新启动时会产生 Update Started 更新开始;更新失败或你停止管道时会产生 Update Failed 更新失败。要获取完成信号,请参阅通过作业监视管道。
输出
开启 Simplify 简化时,两种资源的每个数据项都具有相同的顶级键:event、被监视对象(job 或 pipeline)、运行或更新、result 和 timing。Run Started 运行开始和 Update Started 更新开始不包含 result。节点会移除没有值的键。
作业输出
| 字段 | 值 |
|---|---|
event |
runStarted、runSucceeded 或 runFailed。 |
job.id |
作业 ID。 |
run.id |
运行 ID。可将其传给 Databricks 节点的 Get Run 获取运行记录或 Get Run Output 获取运行输出操作,具体示例请参阅作业运行失败时发送通知。 |
run.name |
运行名称。 |
run.url |
Databricks 中的运行页面 URL。 |
run.trigger |
启动运行的方式,例如 ONE_TIME。 |
run.creator |
创建运行的用户或服务主体。 |
run.parameters |
运行的作业参数,以名称和值对的形式表示。没有值的参数会显示其默认值。 |
result.state |
生命周期状态。已完成的运行是 TERMINATED。 |
result.code |
终止代码,例如 SUCCESS、SUCCESS_WITH_FAILURES、USER_CANCELED 或 RUN_EXECUTION_ERROR。用户取消的运行使用 USER_CANCELED。CANCELED 表示 Databricks 取消了运行,例如运行超过最长持续时间。完整列表请参阅 Databricks API 参考中的 termination_details.code。 |
result.type |
终止类型,例如 SUCCESS 或 CLIENT_ERROR。 |
result.message |
终止消息。Databricks 未提供消息时不包含此字段。 |
timing.startedAt |
UTC 开始时间。 |
timing.endedAt |
UTC 结束时间。运行仍在进行时不包含此字段。 |
timing.durationMs |
运行时长(毫秒)。对于 Run Started 运行开始数据项,表示触发器轮询时该运行已经持续的时间。 |
timing.queuedMs |
运行在队列中等待的时间(毫秒)。 |
Run Failed 运行失败数据项如下所示:
{
"event": "runFailed",
"job": { "id": 281874479417551 },
"run": {
"id": 41847992357943,
"name": "nightly-etl",
"url": "https://adb-example.cloud.databricks.com/?o=1234567890#job/281874479417551/run/41847992357943",
"trigger": "ONE_TIME",
"creator": "[email protected]",
"parameters": { "fail": "true" }
},
"result": {
"state": "TERMINATED",
"code": "RUN_EXECUTION_ERROR",
"type": "CLIENT_ERROR",
"message": "Task main failed with message: Workload failed, see run output for details."
},
"timing": {
"startedAt": "2026-09-01T13:37:18.171Z",
"endedAt": "2026-09-01T13:37:58.640Z",
"durationMs": 40469,
"queuedMs": 14111
}
}
管道输出
| 字段 | 值 |
|---|---|
event |
updateStarted、updateCompleted 或 updateFailed。 |
pipeline.id |
管道 ID。 |
pipeline.name |
管道名称。Databricks 事件未提供名称时不包含此字段。 |
pipeline.url |
Databricks 中的管道页面 URL。 |
update.id |
更新 ID。 |
update.url |
Databricks 中的更新页面 URL。 |
result.state |
COMPLETED、FAILED 或 CANCELED。 |
result.message |
Databricks 事件的消息,例如 Update 01ee1d is COMPLETED.。 |
result.errors |
失败更新的异常。每个条目包含 type、code、sqlState、message 和 stack;其中 stack 会为每个堆栈帧列出 class、method、file 和 line。事件没有异常时不包含此字段。 |
timing.startedAt |
触发器发现的第一个进行中事件的时间。如果你发布工作流时更新已经在运行等情况下,触发器只发现最终事件,则不包含此字段。 |
timing.runningAt |
更新达到 RUNNING 状态的时间。触发器未发现该事件时不包含此字段。 |
timing.endedAt |
最终事件的时间。Update Started 更新开始不包含此字段。 |
timing.durationMs |
endedAt 减去 runningAt 的毫秒数。没有 runningAt 时不包含此字段。 |
Update Completed 更新完成数据项如下所示:
{
"event": "updateCompleted",
"pipeline": {
"id": "8199cd89-e2f5-4169-a6aa-656a24c8886d",
"name": "orders-ingest",
"url": "https://adb-example.cloud.databricks.com/pipelines/8199cd89-e2f5-4169-a6aa-656a24c8886d"
},
"update": {
"id": "01ee1dae-da54-415a-aba8-0c8b0de503f1",
"url": "https://adb-example.cloud.databricks.com/pipelines/8199cd89-e2f5-4169-a6aa-656a24c8886d/updates/01ee1dae-da54-415a-aba8-0c8b0de503f1"
},
"result": {
"state": "COMPLETED",
"message": "Update 01ee1d is COMPLETED."
},
"timing": {
"startedAt": "2026-09-01T14:20:31.066Z",
"runningAt": "2026-09-01T14:20:31.066Z",
"endedAt": "2026-09-01T14:20:35.738Z",
"durationMs": 4672
}
}
原始输出
关闭 Simplify 简化时,每个数据项都是 Databricks 返回的对象,并额外包含 event 键。对于作业,这是 Jobs API 所列出的运行记录;对于管道,这是 Pipelines API 所列出的 update_progress 事件。请参阅 Databricks API 参考中的 list runs 和 list pipeline events。
触发器如何轮询
节点会按照 Poll Times 轮询时间中的计划检查 Databricks。事件在发生后最多经过一个轮询间隔才会到达工作流。如果这太慢,请参阅在数秒内通过 Webhook 获取事件。
- 首次发布工作流时,触发器从该时刻开始监视。对于作业,它不会报告更早开始的运行;对于管道,如果更新在发布时已经运行,它仍会报告该更新的结束,但不包含
timing.startedAt、timing.runningAt或timing.durationMs。 - 取消发布后再次发布时,触发器会从停止位置继续,并报告工作流未发布期间发生的事件。更改作业或管道,或切换 Resource 资源时,触发器会从该时刻重新开始。
- 即使 Databricks 延迟列出某次运行或更新,触发器仍会报告它,并且只报告一次。无论长时间运行耗时多久,触发器都会在运行结束时报告。
- 如果一个作业在两次轮询之间启动超过 1,000 次运行,触发器会报告最近的 1,000 次,并向 n8n 日志写入警告。
- 每次轮询都会向 Databricks 发出至少一个请求,因此每个触发器节点使用 Every Minute 每分钟时,每天至少发出 1,440 个请求。未发现任何内容的轮询不会创建执行。对于每天只运行几次的作业,将 Every X 每 X 分钟设置为 10 或 15 分钟即可。管道轮询会读取时间窗口中的每个事件,而不仅是更新事件,因此繁忙管道每次轮询的开销高于作业。
测试触发器
选择 Fetch Test Event 获取测试事件可手动运行触发器一次。对于作业,节点读取最近 25 次运行,每次运行产生一个数据项:运行时是 Run Started 运行开始,结束后则是最终事件。对于管道,节点读取最近 100 个事件,并返回其中的更新事件。一次更新可能同时产生开始和结束事件。节点按从旧到新的顺序列出数据项,并仅保留 Events 事件中选择的事件。如果没有匹配的运行或更新,例如只选择 Run Started 运行开始但没有运行正在进行,则测试不会返回内容。测试不会改变已发布工作流之后报告的内容。
使用服务主体
只要工作流保持发布,触发器就会无人值守地运行,因此请使用属于服务主体的凭据。也就是将 Grant Type 授权类型设置为 Client Credentials (Service Principal) 的 OAuth2 凭据。绑定到个人的凭据会在该人员离职或撤销同意后停止工作。设置步骤请参阅使用 OAuth2(服务主体)。请跟踪密钥到期日期;密钥过期时触发器会停止工作。
授予 CAN VIEW 权限
凭据所认证的身份需要对每个被监视的作业或管道拥有 CAN VIEW 权限。这是两者的最低权限级别。要为作业授予此权限,请在 Databricks 中打开作业,在 Job details 作业详情面板中选择 Edit permissions 编辑权限。选择用户或服务主体,将权限设置为 Can View,然后选择 Add 添加和 Save 保存。对于管道,请在其权限设置中授予该权限。请参阅 Databricks 的作业权限和管道访问控制列表文档。所需 Databricks 权限表列出了凭据需要的其他权限。
在数秒内通过 Webhook 获取事件
触发器使用轮询,因此事件最多经过一个轮询间隔才会到达工作流。如果需要在数秒内收到作业事件,可以让 Databricks 将其推送到 Webhook 节点。Databricks 作业通知可以在运行开始、成功或失败时调用 Webhook。管道不能发送 Webhook;请参阅通过作业监视管道。
开始之前:
- Databricks 工作区管理员必须创建通知目标。Databricks 不会对载荷签名,因此 Webhook 节点上的 Basic Auth 用户名和密码是唯一的验证方式。
- 载荷只包含 ID,因此工作流需要使用 Databricks 节点读取运行记录。
- Databricks 没有说明重试机制,因此请保留 Databricks Trigger 触发器节点,作为遗漏事件的后备方案。
- Databricks 不保证调用顺序。同一次运行的
jobs.on_success调用可能先于jobs.on_start调用到达;添加目标后的第一次运行也可能跳过jobs.on_start。请根据$json.body.event_type分支,而不要依赖调用的到达顺序。 - Databricks 必须能够通过 HTTPS 访问 n8n 实例。对于位于防火墙后的自托管实例,请允许通知目标页面中 Networking requirements 下列出的 Databricks 出站 IP 范围。
设置步骤如下:
- 在 n8n 中添加 Webhook 节点。将 HTTP Method HTTP 方法设置为 POST,将 Authentication 身份验证设置为 Basic Auth,并创建包含 User 用户名和 Password 密码的 Basic Auth 凭据。将 Respond 响应保留为 Immediately 立即。复制 Production URL 生产 URL。
- 在 Webhook 节点后添加 Databricks 节点。将 Resource 资源设置为 Job 作业,将 Operation 操作设置为 Get Run 获取运行记录。将 Run 运行记录设置为 By ID 按 ID,并输入表达式
{{ $json.body.run.run_id }}。节点会返回完整的运行记录,其中包含run_state、run_result和run_error_message。请参阅 Get Run 获取运行记录。 - 发布工作流。
- 在 Databricks 中,由工作区管理员创建目标。选择顶部栏中的用户名,然后选择 Settings 设置。在 Workspace admin 工作区管理员部分中,打开 Notifications 通知标签页并选择 Manage 管理。选择 Add destination 添加目标,选择 Webhook,输入生产 URL,以及第 1 步中的 User 用户名和 Password 密码。选择 Create 创建。请参阅管理通知目标。
- 在作业中,打开 Job details 作业详情面板,然后在 Job notifications 作业通知下选择 Edit notifications 编辑通知。选择 Add notification 添加通知,在 Destination 目标中选择目标,然后勾选 Start 开始、Success 成功或 Failure 失败。选择 Save 保存。请参阅为作业添加通知。
随后,Databricks 会为每个事件发送一个 POST 请求。请求体会出现在 $json.body 中:
{
"event_type": "jobs.on_failure",
"workspace_id": 1234567890,
"run": { "run_id": 41847992357943 },
"job": { "job_id": 281874479417551, "name": "nightly-etl" }
}
event_type 可以是 jobs.on_start、jobs.on_success、jobs.on_failure 或 jobs.on_duration_warning_threshold_exceeded。只在 Databricks 中勾选所需事件,也可以使用 If 节点根据 $json.body.event_type 进行分支。一个作业的每种事件类型最多可以通知三个目标。
通过作业监视管道
Pipeline 管道资源会监视 Databricks 管道的每次更新,无论更新由什么方式启动。在以下三种情况下,请改为监视作业。
管道作为作业中的任务运行
如果关注整个作业,例如管道任务之后还有其他任务,请监视作业。作业只会看到它启动的更新。如果需要失败更新中的异常和堆栈信息(位于 result.errors),请监视管道。
管道为连续模式
连续管道不会产生 Update Completed 更新完成。要获取完成信号,请通过包含管道任务的触发式作业运行它。作业会将管道作为一次可完成的更新运行,因此作业上的 Run Succeeded 运行成功和管道上的 Update Completed 更新完成都会发生。此时管道会在作业运行时处理数据,而不是持续处理。
需要在数秒内收到事件
作业可以发送 Webhook,但管道不能。包含管道任务的作业可以为管道提供在数秒内通过 Webhook 获取事件中所述的 Webhook 路径。
更多信息请参阅 Pipeline task for jobs 和 Triggered vs. continuous pipeline mode。
常见问题
触发器未启动工作流
- 首次发布工作流时,触发器从该时刻开始,不会重放较早的运行。请启动新的运行或更新进行测试。
- 打开 Executions 执行列表。失败的轮询会显示在其中,并附带 Databricks 错误。
- 对于作业,缺少 CAN VIEW 权限不会产生错误。触发器会继续轮询而不报错,但永远不会触发。请参阅权限错误。
- 检查 Events 事件选择。默认未选择 Run Started 运行开始和 Update Started 更新开始。
- 连续管道不会产生 Update Completed 更新完成。请参阅通过作业监视管道。
- 仍在运行的作业只会产生 Run Started 运行开始。Databricks 报告运行结束后,最终事件才会出现。
- 凭据已过期。服务主体密钥的有效期最长为 730 天,用户登录连接则会在刷新令牌过期时结束。请参阅 OAuth 密钥会过期和配置令牌生命周期。
列表中没有作业或管道
Databricks 只列出凭据身份拥有 CAN VIEW 权限的作业。搜索最多扫描工作区中的前 1,000 个作业或管道。请改用 By ID 按 ID或 By URL 按 URL,或者先授予 CAN VIEW 权限。
权限错误
凭据身份缺少 CAN VIEW 权限时,Databricks 会以 PERMISSION_DENIED 拒绝请求。n8n 会显示 Databricks 消息作为错误,并添加以下提示之一作为说明:
Grant Can View on the job to the user or service principal of the credential, then retry.
Grant Can View on the pipeline to the user or service principal of the credential, then retry.
选择 Fetch Test Event 获取测试事件时,节点中会显示该错误。在已发布的工作流中,每次失败的轮询都会在 Executions 执行列表中显示为失败执行。请参阅授予 CAN VIEW 权限。
对于作业,如果身份缺少 CAN VIEW 权限,Databricks 会为运行列表返回空结果,而不是 PERMISSION_DENIED。此时 Fetch Test Event 获取测试事件不会返回任何内容,已发布的触发器也会持续轮询而不报错,但永远不会触发。唯一可见的迹象是该作业未出现在 From List 从列表选择选择器中。为作业授予 CAN VIEW 权限,然后再次选择 Fetch Test Event 获取测试事件。触发器会在下一次轮询时报告授予权限前五分钟内发生的运行。
作业或管道 ID 无效
节点会在调用 Databricks 之前检查 ID:
Job ID must be a whole number:使用 Databricks 作业 URL 中显示的数字 ID。Job ID is too large to send exactly:大于9007199254740991的 ID 会在 JavaScript 中丢失精度,因此节点无法监视此作业。Pipeline ID must be a UUID:使用 Databricks 管道 URL 中显示的 ID,例如8199cd89-e2f5-4169-a6aa-656a24c8886d。
意外响应
凭据中的 Host 主机不是 Databricks 工作区 URL 时,n8n 会显示 Databricks did not return a JSON list of job runs 或 Databricks did not return a JSON list of pipeline events。请检查 Host 主机并重试。