開發、執行及管理 Microsoft Fabric 筆記本

發行項
10/15/2024

Microsoft Fabric 筆記本是開發 Apache Spark 作業和機器學習實驗的主要程式碼項目。這是資料科學家和資料工程師用來撰寫程式碼的網頁式互動式介面，受益於豐富視覺效果和 Markdown 文字。本文說明如何使用程式碼儲存格作業來開發筆記本，並加以執行。

開發筆記本

筆記本由儲存格組成，而儲存格是個別的程式碼或文字區塊，可獨立或成群執行。

我們提供豐富的作業來開發筆記本：

新增儲存格
設定主要語言
使用多種語言
整合式開發環境 (IDE) 樣式的 IntelliSense
程式碼片段
拖放以插入片段
拖放以插入影像
使用工具列按鈕格式化文字儲存格
復原/重做儲存格作業
移動儲存格
刪除儲存格
摺疊儲存格輸入
摺疊儲存格輸出
儲存格輸出安全性
鎖定或凍結儲存格
筆記本內容
Markdown 折疊
尋找並取代

新增儲存格

有多種方式可將新的儲存格新增至您的筆記本。

將游標停留在兩個儲存格之間的空隙，然後選取 [程式碼] 或 [Markdown]。
使用 [命令模式下的快速鍵]。按下 [A]，將儲存格插入目前的儲存格上方。按下 [B]，將儲存格插入目前的儲存格下方。

設定主要語言

Fabric 筆記本目前支援四種 Apache Spark 語言：

PySpark (Python)
Spark (Scala)
Spark SQL
SparkR

您可以從頂端命令列的下拉式清單中，為新加入的儲存格設定主要語言。

使用多種語言

您可以在儲存格的開頭指定正確的語言 magic 命令，以便在同個筆記本中使用多種語言。您也可以從語言選擇器切換儲存格語言。以下資料表列出用來切換儲存格語言的 magic 命令。

Magic 命令	語言	說明
%%pyspark	Python	針對 Apache Spark 內容執行 Python 查詢。
%%spark	Scala	針對 Apache Spark 內容執行 Scala 查詢。
%%sql	SparkSQL	針對 Apache Spark 內容執行 SparkSQL 查詢。
%%html	Html	針對 Apache Spark 內容執行 HTML 查詢。
%%sparkr	R	針對 Apache Spark 內容執行 R 查詢。

整合式開發環境 (IDE) 樣式的 IntelliSense

Fabric 筆記本與 Monaco 編輯器整合，將 IDE 樣式 IntelliSense 引進儲存格編輯器。語法醒目提示、錯誤標記和自動程式碼完成，協助您更快撰寫程式碼和識別問題。

IntelliSense 功能在不同語言的成熟度層級不同。以下資料表顯示 Fabric 支援的內容：

語言	語法醒目提示	語法錯誤標記	語法程式碼完成功能	變數程式碼完成	系統函數程式碼完成	使用者函數程式碼完成	智慧縮排	程式碼摺疊功能
PySpark (Python)	Yes	.是	.是	.是	.是	.是	.是	Yes
Spark (Scala)	Yes	.是	.是	.是	.是	.是	.是	Yes
SparkSQL	Yes	.是	.是	.是	是	無	.是	Yes
SparkR	Yes	.是	.是	.是	.是	.是	.是	是

注意

您必須有作用中的 Apache Spark 工作階段，才能使用 IntelliSense 程式碼完成。

程式碼片段

Fabric 筆記本提供程式碼片段，可協助您輕鬆撰寫常用的程式碼模式，例如：

將資料載入 Apache Spark DataFrame
使用 Matplotlib 繪製圖表

程式碼片段出現在 IDE 樣式 IntelliSense 的快速鍵中，並混合其他建議。程式碼片段內容配合程式碼儲存格語言。您可以輸入「片段」來檢視可用的片段。您也可以輸入任何關鍵字來查看相關片段的清單。例如，輸入 [read] 可以看到用於從各種資料來源讀取資料的程式碼片段清單。

動畫 GIF，其中顯示程式碼片段。

拖放以插入片段

