藉由執行 Synapse 筆記本來轉換資料
適用於:Azure Data Factory Azure Synapse Analytics
提示
試用 Microsoft Fabric 中的 Data Factory,這是適用于企業的單一分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告等所有專案。 瞭解如何 免費開始新的試用版 !
Synapse 管線中的 Azure Synapse 筆記本活動會在您的 Azure Synapse 工作區中,執行 Synapse 筆記本。 本文是根據 資料轉換活動 一文,它呈現資料轉換和支援的轉換活動的一般概觀。
建立 Synapse 筆記本活動
您可以直接從 Synapse 管線畫布或筆記本編輯器建立 Synapse 筆記本活動。 Synapse 筆記本活動會在 Synapse 筆記本中選擇的 Spark 集區上執行。
從管線畫布新增 Synapse 筆記本活動
將 [活動] 下的 [Synapse 筆記本] 拖放至 Synapse 管線畫布上。 選取 [Synapse 筆記本活動] 方塊,並在 [設定] 中設定目前活動的筆記本內容。 您可以從目前的工作區選取現有的筆記本,或新增一個筆記本。
如果您從目前的工作區中選取現有的筆記本,您可以按一下 [開啟] 按鈕,直接開啟筆記本的頁面。
(選擇性) 您也可以在設定中重新設定 Spark 集區\執行程式大小\動態配置執行程式\最小執行程式\最大執行程式\驅動程式大小。 請注意,此處重新設定的設定將會取代 Notebook 中設定工作階段的設定。 如果目前筆記本活動的設定中未設定任何項目,則會使用該筆記本中設定工作階段的設定來執行。
屬性 | Description | 必要 |
---|---|---|
Spark 集區 | Spark 集區的參考。 您可以從清單中選取 Apache Spark 集區。 如果此設定是空的,會在筆記本本身的 Spark 集區中執行。 | No |
執行程式大小 | 配置在工作階段之指定 Apache Spark 集區中的執行程式所要使用的核心與記憶體數目。 | No |
動態配置執行程式 | 此設定會對應到 Spark 設定中的動態配置屬性,以進行 Spark 應用程式執行程式配置。 | No |
執行程式數目下限 | 要在針對工作所指定 Spark 集區中配置的執行程式數目下限。 | No |
執行程式數目上限 | 要在針對工作所指定 Spark 集區中配置的執行程式數目上限。 | No |
驅動程式大小 | 在指定 Apache Spark 集區中提供給作業使用的驅動程式所能使用的核心和記憶體數目。 | No |
注意
在 Azure Synapse 管線中執行平行 Spark 筆記本時,會以 FIFO 方式排入佇列並執行,佇列中的工作順序是根據時間序列,在佇列中工作的到期時間為 3 天,請注意,筆記本的佇列僅適用於 Synapse 管線。
將筆記本新增至 Synapse 管線
選取右上角的 [新增至管線] 按鈕,將筆記本新增至現有的管線或建立新的管線。
傳遞參數
指定參數資料格
若要將筆記本參數化,請選取省略符號 (...),以存取儲存格工具列上的更多命令。 然後選取 [切換參數儲存格],將儲存格指定為參數儲存格。
Azure Data Factory 會尋找參數資料格,並使用這些值做為在執行時間所傳入參數的預設值。 執行引擎會在參數資料格下方加入新的資料格,其中包含可覆寫預設值的輸入參數。
從管線指派參數值
建立具有參數的筆記本之後,您可以從具有 Synapse 筆記本活動的管線執行它。 將活動新增至管線畫布之後,即可在 [設定] 索引標籤的 [基底參數] 區段下設定參數值。
讀取 Synapse 筆記本資料格輸出值
您可以遵循下列步驟,讀取下一個活動中的筆記本資料格輸出值:
在您的 Synapse 筆記本活動中呼叫 mssparkutils.notebook.exit API,以傳回想要在活動輸出中顯示的值,例如:
mssparkutils.notebook.exit("hello world")
儲存筆記本內容和重新觸發管線時,筆記本活動輸出會包含可在下列步驟 2 活動中取用的 exitValue。
從筆記本活動輸出讀取 exitValue 屬性。 以下的範例運算式可用來檢查從筆記本活動輸出提取的 exitValue 是否等於 "hello world":
執行另一個 Synapse 筆記本
您可以透過呼叫 %run magic 或 mssparkutils 筆記本公用程式,在 Synapse 筆記本活動中參考其他筆記本。 兩者都支援巢狀函式呼叫。 根據您的案例,這兩種方法您應該考慮的主要差異如下:
-
%run magic 會將參考筆記本中的所有資料格複製至 %run 資料格,並共用變數內容。 若 notebook1 透過
%run notebook2
參考 notebook2,且 notebook2 呼叫 mssparkutils.notebook.exit 函式,則系統會停止在 notebook1 中執行資料格。 當您想要「包含」筆記本檔案時,建議您使用 %run magic。 -
mssparkutils 筆記本公用程式會呼叫參考的筆記本做為方法或函式。 系統不會共用變數內容。 若 notebook1 透過
mssparkutils.notebook.run("notebook2")
參考 notebook2,且 notebook2 呼叫 mssparkutils.notebook.exit 函式,則系統會繼續在 notebook1 中執行資料格。 若要「匯入」筆記本,建議您使用 mssparkutils 筆記本公用程式。
查看筆記本活動執行歷程記錄
移至 [監視] 索引標籤下的 [管線執行],您會看到已觸發的管線。 開啟包含筆記本活動的管線,以查看執行歷程記錄。
您可以選取 [開啟筆記本] 按鈕,以查看最新的筆記本執行快照集,包括資料格輸入和輸出。
開啟筆記本快照集:
您可以藉由選取 [輸入] 或 [輸出] 按鈕,查看筆記本活動輸入或輸出。 若管線因使用者錯誤而失敗,請選取 [輸出] 來檢查 [結果] 欄位,以查看詳細的使用者錯誤追溯。
Synapse 筆記本活動定義
以下是 Synapse 筆記本活動的 JSON 定義範例:
{
"name": "parameter_test",
"type": "SynapseNotebook",
"dependsOn": [],
"policy": {
"timeout": "7.00:00:00",
"retry": 0,
"retryIntervalInSeconds": 30,
"secureOutput": false,
"secureInput": false
},
"userProperties": [],
"typeProperties": {
"notebook": {
"referenceName": "parameter_test",
"type": "NotebookReference"
},
"parameters": {
"input": {
"value": {
"value": "@pipeline().parameters.input",
"type": "Expression"
}
}
}
}
}
Synapse 筆記本活動輸出
以下是 Synapse 筆記本活動輸出的 JSON 範例:
{
{
"status": {
"Status": 1,
"Output": {
"status": <livySessionInfo>
},
"result": {
"runId": "<GUID>",
"runStatus": "Succeed",
"message": "Notebook execution is in Succeeded state",
"lastCheckedOn": "2021-03-23T00:40:10.6033333Z",
"errors": {
"ename": "",
"evalue": ""
},
"sessionId": 4,
"sparkpool": "sparkpool",
"snapshotUrl": "https://myworkspace.dev.azuresynapse.net/notebooksnapshot/{guid}",
"exitCode": "abc" // return value from user notebook via mssparkutils.notebook.exit("abc")
}
},
"Error": null,
"ExecutionDetails": {}
},
"effectiveIntegrationRuntime": "DefaultIntegrationRuntime (West US 2)",
"executionDuration": 234,
"durationInQueue": {
"integrationRuntimeQueue": 0
},
"billingReference": {
"activityType": "ExternalActivity",
"billableDuration": [
{
"meterType": "AzureIR",
"duration": 0.06666666666666667,
"unit": "Hours"
}
]
}
}
已知問題
如果 Notebook 名稱在管線筆記本活動中已參數化,則偵錯執行中無法參考處於未發佈狀態的筆記本版本。