建立、開發及維護 Synapse 筆記本

發行項
08/09/2024

Azure Synapse Analytics 中的筆記本（Synapse Notebook）是一個 Web 介面，可讓您建立包含即時程式代碼、視覺效果和敘事文字的檔案。筆記本是驗證想法和使用快速實驗從您的資料取得見解的絕佳位置。筆記本也廣泛使用於數據準備、數據視覺效果、機器學習和其他巨量數據案例。

Synapse 筆記本的用途：

無須設定即可開始使用。
使用內建企業安全性功能協助保護數據安全。
分析原始格式的數據（例如 CSV、TXT 和 JSON）、已處理檔格式（例如 Parquet、Delta Lake 和 ORC），以及針對 Spark 和 SQL 的 SQL 表格式數據檔。
透過增強的撰寫功能和內建的資料視覺效果，提高生產力。

本文說明如何在 Synapse Studio 中使用筆記本。

建立筆記本

您可以建立新的筆記本，或從 物件總管 將現有的筆記本匯入至 Synapse 工作區。選取 [開發]，以滑鼠右鍵按兩下 [筆記本]，然後選取 [新增筆記本] 或 [匯入]。 Synapse 筆記本可辨識標準 Jupyter Notebook IPYNB 檔案。

用於建立或匯入筆記本之選取項目的螢幕快照。

開發筆記本

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

下列各節說明開發筆記本的作業：

新增儲存格
設定主要語言
使用多種語言
使用臨時表跨語言參考數據
使用 IDE 樣式 IntelliSense
使用程式碼片段
使用工具列按鈕格式化文字儲存格
復原或取消復原單元格作業
程式代碼儲存格的批註
移動儲存格
刪除儲存格
折疊儲存格輸入
折疊單元格輸出
使用筆記本大綱

注意

在筆記本中， SparkSession 系統會自動為您建立實例，並儲存在稱為的 spark變數中。也有稱為sc的SparkContext變數。使用者可以直接存取這些變數，但不應該變更這些變數的值。

新增儲存格

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

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

設定主要語言

Synapse 筆記本支援四種 Apache Spark 語言：