使用拖放功能，輕鬆地從 Lakehouse 總管讀取資料。這裡支援多個檔案類型；您可以在文字檔、資料表、影像等上操作。您可以拖放至現有的儲存格或新的儲存格。筆記本會據此產生片段，以預覽資料。

動畫 GIF，其中顯示拖放以插入片段。

拖放以插入影像

此外，您也可以從瀏覽器或本機電腦拖放影像，輕鬆地將影像插入 Markdown 儲存格。

動畫 GIF，其中顯示拖放以插入影像。

您可以使用文字儲存格工具列中的格式按鈕來執行常見的 Markdown 動作。

復原/重做儲存格作業

選取 [復原] 或是 [重做] 按鈕或按下 [Z] 或是 [Shift+Z] 可撤銷最近的儲存格作業。您最多可以復原或是重做最後 10 個儲存格動作。

支援的復原儲存格作業：

插入或刪除儲存格。您可以選取 [復原] 來撤銷刪除作業，文字內容會與儲存格一起保存。
重新排序儲存格。
切換參數。
在程式碼儲存格與 Markdown 儲存格之間轉換。

注意

儲存格內文字作業和程式碼儲存格註解作業無法復原。您最多可以復原或是重做最後 10 個儲存格動作。

移動儲存格

您可以從儲存格的空白部分拖曳，並將其放至所需的位置。

您也可以使用功能區上的 [上移] 和 [下移] 來移動選取的儲存格。

刪除儲存格

若要刪除儲存格，請選取資料格右側的刪除按鈕。

您也可以使用 [命令模式下的快速鍵]。按下 [Shift+D] 可刪除目前的儲存格。

摺疊儲存格輸入

在儲存格工具列上選取 [更多命令] 省略符號 (...)，然後選取 [隱藏輸入]，以摺疊目前儲存格的輸入。若要展開，請在儲存格已摺疊時選取 [顯示輸入]。

摺疊儲存格輸出

選取儲存格工具列上的 [更多命令] 省略符號 (...)，然後選取 [隱藏輸出]，以摺疊目前儲存格的輸出。若要再次展開，請在儲存格輸出折疊時，選取 [顯示輸出]。

儲存格輸出安全性

使用＜OneLake 資料存取角色 (預覽版)＞，使用者可以在筆記本查詢期間，只設定對 Lakehouse 中特定資料夾的存取權。沒有資料夾或資料表存取權的使用者，會在查詢執行期間看到未經授權的錯誤。

重要

安全性只會在查詢執行期間套用，而且任何包含查詢結果的筆記本儲存格都可以由未獲授權直接對資料執行查詢的使用者檢視。

鎖定或凍結儲存格

鎖定和凍結儲存格作業，可讓您將儲存格設定為唯讀，或停止個別執行程式碼儲存格。

動畫 GIF，其中顯示鎖定或凍結儲存格。

合併和分割儲存格

您可以使用 [與上一個儲存格合併] 或 [與下一個儲存格合併] 輕鬆地合併相關儲存格。

選取 [分割儲存格] 可協助您將不相關的語句分割成多個單元格。作業會根據游標的行位置來分割程序碼。

筆記本內容

選取 [大綱] 或 [目錄]，側邊欄視窗會顯示第一個 Markdown 標頭中任何 Markdown 儲存格，以方便快速導覽。 [大綱] 側邊欄可調整大小也可摺疊，以最適合畫面大小。您可以選取筆記本命令列上的 [大綱] 按鈕，以開啟或隱藏側邊欄。

Markdown 折疊

Markdown 折疊選項可讓您在 Markdown 儲存格底下，隱藏包含標題的儲存格。在執行儲存格作業時，Markdown 儲存格及其隱藏儲存格會與連續多重選取的儲存格一樣處理。

動畫 GIF，其中顯示Markdown 折疊。

尋找並取代

尋找和取代選項可協助您比對筆記本內容中的關鍵字或運算式。您也可以輕鬆地將目標字串取代為新的字串。

執行筆記本

您可以個別或一次全部在您的筆記本中執行程式碼儲存格。每個儲存格的狀態和進度都會在筆記本中表示。

執行儲存格

有數種方式可以在儲存格中執行程式碼。

