使用 API 在 Fabric 中管理和执行笔记本

Microsoft Fabric REST API 为 Fabric 项的创建、读取、更新和删除 (CRUD) 操作提供服务终结点。 本文介绍可用的笔记本 REST API 及其用法。

使用笔记本 API，数据工程师和数据科学家可以实现其自己的管道的自动化，方便高效地建立 CI/CD。 这些 API 还使用户可以轻松地管理和操作 Fabric 笔记本项，并将笔记本与其他工具和系统集成。 可以通过这些 API 从 Fabric 管道和外部调度器协调安排笔记本，从而实现与自动化工作流的无缝集成。

这些条目管理操作适用于笔记本：

操作 说明
创建项目 在工作区中创建笔记本。
更新条目 更新笔记本的元数据。
更新项定义 更新笔记本的内容。
删除物品 删除笔记本。
获取条目 获取笔记本的元数据。
获取项定义 获取笔记本的内容。
列表项 列出工作区中的所有项。

有关详细信息，请参阅项 - REST API。

以下作业计划程序操作适用于笔记本：

操作 说明
按需执行项目作业 按需运行笔记本，支持参数化设定、会话设置配置（例如 Spark/计算设置）、环境和运行时的选择，以及目标 Fabric Lakehouse 的选定。
取消项目作业实例 取消笔记本作业运行。
获取项目作业实例 获取笔记本运行状态并检索运行返回的退出值。

有关详细信息，请参阅作业计划程序。

注意

Items REST API（项目 CRUD 操作）和 Job Scheduler API（执行、监控和取消）均支持服务主体身份验证。 这可实现安全的无人参与自动化和 CI/CD 方案。 将服务主体添加到工作区，并设置为适当的角色（管理员、成员或贡献者），以便管理和执行笔记本。

笔记本运行的返回值

通过作业调度程序 API 执行的笔记本运行可以返回一个退出值，该值可以用于条件编排。 退出值显示在exitValue“获取项作业实例”响应有效负载的字段中。

笔记本可以通过在运行完成之前调用 mssparkutils.notebook.exit("your-value") 来设置其退出值。 退出值是一个字符串，可以编码任何结果信号， "success"例如， "no_rows_processed"或 JSON 序列化的结果。

运行完成后，外部业务流程协调程序、Fabric 管道和其他自动化工具可以调用获取项作业实例来读取退出值并根据结果进行分支。 例如：

  1. 使用参数和执行设置提交 按需运行项作业 。
  2. 轮询 获取项作业实例 直到 status 变为 Completed（或者 Failed）。
  3. 从响应中读取 exitValue ，以确定工作流中的下一步。

此模式使能基于笔记本执行结果的条件性编排和下游信号传递。

端到端示例

以下示例展示如何提交一个笔记本的运行过程，并检索其状态和退出值。 有关完整的请求正文架构，包括参数、会话配置以及 Lakehouse 选择字段的详细信息，请参阅 作业计划程序 - 按需运行项作业 API 参考。

步骤 1：提交运行

使用按需运行项作业端点启动笔记本运行。

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances?jobType=RunNotebook

响应返回 202 Accepted，其 Location 标头包含您用于监控运行的作业实例的 URL。

步骤 2：检索运行状态和退出值

使用标头中的 Location URL 检查状态，并在运行完成后读取退出值：

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances/{jobInstanceId}

示例响应（缩写）：

{
  "id": "<jobInstanceId>",
  "itemId": "<notebookId>",
  "jobType": "RunNotebook",
  "invokeType": "OnDemand",
  "status": "Completed",
  "startTimeUtc": "2026-03-01T10:00:00Z",
  "endTimeUtc": "2026-03-01T10:05:00Z",
  "failureReason": null,
  "exitValue": "success"
}

读取 exitValue 以确定自动化逻辑的结果并相应地进行分支。

  • Last updated on