PySpark (Python)
Spark (Scala)
Spark SQL
.NET Spark (C#)
SparkR (R)

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

在 Synapse 筆記本中選取語言的下拉式清單螢幕快照。

使用多種語言

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

Magic 命令	語言	描述
`%%pyspark`	Python	對 `SparkContext`執行 Python 查詢。
`%%spark`	Scala	對 `SparkContext`執行 Scala 查詢。
`%%sql`	Spark SQL	對 `SparkContext`執行 Spark SQL 查詢。
`%%csharp`	適用於 Spark C# 的 .NET	針對執行適用於 Spark C# 查詢的 `SparkContext`.NET。
`%%sparkr`	R	對 `SparkContext`執行 R 查詢。

下圖顯示如何使用 magic 命令或 Spark SQL 查詢，在 Spark （Scala）筆記本中使用 magic 命令來撰寫 PySpark %%pyspark 查詢 %%sql 的範例。筆記本的主要語言會設定為 PySpark。

Synapse 筆記本中 Spark magic 命令的螢幕快照。

使用臨時表跨語言參考數據

您無法直接在 Synapse 筆記本中跨不同語言參考數據或變數。在Spark中，您可以跨語言參考臨時表。以下是如何使用 Spark 臨時表作為因應措施，在 PySpark 和 Spark SQL 中讀取 Scala DataFrame 的範例：

在儲存格 1 中，使用 Scala 從 SQL 集區連接器讀取 DataFrame，並建立臨時表：

%%spark
val scalaDataFrame = spark.read.sqlanalytics("mySQLPoolDatabase.dbo.mySQLPoolTable")
scalaDataFrame.createOrReplaceTempView( "mydataframetable" )

在儲存格 2 中，使用 Spark SQL 查詢資料：
```
%%sql
SELECT * FROM mydataframetable
```

在儲存格 3 中，使用 PySpark 中的數據：

%%pyspark
myNewPythonDataFrame = spark.sql("SELECT * FROM mydataframetable")

使用 IDE 樣式 IntelliSense

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

IntelliSense 功能在不同語言的成熟度層級不同。使用下表來查看支援的功能。

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

使用中的Spark會話必須受益於變數程式代碼完成、系統函式程式碼完成，以及適用於Spark的 .NET使用者函式程式碼完成（C#）。

使用代碼段

Synapse 筆記本提供代碼段，可讓您更輕鬆地輸入常用的程式代碼模式。這些模式包括設定 Spark 工作階段、將資料讀取為 Spark 資料框架，以及使用 Matplotlib 繪製圖表。

代碼段會出現在 IDE 樣式 IntelliSense 的快速鍵中，與其他建議混合。代碼段的內容會與程式代碼數據格語言一致。您可以輸入 代碼段 或程式碼儲存格編輯器中代碼段標題中顯示的任何關鍵字，來查看可用的代碼段。例如，藉由輸入 read，您可以看到從各種數據源讀取資料的代碼段清單。

Synapse 筆記本中代碼段的動畫 GIF。

您可以使用文字儲存格工具列上的格式按鈕來執行常見的 Markdown 動作。這些動作包括讓文字粗體、製作文字斜體、透過下拉功能表建立段落和標題、插入程式代碼、插入未排序的清單、插入已排序的清單、插入超連結，以及從URL插入影像。

Synapse 筆記本中文字數據格工具列的螢幕快照。

復原或取消復原單元格作業

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

Synapse 筆記本中 [復原] 和 [取消復原] 按鈕的螢幕快照。

支援的儲存格作業包括：

插入或刪除儲存格。您可以選取 [復原] 來撤銷刪除作業。此動作會保留文字內容與儲存格。
重新排列儲存格。
開啟或關閉參數儲存格。
在程式代碼儲存格和 Markdown 儲存格之間轉換。

注意

您無法復原儲存格中的文字作業或批註作業。

程式代碼儲存格的批註

選取筆記本工具列上的 [ 批注 ] 按鈕，以開啟 [ 批注 ] 窗格。
在程式代碼數據格中選取程式代碼，選取 [批注] 窗格上的 [新增]，新增批注，然後選取 [張貼批注] 按鈕。
如有必要，您可以選取批注旁的 [更多省略號]，以執行 [編輯批注]、[解析線程] 和 [刪除線程] 動作。

移動儲存格

若要移動儲存格，請選取儲存格的左側，並將儲存格拖曳至所需的位置。

Synapse 筆記本中移動儲存格的動畫 GIF。

刪除儲存格

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

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

用於刪除 Synapse 筆記本中儲存格的按鈕螢幕快照。

折疊儲存格輸入

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

折疊單元格輸出

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

使用筆記本大綱

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

執行筆記本

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

注意

刪除筆記本不會自動取消目前正在執行的任何作業。如果您需要取消作業，請移至 [監視] 中樞，然後手動取消。

執行儲存格

有多種方式可以在數據格中執行程式碼：

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

執行所有儲存格

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

在 Synapse 筆記本中執行所有儲存格的按鈕螢幕快照。

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

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

在 Synapse 筆記本中目前儲存格上方和下方執行儲存格的命令螢幕快照。

取消所有執行中的儲存格

若要取消在佇列中等候的執行單元格或儲存格，請選取 [ 取消所有 ] 按鈕。

用於取消 Synapse 筆記本中所有執行或等候儲存格的按鈕螢幕快照。

參考筆記本

若要參考目前筆記本內容中的另一個筆記本，請使用 %run <notebook path> magic命令。參考筆記本中定義的所有變數都可以在目前的筆記本中使用。

以下是範例：

%run /<path>/Notebook1 { "parameterInt": 1, "parameterFloat": 2.5, "parameterBool": true, "parameterString": "abc" }

筆記本參考可在互動式模式和管線中運作。

%run magic 命令有下列限制：

命令支援巢狀呼叫，但不支援遞歸呼叫。
此命令僅支援傳遞絕對路徑或筆記本名稱做為參數。它不支持相對路徑。
命令目前僅支援四個參數實值類型： int、 float、 bool和 string。它不支援變數取代作業。
必須發佈參考的筆記本。除非您選取啟用未發佈筆記本參考的選項，否則您必須發佈筆記本來參考它們。 Synapse Studio 無法辨識 Git 存放庫中未發佈的筆記本。
參考的筆記本不支援大於5的語句深度。

使用變數總管

Synapse 筆記本會以表格的形式提供內建變數總管，其中列出 PySpark （Python）單元格目前 Spark 會話中的變數。數據表包含變數名稱、類型、長度和值的數據行。更多變數會在程式代碼數據格中定義時自動顯示。選取每個數據行標頭會排序數據表中的變數。

若要開啟或隱藏變數總管，請選取 筆記本命令行上的 [變數 ] 按鈕。

Synapse 筆記本中變數總管的螢幕快照。

注意

變數總管僅支援 Python。

使用儲存格狀態指示器

單元格執行的逐步狀態會出現在儲存格下方，以協助您查看其目前進度。數據格執行完成之後，總持續時間和結束時間的摘要隨即出現，並留在那裡供日後參考。

Synapse 筆記本中執行單元格摘要的螢幕快照。

使用Spark進度指示器

Synapse Notebook 純粹是以 Spark 為基礎。程式代碼數據格會從遠端在無伺服器 Apache Spark 集區上執行。具有即時進度列的 Spark 作業進度指標可協助您了解作業執行狀態。

每個作業或階段的工作數目可協助您識別 Spark 作業的平行層級。您也可以藉由選取作業 (或階段) 名稱上的連結，更深入鑽研特定工作 (或階段) 的 Spark UI。

Synapse 筆記本中 Spark 進度指示器的螢幕快照。

設定 Spark 工作階段

在 [ 設定工作階段 ] 窗格中，您可以指定逾時持續時間、執行程式數目，以及要提供給目前 Spark 會話的執行程式大小。重新啟動Spark工作階段，讓設定變更生效。所有快取的筆記本變數都會清除。

您也可以從 Apache Spark 設定建立設定，或選取現有的設定。如需詳細資訊，請參閱管理 Apache Spark 設定。

設定 Spark 工作階段的 Magic 命令

您也可以透過magic命令 %%configure指定Spark工作階段設定。若要讓設定生效，請重新啟動Spark工作階段。

建議您在筆記本開頭執行 %%configure 。以下是範例。如需有效參數的完整清單，請參閱 GitHub 上的 Livy 資訊。

%%configure
{
    //You can get a list of valid parameters to configure 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 a standard Spark property. To find more available properties, go to https://spark.apache.org/docs/latest/configuration.html#application-properties.
        "spark.driver.maxResultSize":"10g",
    //Example of a customized property. You can specify the count of lines that Spark SQL returns by configuring "livy.rsc.sql.num-rows".
        "livy.rsc.sql.num-rows":"3000" 
    }
}

