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

適用於：Azure Data Factory Azure Synapse Analytics

提示

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

管線中的 Azure Synapse 筆記本活動會在您的 Azure Synapse Analytics 工作區中執行 Synapse 筆記本。本文是以資料轉換活動一文為基礎，該文提供了資料轉換和系統支援的轉換活動的一般概覽。

您可以直接透過 Azure Data Factory Studio 使用者介面建立 Azure Synapse Analytics 筆記本活動。如需如何使用使用者介面建立 Synapse 筆記本活動的逐步解說，您可以參考下列內容。

使用 UI 將 Synapse 的「筆記本」活動新增至管線

若要在管線中使用 Synapse 的筆記本活動，請依照以下步驟完成：

一般設定

在管線「活動」窗格中搜尋筆記本，然後將 Synapse 底下的「筆記本」活動拖曳到管線畫布上。
如果尚未選取，請在畫布上選取新的 Notebook 活動項目。
在 [一般] 設定中，輸入 [名稱] 的範例。
(選項) 您也可以輸入描述。
逾時：活動可執行的最長時間。預設值為 12 小時，而允許的時間上限為 7 天。格式是 D.HH:MM:SS (日期.小時：分鐘：秒)。
重試嘗試：重新嘗試次數的上限。
重試間隔 (秒)：每次重新嘗試間隔的秒數。
安全輸出：核取時，活動輸出不會擷取至記錄。
安全輸入：核取時，活動輸入不會擷取至記錄。

Azure Synapse Analytics (Artifacts) 設定

選取 [Azure Synapse Analytics (Artifacts)] 索引標籤，以選取或建立新的 Azure Synapse Analytics 連結服務，該服務將會執行筆記本活動。

[設定] 索引標籤

如果畫布上的新 Synapse 筆記本活動尚未選取，請選取它。
選取 [設定] 索引標籤。
展開 [筆記本] 清單，您可以在連結的 Azure Synapse Analytics (Artifacts) 中選取現有的筆記本。
按一下 [開啟] 按鈕，開啟所選取筆記本所在連結服務的頁面。

注意

如果連結服務中的工作區資源識別碼是空的，則會停用 [開啟] 按鈕。

選取 [設定] 索引標籤，然後選擇筆記本，以及要傳遞至筆記本的選擇性基底參數。

(選擇性) 您可以填入 Synapse 筆記本的資訊。如果下列設定是空的，則 Synapse 筆記本本身的設定會用於執行；如果下列設定不是空的，這些設定將會取代 Synapse 筆記本本身的設定。

屬性	說明
Spark 池	Spark 集區的參考。您可以從清單中選取 Apache Spark 集區。
執行程式大小	工作階段中，在指定 Apache Spark 集區中，配置給執行程式的核心數與記憶體大小。對於動態內容，有效值為 Small/Medium/Large/XLarge/XXLarge。
動態配置執行程式	此設定會對應到 Spark 設定中的動態分配屬性，以進行 Spark 應用程式執行元分配。
執行程式數目下限	要在針對工作所指定 Spark 集區中配置的執行程式數目下限。
執行程式數目上限	要在針對工作所指定 Spark 集區中配置的執行程式數目上限。
驅動程式大小	在作業中，於指定 Apache Spark 集區中提供給驅動程式的核心數與記憶體大小。

Azure Synapse Analytics 筆記本活動定義

以下是 Azure Synapse Analytics 筆記本活動的範例 JSON 定義：

{
    "activities": [
            {
                "name": "demo",
                "description": "description",
                "type": "SynapseNotebook",
                "dependsOn": [],
                "policy": {
                    "timeout": "7.00:00:00",
                    "retry": 0,
                    "retryIntervalInSeconds": 30,
                    "secureOutput": false,
                    "secureInput": false
                },
                "userProperties": [
                    {
                        "name": "testproperties",
                        "value": "test123"
                    }
                ],
                "typeProperties": {
                    "notebook": {
                        "referenceName": {
                            "value": "Notebookname",
                            "type": "Expression"
                        },
                        "type": "NotebookReference"
                    },
                    "parameters": {
                        "test": {
                            "value": "testvalue",
                            "type": "string"
                        }
                    },
                    "snapshot": true,
                    "sparkPool": {
                        "referenceName": {
                            "value": "SampleSpark",
                            "type": "Expression"
                        },
                        "type": "BigDataPoolReference"
                    }
                },
                "linkedServiceName": {
                    "referenceName": "AzureSynapseArtifacts1",
                    "type": "LinkedServiceReference"
                }
            }
        ]
    }

Azure Synapse Analytics 筆記本活動屬性

下表說明 JSON 定義中使用的 JSON 屬性：

屬性	說明	必要
名稱	管線中的活動名稱。	Yes
說明	說明活動用途的文字。	No
型別	對於 Azure Synapse Analytics Notebook Activity，活動類型是 SynapseNotebook。	Yes
筆記本	要在 Azure Synapse Analytics 中執行的筆記本名稱。	Yes
sparkPool	執行 Azure Synapse Analytics Notebook 所需的 Spark 集區。	No
參數	執行 Azure Synapse Analytics Notebook 所需的參數。如需詳細資訊，請參閱藉由執行 Synapse 筆記本來轉換資料	No

指定參數儲存格

Azure Data Factory 會尋找參數資料格，並使用這些值做為在執行時間所傳入參數的預設值。執行引擎會在參數資料格下方新增一個包含輸入參數的資料格，以覆寫預設值。您可以參考使用 Synapse 筆記本進行資料轉換。

讀取 Synapse 筆記本單元格輸出值

您可以在活動中讀取 Notebook 儲存格輸出值，關於此面板，請參閱藉由執行 Synapse 筆記本轉換資料。

執行另一個 Synapse 筆記本

您可以在 Synapse Notebook 活動中，藉由呼叫 %run magic 或 mssparkutils notebook utilities 來參考其他 Notebook。兩者都支援巢狀函式呼叫。根據您的案例，這兩種方法您應該考慮的主要差異如下：

%run magic 會將參考筆記本中的所有資料格複製至 %run 資料格，並共用變數內容。若 notebook1 透過 %run notebook2 參考 notebook2，且 notebook2 呼叫 mssparkutils.notebook.exit 函式，則系統會停止在 notebook1 中執行資料格。當您想要「包含」筆記本檔案時，建議您使用 %run magic。
mssparkutils notebook utilities 會將參考的 Notebook 當作方法或函式來呼叫。系統不會共用變數內容。若 notebook1 透過 mssparkutils.notebook.run("notebook2") 參考 notebook2，且 notebook2 呼叫 mssparkutils.notebook.exit 函式，則系統會繼續在 notebook1 中執行資料格。若要「匯入」筆記本，建議您使用 mssparkutils 筆記本公用程式。

請參閱 Azure Synapse Analytics 筆記本活動執行歷程記錄

前往監視器索引標籤底下的「管線執行」，您將看到已觸發的管線。開啟包含 notebook 活動的 pipeline，以查看執行歷程記錄。

至於 Open notebook snapshot，目前尚不支援此功能。

您可以藉由選取 [輸入] 或 [輸出] 按鈕，查看筆記本活動輸入或輸出。若管線因使用者錯誤而失敗，請選取 [輸出] 來檢查 [結果] 欄位，以查看詳細的使用者錯誤追溯。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-03-30