將游標停留在您想要執行的儲存格上，然後選取 [執行儲存格] 按鈕，或按下 [Ctrl+Enter]。
使用 [命令模式下的快速鍵]。按下 [Shift+Enter] 以執行目前的儲存格，然後選取下方的儲存格。按下 [Alt+Enter] 以執行目前的儲存格，並在下方插入新的儲存格。

執行所有儲存格

選取 [全部執行] 按鈕，依序執行目前筆記本中的所有儲存格。

執行上方或下方所有儲存格

展開 [全部執行] 按鈕的下拉式清單，然後選取 [執行上方的儲存格]，以依序執行目前儲存格上方的所有儲存格。選取 [執行下方的儲存格]，依序執行目前儲存格下方的所有儲存格。

取消所有執行中的儲存格

選取 [全部取消] 按鈕，以取消執行中的儲存格或在佇列中等待的儲存格。

停止工作階段

[停止工作階段] 會取消執行和等待中的儲存格，並停止目前的工作階段。您可以再次選取 [執行] 選項，以重新啟動全新的工作階段。

參考應用程式

參考執行筆記本

除了 Notebookutils 參考執行 API 之外，您也可以使用 %run <notebook name> magic 命令來參考目前筆記本內容中的另一個筆記本。參考筆記本中定義的所有變數都可以在目前的筆記本中使用。 %runmagic 命令支援巢狀呼叫，但不支援遞迴呼叫。如果陳述式深度大於五，您會收到例外狀況。

範例：%run Notebook1 { "parameterInt": 1, "parameterFloat": 2.5, "parameterBool": true, "parameterString": "abc" }。

筆記本參考在互動模式和管線中都有作用。

注意

此 %run命令目前僅支援與目前筆記本位於相同工作區中的參考筆記本。
%run此命令目前僅支援最多四個參數值類型：int、float、bool 和 string。不支援變數取代作業。
%run此命令不支援深度大於「五」的巢狀參考。

參考執行指令碼

%run此命令也可讓您執行儲存在筆記本內建資源的 Python 或 SQL 檔案，以便方便地在筆記本中執行原始碼檔案。

%run [-b/--builtin -c/--current] [script_file.py/.sql] [variables ...]

針對選項：

-b/--builtin：此選項表示命令會從筆記本的內建資源尋找並執行指定的指令檔。
-c/--current：此選項可確保命令一律使用目前筆記本的內建資源，即使目前的筆記本是由其他筆記本參考也一樣。

範例：

從內建資源執行 script_file.py：%run -b script_file.py
從內建資源執行 script_file.sql：%run -b script_file.sql
從具有特定變數的內建資源執行 script_file.py：%run -b script_file.py { "parameterInt": 1, "parameterFloat": 2.5, "parameterBool": true, "parameterString": "abc" }

注意

如果命令不包含 -b/--builtin，它會嘗試在相同的工作區內 (而不是內建資源內) 尋找和執行筆記本項目。

巢狀執行案例的使用範例：

假設我們有兩個筆記本。
- Notebook1：在其內建資源中包含 script_file1.py
- Notebook2：在其內建資源中包含 script_file2.py
讓我們使用 Notebook1 作為包含內容的根筆記本：%run Notebook2。
然後在 Notebook2 中，使用指示如下：
- 若要在 Notebook1 (根筆記本) 中執行 script_file1.py，程式碼會是：%run -b script_file1.py
- 若要在 Notebook2 (目前筆記本) 中執行 script_file2.py，程式碼會是：%run -b -c script_file2.py

變數總管

Fabric 筆記本提供內建變數總管，讓您在目前的 Spark 工作階段中，查看 PySpark (Python) 儲存格的變數名稱、型別、長度和值的清單。隨著程式碼儲存格中定義變數，將會自動出現越多變數。按一下每個資料行標頭會排序資料表中的變數。

若要開啟或隱藏變數總管，請選取筆記本功能區 [檢視] 上的 [變數]。

注意

變數總管僅支援 Python。

儲存格狀態指標

儲存格下方會逐步顯示儲存格執行狀態，以協助您檢視目前的進度。儲存格執行完成之後，會顯示包含總持續時間和結束時間的執行摘要，並保留在該處供日後參考。