以下是magic命令的 %%configure 一些考慮：

建議您在 driverMemory executorMemory 中使用 %%configure與相同的值。我們也建議您使用 driverCores 和 executorCores 具有相同的值。
您可以在 Synapse 管線中使用 %%configure ，但如果未在第一個程式代碼數據格中設定，管線執行將會失敗，因為它無法重新啟動會話。
%%configure中所使用的mssparkutils.notebook.run命令會被忽略，但中使用的%run <notebook>命令會繼續執行。
您必須在主體中使用 "conf" 標準 Spark 組態屬性。我們不支援Spark組態屬性的第一層參考。
某些特殊的 Spark 屬性不會在主體中"conf"生效，包括 "spark.driver.cores"、、"spark.executor.cores""spark.driver.memory"、 "spark.executor.memory"和 "spark.executor.instances"。

來自管線的參數化會話組態

您可以使用參數化會話組態，將magic命令中的 %%configure 值取代為管線執行（Notebook 活動）參數。當您準備程式 %%configure 代碼資料格時，您可以使用如下所示的物件來覆寫預設值：

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

下列範例顯示和"2000"的4預設值，這些預設值也是可設定的：

%%configure  

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

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

在管線執行模式期間，您可以使用 [ 設定 ] 索引標籤來設定管線筆記本活動的設定。

Synapse 筆記本中參數化會話設定的螢幕快照。

