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

發行項
04/24/2024

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

開發筆記本

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

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

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

新增儲存格

有多種方式可將新單元格新增至筆記本。

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

設定主要語言

網狀架構筆記本目前支援四種 Apache Spark 語言：

PySpark (Python)
Spark (Scala)
Spark SQL
SparkR

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

使用多種語言

您可以在筆記本中使用多種語言，方法是在儲存格開頭指定語言 magic 命令。您也可以從語言選擇器切換儲存格語言。下表列出切換單元格語言的magic命令。

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

IDE 樣式 IntelliSense

網狀架構筆記本與摩納哥編輯器整合，可將IDE樣式的IntelliSense帶入數據格編輯器。語法醒目提示、錯誤標記和自動程式代碼完成可協助您快速撰寫程式代碼並識別問題。

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

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

注意

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

程式碼片段

網狀架構筆記本提供代碼段，可協助您輕鬆撰寫常用的程式代碼模式，例如：

以 Spark DataFrame 讀取數據
使用 Matplotlib 繪製圖表

代碼段會出現在 IDE 樣式 IntelliSense 的快速鍵中，與其他建議混合。代碼段內容會與程式代碼數據格語言一致。您可以輸入 代碼段來檢視可用的代碼段。您也可以輸入任何關鍵詞來查看相關代碼段的清單。例如，如果您輸入 read，您會看到從各種數據源讀取資料的代碼段清單。

代碼段的動畫 GIF。

拖放以插入代碼段

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

拖放的動畫 GIF 以插入代碼段。

拖放以插入影像

使用拖放功能，輕鬆地將影像從瀏覽器或本機計算機插入 Markdown 儲存格。

拖放的動畫 GIF 以插入影像。

若要完成一般 Markdown 動作，請使用文字儲存格工具列中的格式按鈕。

復原或重做單元格作業

選取 [復原] 或 [取消復原]，或按 Z 或 Shift+Z 以撤銷最新的儲存格作業。您最多可以復原或重做 10 個最新的歷程記錄數據格作業。

支援的復原儲存格作業：

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

注意

無法復原儲存格內文字作業和程式代碼數據格批注作業。您最多可以復原或重做 10 個最新的歷程記錄數據格作業。

移動儲存格

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

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

刪除儲存格

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

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

折疊儲存格輸入

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

折疊單元格輸出

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

單元格輸出安全性

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

重要

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

鎖定或凍結單元格

鎖定和凍結數據格作業可讓您讓儲存格唯讀或停止個別執行程式代碼數據格。

鎖定或凍結儲存格的動畫GIF。

合併和分割儲存格

您可以使用 [與上一個儲存格合併] 或 [與下一個儲存格合併] 來方便合併相關儲存格。

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

筆記本內容

選取 [大綱] 或 [目錄] 會顯示提要視窗內任何 Markdown 單元格的第一個 Markdown 標頭，以供快速流覽。 [大綱] 提要字段可重設大小且可折疊，以盡可能以最佳方式調整螢幕大小。選取 筆記本命令行上的 [內容] 按鈕，以開啟或隱藏提要字段。

Markdown 折疊

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

Markdown 折迭的動畫 GIF。

尋找並取代

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

執行筆記本

您可以個別或一次地在筆記本中執行程式碼數據格。每個儲存格的狀態和進度會顯示在筆記本中。

執行儲存格

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

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

執行所有儲存格

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

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

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

取消所有執行中的儲存格

選取 [ 全部取消] 以取消佇列中等候的執行單元格或儲存格。

停止工作階段

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

參考執行

參考執行筆記本

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

範例：%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

變數總管

網狀架構筆記本提供內建的變數總管，可在 PySpark （Python）單元格的目前 Spark 會話中顯示變數名稱、類型、長度和值的清單。更多變數會在程式代碼數據格中定義時自動顯示。按兩下每個資料列標頭會排序資料表中的變數。

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

注意

變數總管僅支援 Python。

單元格狀態指示器

數據格下會顯示逐步數據格執行狀態，以協助您查看其目前進度。一旦數據格執行完成，就會顯示總持續時間和結束時間的執行摘要，並儲存在那裡供日後參考。

內嵌Spark作業指標