內嵌 Apache Spark 作業指標

Fabric 筆記本是以 Apache Spark 為基礎。程式碼儲存格在遠端的 Apache Spark 集區上執行。系統隨即會提供具有即時進度列的 Spark 作業進度列指示器，以協助您了解作業執行狀態。每個作業或階段的工作數目可協助您找出 Spark 作業的平行層級。您也可以透過選取作業 (或階段) 名稱上的連結，更深入鑽研特定工作 (或階段) 的 Spark UI。

您也可以在進度指示器旁邊找到 [儲存格層級實時記錄檔]，而 [診斷] 可以提供實用的建議，協助您精簡和偵錯程序碼。

在 [更多動作] 中，您可以輕鬆地流覽至 [Spark 應用程式] 詳細資料頁面和 [Spark Web UI] 頁面。

祕密修訂

為了避免在執行筆記本時意外洩漏認證，Fabric 筆記本支援 秘密修訂 ，以取代儲存格輸出 [REDACTED]中顯示的祕密值。祕密修訂適用於 Python、Scala 和 R。

筆記本中的 Magic 命令

內建 Magic 命令

您可以在 Fabric 筆記本中使用熟悉的 Ipython magic 命令。請檢閱下列目前可用的 Magic 命令清單。

注意

這些是 Fabric 管線中唯一支援的 magic 命令：%%pyspark、%%spark、%csharp、%%sql、%%configure。

可用的行 magic 命令： %lsmagic、%time、%timeit、%history、%run、%load、%alias、%alias_magic、%autoawait、%autocall， %automagic、%bookmark、%cd、%colors、%dhist、%dirs、%doctest_mode、%killbgscripts、%load_ext、%logoff、%logon、%logstart、%logstate、%logstop、%magic、%matplotlib、%page、%pastebin、%pdef、%pfile、%pinfo、%pinfo2、%popd、%pprint、%precision、%prun、%psearch、%psource、%pushd、%pwd、%pycat、%quickref、%rehashx、%reload_ext、%reset、%reset_selective、%sx、%system、%tb、%unalias、%unload_ext、%who、%who_ls、%who、%xdel、%xmode。

Fabric 筆記本也支援改善的程式庫管理命令 %pip 和 %conda。如需使用方式的詳細資訊，請參閱＜在 Microsoft Fabric 中管理 Apache Spark 連結庫＞。

可用的儲存格 magic 命令：%%time、%%timeit、%%capture、%%writefile、%%sql、%%pyspark、%%spark、%%csharp、%%configure、%%html、%%bash、%%markdown、%%perl、%%script、%%sh。

自訂 magic 命令

您也可以建置更多自訂 magic 命令，以符合您的特定需求。以下是範例：

建立名稱為 "MyLakehouseModule" 的筆記本。
在另一個筆記本中，參考 "MyLakehouseModule" 及其 magic 命令。此程式可讓您使用不同語言的筆記本，輕鬆地組織專案。

IPython 小工具

IPython 小工具是瀏覽器中具有表示法與事件性質的 Python 物件。您可以使用 IPython 小工具作為筆記本中的低程式碼控件 (例如滑桿或文本框)，就像 Jupyter 筆記本一樣。目前它只適用於 Python 內容。

使用 IPython 小工具

您必須先匯入 ipywidgets 模組，才能使用 Jupyter 小工具架構。
```
import ipywidgets as widgets
```
使用最上層的顯示函式來轉譯小工具，或將小工具類型的運算式保留在程式代碼數據格的最後一行。
```
slider = widgets.IntSlider()
display(slider)
```
執行儲存格。小工具會顯示在輸出區域中。
```
slider = widgets.IntSlider()
display(slider)
```
使用多個 display() 呼叫來轉譯相同的小工具執行個體多次。它們彼此保持同步。
```
slider = widgets.IntSlider()
display(slider)
display(slider)
```

若要呈現彼此獨立的兩個小工具，請建立兩個小工具執行個體：

slider1 = widgets.IntSlider()
slider2 = widgets.IntSlider()
display(slider1)
display(slider2)

支援的小工具