如果您想要變更會話組態，管線筆記本活動參數的名稱應該與 activityParameterName 筆記本中的名稱相同。在這裡範例中，在管線執行期間，8會在中%%configure取代 driverCores ，並4000取代 livy.rsc.sql.num-rows。

如果使用magic命令之後 %%configure ，如果管線執行失敗，您可以在筆記本的互動式模式中執行 %%configure magic資料格，以取得更多錯誤資訊。

將資料帶入筆記本

您可以從 Azure Data Lake Storage Gen 2、Azure Blob 儲存體和 SQL 集區載入數據，如下列程式碼範例所示。

從 Azure Data Lake Storage Gen2 讀取 CSV 檔案作為 Spark DataFrame

from pyspark.sql import SparkSession
from pyspark.sql.types import *
account_name = "Your account name"
container_name = "Your container name"
relative_path = "Your path"
adls_path = 'abfss://%s@%s.dfs.core.windows.net/%s' % (container_name, account_name, relative_path)

df1 = spark.read.option('header', 'true') \
                .option('delimiter', ',') \
                .csv(adls_path + '/Testfile.csv')

從 Azure Blob 儲存體讀取 CSV 檔案作為 Spark 數據框架


from pyspark.sql import SparkSession

# Azure storage access info
blob_account_name = 'Your account name' # replace with your blob name
blob_container_name = 'Your container name' # replace with your container name
blob_relative_path = 'Your path' # replace with your relative folder path
linked_service_name = 'Your linked service name' # replace with your linked service name

blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds(linked_service_name)

# Allow Spark to access from Azure Blob Storage remotely

wasb_path = 'wasbs://%s@%s.blob.core.windows.net/%s' % (blob_container_name, blob_account_name, blob_relative_path)

spark.conf.set('fs.azure.sas.%s.%s.blob.core.windows.net' % (blob_container_name, blob_account_name), blob_sas_token)
print('Remote blob path: ' + wasb_path)

df = spark.read.option("header", "true") \
            .option("delimiter","|") \
            .schema(schema) \
            .csv(wasbs_path)

讀取主要儲存體帳戶中的資料

您可以直接存取主要儲存體帳戶中的資料。不需要提供祕密金鑰。在 [數據總管] 中，以滑鼠右鍵按兩下檔案，然後選取 [新增筆記本]，以查看具有自動產生數據擷取器的新筆記本 。

使用 IPython 小工具

小工具是瀏覽器中具有表示法的可事件 Python 物件，通常是像滑桿或文本框這樣的控件。 IPython 小工具只能在 Python 環境中運作。其他語言目前不支持它們（例如 Scala、SQL 或 C#）。

使用 IPython 小工具的步驟

匯入 ipywidgets 模組以使用 Jupyter Widgets 架構：
```
import ipywidgets as widgets
```
使用最上層 display 函式來轉譯小工具，或將型別的 widget 表達式保留在程式碼數據格的最後一行：
```
slider = widgets.IntSlider()
display(slider)
```
```
slider = widgets.IntSlider()
slider
```
執行資料格。小工具會出現在輸出區域。

您可以使用多個 display() 呼叫來轉譯相同的小工具實例多次，但彼此保持同步：

slider = widgets.IntSlider()
display(slider)
display(slider)

Synapse 筆記本中多個 IPython 小工具滑桿的螢幕快照。

若要呈現彼此獨立的兩個 Widget，請建立兩個 Widget 實例：

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

支援的小工具

小工具類型	Widget
數值	`IntSlider`、`FloatSlider`、`FloatLogSlider`、`IntRangeSlider`、`FloatRangeSlider`、`IntProgressFloatProgressBoundedIntText`、、 `BoundedFloatTextIntTextFloatText`
布林值	`ToggleButton`、、 `CheckboxValid`
選取項目	`Dropdown`、`RadioButtons`、、`SelectionSliderSelect`、`SelectionRangeSlider`、、、 `ToggleButtonsSelectMultiple`
String	`Text`、`Text area`、`Combobox`、`Password`、`Label`、`HTML`、`HTML Math`、 `ImageButton`
播放（動畫）	`Date picker`、、 `Color pickerController`
容器/版面配置	`Box`、`HBox`、、`GridBoxVBox`、`Accordion`、、、 `TabsStacked`

