使用 API 在 Fabric 中管理和執行筆記本
Microsoft 網狀架構 REST API 會為網狀架構項目的建立、讀取、更新和刪除作業提供服務端點。 本文說明可用的筆記本 REST API 及其使用方式。
重要
此功能處於預覽。
注意
服務主體驗證 適用於 Notebook CRUD API。 目前不支援執行筆記本 API。
透過筆記本 API，資料工程師和資料科學家可以自動化自己的管線，並方便且有效率地建立 CI/CD。 這些 API 也可讓使用者輕鬆管理及操作 Fabric 筆記本項目，並將筆記本與其他工具和系統整合。
這些項目管理動作適用於筆記本：
| 動作 | 描述 |
|---|---|
| 建立項目 | 在工作區內建立筆記本。 |
| 更新項目 | 更新筆記本的中繼資料。 |
| 更新項目定義 | 更新筆記本的內容。 |
| 刪除項目 | 刪除筆記本。 |
| Get item | 取得筆記本的中繼資料。 |
| 取得項目定義 | 取得筆記本的內容。 |
| 清單項目 | 列出工作區中的所有項目。 |
如需詳細資訊，請參閱 項目 - REST API。
下列 作業排程器 動作適用於筆記本：
| 動作 | 描述 |
|---|---|
| 視需要執行項目作業 | 使用參數化執行筆記本。 |
| 取消項目工作執行個體 | 取消筆記本作業執行。 |
| 取得項目工作執行個體 | 取得筆記本執行狀態。 |
如需詳細資訊，請參閱 Job Scheduler。
筆記本 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，您可以使用取得項目工作執行個體來檢視作業狀態，或使用取消項目工作執行個體來取消目前的筆記本執行。