小工具類型	Widget
數值小工具	IntSlider、FloatSlider、FloatLogSlider、IntRangeSlider、FloatRangeSlider、IntProgress、FloatProgress、BoundedIntText、BoundedFloatText、IntText、FloatText
布林值小工具	ToggleButton、Checkbox、Valid
選取項目小工具	Dropdown、RadioButtons、Select、SelectionSlider、SelectionRangeSlider、ToggleButtons、SelectMultiple
字串小工具	Text、Text area、Combobox、Password、Label、HTML、HTML Math、Image、Button
播放 (動畫) 小工具	日期選擇器、色彩選擇器、控制器
容器或版面配置小工具	Box、HBox、VBox、GridBox、Accordion、Tabs、Stacked

已知的限制

尚未支援下列項目：以下是可用的因應措施：

功能	因應措施
輸出小工具	您可以改用 print() 函數將文字寫入 stdout。
widgets.jslink()	您可以使用 widgets.link() 函數來連結兩個相似的小工具。
FileUpload 小工具	尚不支援。

Fabric 全域顯示函數不支援在一個呼叫中顯示多個小工具 (例如 display (a， b))。此行為與 IPython 顯示函數不同。
如果您關閉包含 IPython 小工具的筆記本，除非再次執行對應的儲存格，否則無法看到小工具或與之互動。
不支援互動函數 (ipywidgets.interact)。

整合筆記本

指定參數儲存格

若要將筆記本參數化，請選取省略符號 (...)，以存取儲存格工具列上的更多命令。然後選取 [切換參數儲存格]，將儲存格指定為參數儲存格。

參數儲存格適用於整合管線中的筆記本。管線活動會尋找參數儲存格，並將此儲存格視為執行時所傳遞參數的預設。執行引擎會在參數儲存格下方加入新的儲存格，其中包含為了覆寫預設值的輸入參數。

從管線指派參數值

建立具有參數的筆記本之後，即可從管線中透過 Fabric 筆記本活動來執行。將活動新增至管線畫布之後，即可在 [設定] 索引標籤的 [基底參數] 區段下設定參數值。

指派參數值時，您可以使用管線運算式語言或函數和變數。

Spark 工作階段設定 magic 命令

您可以使用 magic 命令 %%configure 來個人化 Spark 工作階段。 Fabric 筆記本支援自訂虛擬核心數、驅動程式和執行程式的記憶體、Apache Spark 屬性、裝入點、集區，以及筆記本工作階段的預設 Lakehouse。它們可用於互動式筆記本和管線筆記本活動。建議您在筆記本開頭執行 %%configure 命令，或者您必須重新啟動 Spark 工作階段讓設定生效。

%%configure
{
    // You can get a list of valid parameters to config the session from https://github.com/cloudera/livy#request-body.
    "driverMemory": "28g", // Recommended values: ["28g", "56g", "112g", "224g", "400g", "472g"]
    "driverCores": 4, // Recommended values: [4, 8, 16, 32, 64, 80]
    "executorMemory": "28g",
    "executorCores": 4,
    "jars": ["abfs[s]: //<file_system>@<account_name>.dfs.core.windows.net/<path>/myjar.jar", "wasb[s]: //<containername>@<accountname>.blob.core.windows.net/<path>/myjar1.jar"],
    "conf":
    {
        // Example of customized property, you can specify count of lines that Spark SQL returns by configuring "livy.rsc.sql.num-rows".
        "livy.rsc.sql.num-rows": "3000",
        "spark.log.level": "ALL"
    },
    "defaultLakehouse": {  // This overwrites the default lakehouse for current session
        "name": "<lakehouse-name>",
        "id": "<(optional) lakehouse-id>",
        "workspaceId": "<(optional) workspace-id-that-contains-the-lakehouse>" // Add workspace ID if it's from another workspace
    },
    "mountPoints": [
        {
            "mountPoint": "/myMountPoint",
            "source": "abfs[s]://<file_system>@<account_name>.dfs.core.windows.net/<path>"
        },
        {
            "mountPoint": "/myMountPoint1",
            "source": "abfs[s]://<file_system>@<account_name>.dfs.core.windows.net/<path1>"
        },
    ],
    "environment": {
        "id": "<environment-id>",
        "name": "<environment-name>"
    },
    "sessionTimeoutInSeconds": 1200,
    "useStarterPool": false,  // Set to true to force using starter pool
    "useWorkspacePool": "<workspace-pool-name>"
}

