藉由執行 Synapse 筆記本來轉換資料

發行項
07/27/2023

適用於：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 名稱在管線筆記本活動中已參數化，則偵錯執行中無法參考處於未發佈狀態的筆記本版本。

共用方式為