使用 API 在 Fabric 中管理和执行笔记本
Microsoft Fabric REST API 为 Fabric 项的创建、读取、更新和删除 (CRUD) 操作提供服务终结点。 本文介绍可用的笔记本 REST API 及其用法。
重要
此功能目前为预览版。
注意
服务主体身份验证适用于 Notebook CRUD API。 目前不支持运行笔记本 API。
使用笔记本 API，数据工程师和数据科学家可以实现其自己的管道的自动化，方便高效地建立 CI/CD。 这些 API 还使用户可以轻松地管理和操作 Fabric 笔记本项，并将笔记本与其他工具和系统集成。
这些项管理操作适用于笔记本：
| 操作 | 说明 |
|---|---|
| 创建项目 | 在工作区中创建笔记本。 |
| 更新项目 | 更新笔记本的元数据。 |
| 更新项定义 | 更新笔记本的内容。 |
| 删除物品 | 删除笔记本。 |
| 获取项目 | 获取笔记本的元数据。 |
| 获取项定义 | 获取笔记本的内容。 |
| 列表项 | 列出工作区中的所有项。 |
有关详细信息，请参阅项 - REST API。
以下作业计划程序操作适用于笔记本：
| 操作 | 说明 |
|---|---|
| 按需运行项作业 | 使用参数化运行笔记本。 |
| 取消项作业实例 | 取消笔记本作业运行。 |
| 获取项作业实例 | 获取笔记本运行状态。 |
有关详细信息，请参阅作业计划程序。
笔记本 REST API 用法示例
按照以下说明测试特定笔记本公共 API 的用法示例并验证结果。
注意
这些场景仅涵盖笔记本特有的用法示例。 Fabric 项常用 API 示例不在此介绍。
先决条件
Fabric Rest API 为操作定义统一终结点。 按照本文中的示例操作时，请将占位符 {WORKSPACE_ID} 和 {ARTIFACT_ID} 替换为相应的值。
创建带定义的笔记本
使用现有的 .ipynb 文件和其他类型的源文件创建笔记本项。
Request
POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items
{
"displayName":"Notebook1",
"type":"Notebook",
"definition" : {
"format": "ipynb", // Use "fabricGitSource" for source file format.
"parts": [
{
"path": "notebook-content.ipynb", // fabric source file format, .py, .scala, .sql files are supported.
"payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
"payloadType": "InlineBase64"
}
]
}
}
请求中的有效负载是从以下示例笔记本转换而来的 base64 字符串。
{
"nbformat": 4,
"nbformat_minor": 5,
"cells": [
{
"cell_type": "code",
"source": [
"# Welcome to your new notebook\n# Type here in the cell editor to add code!\n"
],
"execution_count": null,
"outputs": [],
"metadata": {}
}
],
"metadata": {
"language_info": {
"name": "python"
},
"dependencies": {
"environment": {
"environmentId": "6524967a-18dc-44ae-86d1-0ec903e7ca05",
"workspaceId": "c31eddd2-26e6-4aa3-9abb-c223d3017004"
},
"lakehouse": {
"default_lakehouse": "5b7cb89a-81fa-4d8f-87c9-3c5b30083bee",
"default_lakehouse_name": "lakehouse_name",
"default_lakehouse_workspace_id": "c31eddd2-26e6-4aa3-9abb-c223d3017004"
}
}
}
}
注意
可以通过更改笔记本内容 metadata.trident.lakehouse 或 metadata.trident.environment 来更改笔记本默认湖屋或附加环境。
获取带定义的笔记本
使用以下 API 获取笔记本内容。 Fabric 支持你在查询字符串中将格式设置为 .ipynb 以获取 .ipynb 笔记本。
请求
POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items/{{ARTIFACT_ID}}/GetDefinition?format=ipynb
响应
状态代码：200
{
"definition": {
"parts": [
{
"path": "notebook-content.ipynb",
"payload": "eyJuYmZvcm1hdCI6NCwibmJmb3JtYXRfbWlub3IiOjUsImNlbGxzIjpbeyJjZWxsX3R5cGUiOiJjb2RlIiwic291cmNlIjpbIiMgV2VsY29tZSB0byB5b3VyIG5ldyBub3RlYm9va1xuIyBUeXBlIGhlcmUgaW4gdGhlIGNlbGwgZWRpdG9yIHRvIGFkZCBjb2RlIVxuIl0sImV4ZWN1dGlvbl9jb3VudCI6bnVsbCwib3V0cHV0cyI6W10sIm1ldGFkYXRhIjp7fX1dLCJtZXRhZGF0YSI6eyJsYW5ndWFnZV9pbmZvIjp7Im5hbWUiOiJweXRob24ifX19",
"payloadType": "InlineBase64"
}
]
}
}
按需运行笔记本
使用以下 API 计划笔记本运行。 Spark 作业在请求成功后开始执行。
Fabric 支持在请求正文中传递 parameters 以参数化笔记本运行。 这些值由笔记本参数单元格使用。
你还可以使用 configuration 来个性化笔记本运行的 Spark 会话。 configuration 与 Spark 会话配置 magic 命令共享同一协定。
Request
POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items/{{ARTIFACT_ID}}/jobs/instances?jobType=RunNotebook
{
"executionData": {
"parameters": {
"parameterName": {
"value": "new value",
"type": "string"
}
},
"configuration": {
"conf": {
"spark.conf1": "value"
},
"environment": {
"id": "<environment_id>",
"name": "<environment_name>"
},
"defaultLakehouse": {
"name": "<lakehouse-name>",
"id": "<lakehouse-id>",
"workspaceId": "<(optional) workspace-id-that-contains-the-lakehouse>"
},
"useStarterPool": false,
"useWorkspacePool": "<workspace-pool-name>"
}
}
}
响应
状态代码：202
Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60
通过 location，你可以使用获取项作业实例来查看作业状态，或使用取消项作业实例来取消当前笔记本运行。