共用方式為

使用 API 在 Fabric 中管理和執行筆記本

  • 發行項

Microsoft 網狀架構 REST API 會為網狀架構項目的建立、讀取、更新和刪除作業提供服務端點。 本文說明可用的筆記本 REST API 及其使用方式。

重要

此功能處於預覽。

透過筆記本 API，資料工程師和資料科學家可以自動化自己的管線，並方便且有效率地建立 CI/CD。 這些 API 也可讓使用者輕鬆管理及操作 Fabric 筆記本項目，並將筆記本與其他工具和系統整合。

這些項目管理動作適用於筆記本：

動作 描述
建立項目 在工作區內建立筆記本。
更新項目 更新筆記本的中繼資料。
更新項目定義 更新筆記本的內容。
刪除項目 刪除筆記本。
Get item 取得筆記本的中繼資料。
取得項目定義 取得筆記本的內容。
清單項目 列出工作區中的所有項目。

如需詳細資訊，請參閱 項目 - REST API。

下列 作業排程器 動作適用於筆記本：

動作 描述
視需要執行項目作業 使用參數化執行筆記本。
取消項目工作執行個體 取消筆記本作業執行。
取得項目工作執行個體 取得筆記本執行狀態。

如需詳細資訊，請參閱 Job Scheduler。

注意

服務主體驗證適用於 Notebook CRUD API 和作業排程 API，這表示您可以使用服務主體來執行 CRUD 操作、觸發或取消 Notebook 執行，並獲取執行狀態。 您必須將服務主體新增至具有適當角色的工作區。

筆記本 REST API 使用範例

使用下列指示來測試特定筆記本公用 API 的使用範例，並驗證結果。

注意

這些案例只涵蓋筆記本唯一的使用範例。 此處未涵蓋網狀架構項目常見的 API 範例。

必要條件

網狀架構 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", // 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 或 來變更筆記本預設 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 命令共用相同的合約。

要求

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，您可以使用取得項目工作執行個體來檢視作業狀態，或使用取消項目工作執行個體來取消目前的筆記本執行。

相關內容