網狀架構筆記本是以Spark為基礎。程式代碼數據格會從遠端在Spark叢集上執行。 Spark 作業進度指示器會提供即時進度列，可協助您了解作業執行狀態。每個作業或階段的工作數目可協助您識別 Spark 作業的平行層級。您也可以透過選取作業 (或階段) 名稱上的連結，更深入鑽研特定工作 (或階段) 的 Spark UI。

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

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

秘密修訂

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

筆記本中的Magic命令

內建magic命令

您可以在網狀架構筆記本中使用熟悉的Ipythonmagic命令。檢閱下列目前可用的 magic 命令清單。

注意

這些是網狀架構管線中唯一支援的魔術命令：%%pyspark、%%spark、%csharp、%%sql、%%configure。

可用的行魔術命令： %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、%pinfo、%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。

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

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

自訂魔術命令

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

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

IPython 小工具

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

使用 IPython 小工具

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

若要讓兩個小工具彼此獨立轉譯，請建立兩個 Widget 實例：

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

支援的 Widget

Widget 類型	部件
數值小工具	IntSlider、FloatSlider、FloatLogSlider、IntRangeSlider、FloatRangeSlider、IntProgress、FloatProgress、BoundedIntText、BoundedFloatText、IntText、FloatText
布爾小工具	ToggleButton、複選框、有效
選取小工具	下拉式清單、RadioButtons、Select、SelectionSlider、SelectionRangeSlider、ToggleButtons、SelectMultiple
字串小工具	文字、文字區域、組合框、密碼、標籤、HTML、HTML 數學、影像、按鈕
播放（動畫）小工具	日期選擇器、色彩選擇器、控制器
容器或版面配置小工具	Box、HBox、VBox、GridBox、Accordion、Tabs、Stacked

已知的限制

尚不支援下列小工具。以下是可用的因應措施：

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

Fabric 全域顯示函式不支援在一個呼叫中顯示多個小工具（例如 display（a， b） 。此行為與 IPython 顯示函式不同。
如果您關閉包含 IPython 小工具的筆記本，則直到您再次執行對應的儲存格，才能看到或與其互動。

整合筆記本

指定參數數據格

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

參數數據格適用於整合管線中的筆記本。管線活動會尋找參數數據格，並將此儲存格視為運行時間傳入之參數的預設值。執行引擎會在具有輸入參數的參數數據格底下加入新的儲存格，以覆寫預設值。

從管線指派參數值

使用參數建立筆記本之後，您可以使用 Fabric 筆記本活動從管線執行它。將活動新增至管線畫布之後，您可以在 [設定] 索引標籤的 [基底參數] 區段下設定參數值。

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

Spark 工作階段設定 magic 命令

您可以使用 magic 命令 %%configure 來個人化 Spark 工作階段。網狀架構筆記本支援自定義的虛擬核心、驅動程式和執行程式的記憶體、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": "<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>"
        },
    ],
    "useStarterPool": false,  // Set to true to force using starter pool
    "useWorkspacePool": "<workspace-pool-name>"
}

注意

建議您在 %%configure 中為 “DriverMemory” 和 “ExecutorMemory” 設定相同的值。 “driverCores” 和 “executorCores” 值也應該相同。
“defaultLakehouse” 將會覆寫您在 Lakehouse 總管中釘選的 Lakehouse，但這只適用於您目前的筆記本會話。
您可以在網狀架構管線中使用 %%configure，但如果它未在第一個程式代碼數據格中設定，管線執行將會因為無法重新啟動會話而失敗。
mssparkutils.notebook.run 中使用的 %%設定將會被忽略，但在 %run 筆記本中使用的 %%會繼續執行。
標準 Spark 組態屬性必須在「conf」主體中使用。 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」的參數，筆記本會使用預設值。

在管線執行期間，您可以設定管線筆記本活動設定，如下所示：

如果您想要變更會話設定，管線筆記本活動參數名稱應該與 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")

檢視輸入命令的歷程記錄

網狀架構筆記本支援magic命令 %history 來列印在目前會話中執行的輸入命令歷程記錄，相較於標準 Jupyter Ipython 命令，該 %history 命令適用於筆記本中的多種語言內容。

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