通过

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

  • 项目

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

重要

此功能目前为预览版。

注意

目前不支持服务主体身份验证。

使用笔记本 API，数据工程师和数据科学家可以实现其自己的管道的自动化，方便高效地建立 CI/CD。 这些 API 还使用户可以轻松地管理和操作 Fabric 笔记本项，并将笔记本与其他工具和系统集成。

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

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

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

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

操作 说明
按需运行项作业 使用参数化运行笔记本。
取消项作业实例 取消笔记本作业运行。
获取项作业实例 获取笔记本运行状态。

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

笔记本 REST API 用法示例

按照以下说明测试特定笔记本公共 API 的用法示例并验证结果。

注意

这些场景仅涵盖笔记本特有的用法示例。 Fabric 项常用 API 示例不在此介绍。

先决条件

Fabric Rest API 为操作定义统一终结点。 按照本文中的示例操作时，请将占位符 {WORKSPACE_ID} 和 {ARTIFACT_ID} 替换为相应的值。

创建带定义的笔记本

使用现有的 .ipynb 文件创建笔记本项：

请求

POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/items

{
    "displayName":"Notebook1",
    "type":"Notebook",
    "definition" : {
        "format": "ipynb",
        "parts": [
            {
                "path": "artifact.content.ipynb",
                "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"
        },
        "trident": {
            "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"
            },
            "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，你可以使用获取项作业实例来查看作业状态，或使用取消项作业实例来取消当前笔记本运行。

相关内容