已知的限制

下表列出目前不支援的 Widget，以及因應措施：

功能	因應措施
`Output` 小工具	您可以改用函式 `print()` 將文字 `stdout`寫入。
`widgets.jslink()`	您可以使用函 `widgets.link()` 式來連結兩個類似的小工具。
`FileUpload` 小工具	無法使用。

Azure Synapse Analytics 提供的全域 display 函式不支援在一個呼叫中顯示多個小工具（也就是 display(a, b)）。此行為與 IPython display 函式不同。
如果您關閉包含 IPython 小工具的筆記本，則除非再次執行對應的儲存格，否則您無法檢視或與小工具互動。

儲存筆記本

您可以在工作區中儲存單一筆記本或所有筆記本：

若要儲存您對單一筆記本所做的變更，請選取 筆記本命令行上的 [發佈 ] 按鈕。
若要儲存工作區中的所有筆記本，請選取 [工作區] 命令列上的 [全部發佈] 按鈕。

在筆記本的 [屬性 ] 窗格中，您可以設定是否要在儲存時包含數據格輸出。

Synapse 筆記本屬性的螢幕快照，以及儲存時包含儲存格輸出的複選框。

使用 magic 命令

您可以在 Synapse 筆記本中使用熟悉的 Jupyter magic 命令。檢閱下列目前可用的 magic 命令清單。在 GitHub 上告訴我們您的使用案例，讓我們可以繼續建立更多魔術命令以符合您的需求。

注意

Synapse 管線只支援下列 magic 命令：%%pyspark、、%%spark%%csharp、 %%sql。

列可用的 magic 命令：

%lsmagic、、%time%timeit、%history、、%run、%load

適用於儲存格的可用 magic 命令：

%%time、%%timeit、%%capture、%%writefile、%%sql、%%pyspark、%%spark、、%%csharp、、 %%html%%configure

參考未發佈的筆記本

當您想要在本機偵錯時，參考未發佈的筆記本會很有説明。當您啟用此功能時，筆記本執行會擷取 Web 快取中的目前內容。如果您執行包含參考筆記本語句的儲存格，則會參考目前筆記本瀏覽器中呈現的筆記本，而不是叢集中的已儲存版本。其他筆記本可以參考筆記本編輯器中的變更，而不需要您發佈（Live mode）或認可（Git 模式）變更。藉由使用此方法，您可以在開發或偵錯程式期間防止常見連結庫的污染。

您可以選取 [屬性] 窗格上的適當複選框，以啟用參考未發佈的筆記本。

啟用參考未發佈 Synapse 筆記本之複選框的螢幕快照。

下表比較案例。雖然 %run 和 mssparkutils.notebook.run 在這裏的行為相同，但數據表會使用 %run 做為範例。

大小寫	停用	啟用
即時模式
Nb1（已發佈） `%run Nb1`	執行 Nb1 的已發佈版本	執行 Nb1 的已發佈版本
Nb1 （新） `%run Nb1`	錯誤	執行新的 Nb1
Nb1 （先前出版，編輯） `%run Nb1`	執行 Nb1 的已發佈版本	執行 Nb1 的已編輯版本
Git 模式
Nb1（已發佈） `%run Nb1`	執行 Nb1 的已發佈版本	執行 Nb1 的已發佈版本
Nb1 （新） `%run Nb1`	錯誤	執行新的 Nb1
Nb1 （未出版，認可） `%run Nb1`	錯誤	執行已認可的 Nb1
Nb1 （先前出版，已認可） `%run Nb1`	執行 Nb1 的已發佈版本	執行 Nb1 的已認可版本
Nb1 （先前出版，最新分支的新功能） `%run Nb1`	執行 Nb1 的已發佈版本	執行新的 Nb1
Nb1 （未出版，先前認可，編輯） `%run Nb1`	錯誤	執行 Nb1 的已編輯版本
Nb1 （先前出版並認可，編輯） `%run Nb1`	執行 Nb1 的已發佈版本	執行 Nb1 的已編輯版本

摘要中：

如果您停用參考未發佈的筆記本，請一律執行 已發佈 的版本。
如果您啟用參考未發佈的筆記本，參考執行一律會採用筆記本 UX 上出現的目前筆記本版本。

