共用方式為

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

  • 發行項

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

重要

這項功能處於預覽狀態。

注意

目前不支援服務主體驗證 。

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

這些 專案管理 動作適用於筆記本：

動作 描述
建立項目 在工作區內建立筆記本。
更新項目 更新 筆記本的元數據。
更新項目定義 更新 筆記本的內容。
刪除項目 刪除筆記本。
取得專案 取得筆記本的元數據。
取得項目定義 取得筆記本的內容。
清單項目 列出工作區中的所有專案。

如需詳細資訊，請參閱 專案 - REST API。

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

動作 描述
視需要執行項目作業 使用參數化執行筆記本。
取消專案作業實例 取消筆記本作業執行。
取得專案作業實例 取得筆記本執行狀態。

如需詳細資訊，請參閱 作業排程器。

筆記本 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",
        "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 或 來變更筆記本預設 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"
            },
            "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，您可以使用 取得專案作業實例 來檢視作業狀態， 或使用取消專案作業實例 來取消目前的筆記本執行。

相關內容