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

發行項
11/05/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。了解如何免費開始新的試用 (部分機器翻譯)！

Synapse 管線中的 Azure Synapse Notebook 活動會執行 Synapse 筆記本。本文是根據資料轉換活動一文，它呈現資料轉換和支援的轉換活動的一般概觀。

建立 Synapse 筆記本活動

您可以直接從 Synapse 管線畫布或筆記本編輯器建立 Synapse 筆記本活動。 Synapse Notebook 活動會在在 Synapse 筆記本中選擇的 Spark 集區上執行。

從管線畫布新增 Synapse Notebook 活動

將 [活動] 底下的 Synapse 筆記本拖放到 Synapse 管線畫布上。在 [Synapse 筆記本活動] 方塊上選取，並在設定中設定目前活動的筆記本內容。您可以從目前的工作區選取現有的筆記本，或新增筆記本。

如果您從目前的工作區選取現有的筆記本，您可以按下 [開啟 ] 按鈕，直接開啟筆記本的頁面。

（選擇性）您也可以在設定中重新設定 Spark 集區\Executor 大小\動態配置執行程式\Min executors\Max executors\Driver 大小。請注意，此處重新設定的設定將會取代 Notebook 中設定工作階段的設定。如果目前筆記本活動的設定中未設定任何專案，則會使用該筆記本中設定會話的設定來執行。

螢幕快照-顯示-create-notebook-activity

屬性	描述	必要
Spark 集區	Spark 集區的參考。您可以從清單中選取 Apache Spark 集區。如果此設定是空的，它會在筆記本本身的Spark集區中執行。	No
執行程式大小	配置在工作階段之指定 Apache Spark 集區中的執行程式所要使用的核心與記憶體數目。	No
動態配置執行程式	此設定會對應到 Spark 設定中的動態配置屬性，以進行 Spark 應用程式執行程式配置。	No
執行程式數目下限	要在針對工作所指定 Spark 集區中配置的執行程式數目下限。	No
執行程式數目上限	要在針對工作所指定 Spark 集區中配置的執行程式數目上限。	No
驅動程式大小	在指定 Apache Spark 集區中提供給作業使用的驅動程式所能使用的核心和記憶體數目。	No

注意

Azure Synapse 管線中平行 Spark Notebook 的執行會以 FIFO 方式排入佇列並執行，佇列中的作業順序是根據時間順序，佇列中作業的到期時間為 3 天，請注意，筆記本的佇列只能在 synapse 管線中工作。

將筆記本新增至 Synapse 管線

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

顯示-add-notebook-to-pipeline 的螢幕快照

傳遞參數

指定參數儲存格

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

在此數據格中定義您的參數。它可能很簡單：

a = 1
b = 3
c = "Default Value"

您可以在其他數據格中參考這些參數，以及當您執行筆記本以使用您在parameters資料格中指定的預設值時。

當您從管線執行此筆記本時，Azure Data Factory 會尋找參數數據格，並使用您在運行時間傳入的參數預設值。如果您從管線指派參數值，執行引擎會在具有輸入參數的參數數據格底下新增數據格，以覆寫預設值。

從管線指派參數值

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

提示

Data Factory 不會自動填入參數。您必須手動新增。請務必在筆記本中的 parameters 單元格和管線中的基底參數中使用完全相同的名稱。

將參數新增至活動之後，Data Factory 會將您在活動中指定的值傳遞至筆記本，而您的筆記本將會使用這些新的參數值執行，而不是您在參數數據格中指定的預設值。

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

讀取 Synapse 筆記本資料格輸出值

您可以遵循下列步驟，在後續活動中讀取筆記本資料格輸出值：

在 Synapse Notebook 活動中呼叫 mssparkutils.notebook.exit API，以傳回您想要在活動輸出中顯示的值，例如：
```
mssparkutils.notebook.exit("hello world") 
```
儲存筆記本內容並重試管線，Notebook 活動輸出將包含 exitValue，可在步驟 2 中針對下列活動取用。
從 Notebook 活動輸出讀取 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 Notebook 活動定義

以下是 Synapse Notebook 活動的範例 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 Notebook 活動輸出

以下是 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"
            }
        ]
    }
}

已知問題

如果筆記本名稱在管線筆記本活動中被參數化，則偵錯執行中無法參考處於未發佈狀態的筆記本版本。

共用方式為