管理使用中的會話

您可以重複使用筆記本會話，而不需要啟動新的會話。在 Synapse 筆記本中，您可以在單一清單中管理作用中的會話。若要開啟清單，請選取省略號（...），然後選取 [ 管理會話]。

開啟使用中 Synapse 筆記本會話清單之選取項目的螢幕快照。

[ 作用中會話] 窗格會列出您從筆記本啟動之目前工作區中的所有會話。此清單會顯示會話資訊和對應的筆記本。您可以 在這裡使用筆記本中斷連結、 停止工作階段和 檢視監視 動作。此外，您可以將選取的筆記本連線至從另一個筆記本啟動的作用中會話。然後會話會與上一個筆記本中斷連結（如果它未閑置），並附加至目前的筆記本。

Synapse 工作區中作用中會話窗格的螢幕快照。

在筆記本中使用 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 the 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 uses 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 uses 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")

檢視輸入命令的歷程記錄

Synapse 筆記本支援 magic 命令 %history ，以列印目前會話的輸入命令歷程記錄。 %history magic 命令類似於標準 Jupyter IPython 命令，適用於筆記本中的多種語言內容。

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

在上述程式代碼中， -n 是列印執行編號。此值 range 可以是：

N：列印執行之儲存格的程式 Nth 代碼。
M-N：將程式代碼從 Mth 列印到 Nth 執行的數據格。

例如，若要將輸入歷程記錄從第一個列印到第二個執行的數據格，請使用 %history -n 1-2。

整合筆記本

將筆記本新增至管線

若要將筆記本新增至現有的管線或建立新的管線，請選取 右上角的 [新增至管線 ] 按鈕。

將筆記本新增至現有或新 Synapse 管線之功能表選項的螢幕快照。

指定參數儲存格

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

將儲存格指定為參數儲存格之功能表選項的螢幕快照。

Azure Data Factory 會尋找參數數據格，並將此數據格視為運行時間傳入之參數的預設值。執行引擎會在參數數據格底下新增一個新儲存格，其中包含輸入參數，以覆寫預設值。

從管線指派參數值

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

Azure Synapse Analytics 中指派參數的區域螢幕快照。

當您指派參數值時，可以使用管線表達式語言或系統變數。

使用快速鍵

與 Jupyter 筆記本類似，Synapse 筆記本也有強制回應使用者介面。鍵盤會根據筆記本儲存格所在的模式執行不同的動作。 Synapse Notebook 支援下列兩種程式代碼數據格模式：

命令模式：當沒有文字游標提示您輸入時，單元格會處於命令模式。當儲存格處於命令模式時，您可以以整體方式編輯筆記本，但不能輸入個別儲存格。選取 Esc 鍵或使用滑鼠在儲存格的編輯器區域外選取，以進入命令模式。
編輯模式：當儲存格處於編輯模式時，文字游標會提示您輸入儲存格。選取 Enter 鍵或使用滑鼠選取儲存格的編輯器區域，以進入編輯模式。

命令模式中的快速鍵

動作	Synapse 筆記本快捷方式
執行目前的儲存格並在下方選取	Shift+Enter
執行目前的儲存格並在下方插入	Alt+Enter
執行目前的儲存格	Ctrl+Enter
選取上方儲存格	Up
選取下方儲存格	向下
選取上一個儲存格	K
選取下一個儲存格	J
在上方插入儲存格	A
在下方插入儲存格	B
刪除選取的儲存格	Shift + D
切換到編輯器模式	Enter

編輯模式中的快速鍵

動作	Synapse 筆記本快捷方式
向上移動資料指標	Up
向下移動資料指標	向下
復原	Ctrl+Z
取消復原	Ctrl+Y
註解/取消註解	Ctrl+/
刪除此前的文字	Ctrl+退格鍵
刪除此後的文字	Ctrl+Delete
移至儲存格開端	Ctrl+Home
移至儲存格末端	Ctrl+End
往左移一個單字	Ctrl+Left
往右移一個單字	Ctrl+Right
全選	Ctrl+A
Indent	Ctrl+]
Dedent	Ctrl+[
切換到命令類型	Esc

共用方式為