注意

建議您在 %%configure 中為 "DriverMemory" 和 "ExecutorMemory" 設定相同的值。 "driverCores" 和 "executorCores" 值也應該相同。
"defaultLakehouse" 將會覆寫您在 Lakehouse 總管中釘選的 Lakehouse，但這只適用於您目前的筆記本工作階段。
您可以在 Fabric 管線中使用 %%configure，但如果未在第一個程式碼儲存格中設定，則管線執行將會因為無法重新啟動工作階段而失敗。
將會忽略 notebookutils.notebook.run 中使用的 %%configure，但在 %run 筆記本中使用的 %%會繼續執行。
必須在 "conf" 主體中使用標準 Spark 設定屬性。 Fabric 不支援在第一層參考 Spark 設定屬性。
某些特殊的 Spark 屬性 (包括 "spark.driver.cores"、"spark.executor.cores"、"spark.driver.memory"、"spark.executor.memory"、"spark.executor.instances") 不會在 "conf" 主體中生效。

來自管線的參數化工作階段設定

參數化工作階段設定可讓您將 %%configure magic 中的值以管線執行 (筆記本活動) 參數取代。準備 %%configure 程式碼儲存格時，您可以使用類似如下的物件來覆寫預設值 (下列範例中的 4 和 "2000" 也可設定)：

{
      "parameterName": "paramterNameInPipelineNotebookActivity",
      "defaultValue": "defaultValueIfNoParamterFromPipelineNotebookActivity"
}

%%configure  

{ 
    "driverCores": 
    { 
        "parameterName": "driverCoresFromNotebookActivity", 
        "defaultValue": 4 
    }, 
    "conf": 
    { 
        "livy.rsc.sql.num-rows": 
        { 
            "parameterName": "rows", 
            "defaultValue": "2000" 
        } 
    } 
}

如果直接在互動模式中執行筆記本，或管線筆記本活動提供的值皆不符合"activityParameterName"，則筆記本將會使用預設值。

在管線執行模式期間，您可以設定管線 Notebook 活動設定，如下所示：

如果您想要變更工作階段設定，管線筆記本活動參數的名稱應該與筆記本中的 parameterName 相同。在此執行管線的範例中，driverCores 在 %%configure 中會由 8 取代，livy.rsc.sql.num-rows 會由 4000 取代。

注意

如果執行管線因為使用此新的 %%configure magic 而失敗，您可以在筆記本的互動模式中執行 %%configure magic 儲存格，來查看更多錯誤資訊。
筆記本排程的執行不支援參數化工作階段設定。

筆記本中的 Python 記錄

您可以遵循下列範例程式碼來尋找 Python 記錄，並設定不同的記錄層級和格式：

import logging

# Customize the logging format for all loggers
FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
formatter = logging.Formatter(fmt=FORMAT)
for handler in logging.getLogger().handlers:
    handler.setFormatter(formatter)

# Customize log level for all loggers
logging.getLogger().setLevel(logging.INFO)

# Customize the log level for a specific logger
customizedLogger = logging.getLogger('customized')
customizedLogger.setLevel(logging.WARNING)

# logger that use the default global log level
defaultLogger = logging.getLogger('default')
defaultLogger.debug("default debug message")
defaultLogger.info("default info message")
defaultLogger.warning("default warning message")
defaultLogger.error("default error message")
defaultLogger.critical("default critical message")

# logger that use the customized log level
customizedLogger.debug("customized debug message")
customizedLogger.info("customized info message")
customizedLogger.warning("customized warning message")
customizedLogger.error("customized error message")
customizedLogger.critical("customized critical message")

檢視輸入命令的歷程記錄

Fabric 筆記本支援 magic 命令 %history，以列印在目前工作階段中執行的輸入命令歷程記錄，相較於標準 Jupyter Ipython 命令，%history 適用於筆記本中的多種語言內容。

%history [-n] [range [range ...]]