透過使用 Azure Data Factory 或 Synapse Analytics 中的 Script 活動來轉換資料

適用於： Azure Data Factory Azure Synapse Analytics

秘訣

Data Factory in Microsoft Fabric 是下一代的 Azure Data Factory，擁有更簡單的架構、內建 AI 及新功能。如果你是資料整合新手，建議先從 Fabric Data Factory 開始。現有的 ADF 工作負載可升級至 Fabric，以存取資料科學、即時分析與報告等新能力。

秘訣

關於 Microsoft Fabric 中 Data Factory 中的等效活動，請參見腳本活動。

您在 Data Factory 或 Synapse 管線中使用資料轉換活動，以轉換並處理您的未經處理資料，來進行預測和深入解析。指令碼活動是管線支援的其中一個轉換活動。本文是以轉換資料一文為基礎，提供資料轉換及所支援轉換活動的一般概觀。

您可以使用指令碼活動，透過資料操作語言 (DML) 和資料定義語言 (DDL) 來執行一般作業。 INSERT、UPDATE、DELETE 和 SELECT 等 DML 陳述式，可讓使用者在資料庫中插入、修改、刪除和擷取資料。 CREATE、ALTER 和 DROP 等 DDL 陳述式可讓資料庫管理員建立、修改和移除資料庫物件，例如資料表、索引和使用者。

您可以使用腳本活動，在您的企業內或 Azure 虛擬機（VM）中，呼叫以下資料儲存中的 SQL 腳本：

適用於 PostgreSQL 的 Azure 資料庫（Version 2.0）
Azure SQL Database
Azure Synapse Analytics
SQL Server 資料庫。如果你用的是 SQL Server，請在同一台主機上安裝自架整合執行時，或是在有資料庫存取權的另一台電腦上安裝。 Self-Hosted 整合執行時是一個元件，能以安全且受管理的方式，將本地/Azure虛擬機上的資料來源與雲端服務連結起來。如需詳細資料，請參閱自我裝載整合執行階段一文。
Oracle
Snowflake

指令碼可包含循序執行的單一 SQL 陳述式或多個 SQL 陳述式。您可將指令碼工作用於下列用途：

截斷資料表，為插入資料做準備。
建立、改變和卸除資料庫物件，例如資料表和檢視。
將資料載入至事實 (Fact) 和維度 (Dimension) 資料表之前，先重建這些資料表。
執行預存程序。如果 SQL 陳述式叫用會從暫存資料表傳回結果的預存程序，請使用 WITH RESULT SETS 選項來定義結果集的中繼資料。
將從查詢傳回的資料列集儲存為下游取用的活動輸出。

語法詳細資料

以下是定義文稿活動的 JSON 格式：

{ 
   "name": "<activity name>", 
   "type": "Script", 
   "linkedServiceName": { 
      "referenceName": "<name>", 
      "type": "LinkedServiceReference" 
    }, 
   "typeProperties": { 
      "scripts" : [ 
         { 
            "text": "<Script Block>", 
            "type": "<Query> or <NonQuery>", 
            "parameters":[ 
               { 
                  "name": "<name>", 
                  "value": "<value>", 
                  "type": "<type>", 
                  "direction": "<Input> or <Output> or <InputOutput>", 
                  "size": 256 
               }, 
               ... 
            ] 
         }, 
         ... 
      ],     
         ... 
         ] 
      }, 
      "scriptBlockExecutionTimeout": "<time>",  
      "logSettings": { 
         "logDestination": "<ActivityOutput> or <ExternalStore>", 
         "logLocationSettings":{ 
            "linkedServiceName":{ 
               "referenceName": "<name>", 
               "type": "<LinkedServiceReference>" 
            }, 
            "path": "<folder path>" 
         } 
      } 
    } 
}

下表說明這些 JSON 屬性：

屬性名稱	描述	必要
NAME	活動的名稱。	是
型別	活動的類型，設定為 "Script"。	是
typeProperties	指定要設定 Script Activity 的屬性。	是
linkedServiceName	指令碼執行的目標資料庫。其應該是連結服務的參考。	是
指令碼	物件的陣列，表示指令碼。	否
scripts.text	查詢區塊的純文字。	否
scripts.type	查詢區塊的類型。其可以是 Query 或 NonQuery。預設：查詢。	否
scripts.parameter	指令碼的參數陣列。	否
scripts.parameter.name	參數名稱。	否
scripts.parameter.value	參數的值。	否
scripts.parameter.type	參數的資料類型。這個類型為邏輯類型，並遵循每個連接器的類型對應。	否
scripts.parameter.direction	參數的方向。其可以是 Input、Output、InputOutput。如果方向為 Output，則會忽略此值。不支援 ReturnValue 類型。將 SP 的傳回值設定為輸出參數來加以擷取。	否
scripts.parameter.size	參數的大小上限。僅適用於 string/byte[] 類型的 Output/InputOutput 方向參數。	否
scriptBlockExecutionTimeout	在逾時之前等候指令碼區塊執行作業完成的時間。	否
logSettings	用來儲存輸出記錄的設定。如果未指定，則會停用指令碼記錄。	否
logSettings.logDestination	記錄輸出的目的地。其可以是 ActivityOutput 或 ExternalStore。預設值：ActivityOutput。	否
logSettings.logLocationSettings	如果 logDestination 是 ExternalStore，則為目標位置的設定。	否
logSettings.logLocationSettings.linkedServiceName	目標位置的連結服務。僅支援 Blob 儲存體。	否
logSettings.logLocationSettings.path	用來儲存記錄的資料夾路徑。	否

活動輸出

範例輸出：

{ 
    "resultSetCount": 2, 
    "resultSets": [ 
        { 
            "rowCount": 10, 
            "rows":[ 
                { 
                    "<columnName1>": "<value1>", 
                    "<columnName2>": "<value2>", 
                    ... 
                } 
            ] 
        }, 
        ... 
    ], 
    "recordsAffected": 123, 
    "outputParameters":{ 
        "<parameterName1>": "<value1>", 
        "<parameterName2>": "<value2>" 
    }, 
    "outputLogs": "<logs>", 
    "outputLogsLocation": "<folder path>", 
    "outputTruncated": true, 
    ... 
}

屬性名稱	描述	條件
resultSetCount	指令碼所傳回的結果集計數。	一律
resultSets	包含所有結果集的陣列。	一律
resultSets.rowCount	結果集中的資料列總計。	一律
resultSets.rows	結果集中的資料列陣列。	一律
recordsAffected	資料列所影響資料列的資料列計數。	如果 scriptType 為 NonQuery
outputParameters	指令碼的輸出參數。	如果參數類型為 Output 或 InputOutput。
outputLogs	指令碼所撰寫的記錄，例如 print 陳述式。	如果連接器支援 log 陳述式，enableScriptLogs 為 true，且未提供 logLocationSettings。
outputLogsPath	記錄檔的完整路徑。	如果 enableScriptLogs 為 true，則會提供 logLocationSettings。
outputTruncated	輸出是否超過限制並遭截斷的指標。	如果輸出超過限制。

附註

每次執行指令碼區塊時，都會收集輸出。最後一個輸出是所有指令碼區塊輸出的合併結果。在不同指令碼區塊中具有相同名稱的輸出參數將會受到覆寫。
由於輸出具有大小/資料列限制，因此會依下列順序截斷輸出：logs -> parameters -> rows。這適用於單一腳本區塊，這表示下一個腳本區塊的輸出數據列不會收回先前的記錄。
記錄所造成的任何錯誤都不會使活動失敗。
如需在下游活動中取用活動輸出 resultSet，請參閱查閱活動結果文件。
當您使用 'PRINT' 陳述式進行記錄時，請使用 outputLogs。如果查詢傳回 resultSets，則會在活動輸出中使用，且會限制為 5000 個資料列/4MB 大小限制。

使用 UI 設定 Script 活動

內嵌指令碼

此螢幕擷取畫面顯示用來設定內嵌指令碼的 UI。

內嵌指令碼與管線 CI/CD 整合良好，因為指令碼會儲存為管線中繼資料的一部分。

秘訣

當你在 Script 活動中定義參數時，必須明確引用查詢文本中的每個參數，才能在執行時傳遞。

例如：

{
  "type": "Script",
  "typeProperties": {
    "scripts": [
      {
        "type": "Query",
        "text": "EXEC dbo.my_procedure @param1 = @param1",
        "parameters": [
          {
            "name": "param1",
            "type": "String",
            "value": {
              "value": "@pipeline().parameters.myValue",
              "type": "Expression"
            },
            "direction": "Input"
          }
        ]
      }
    ]
  }
}

記錄

此螢幕擷取畫面顯示指令碼記錄設定的 UI。

記錄選項：

停用 – 不會記錄執行輸出。
活動輸出 - 指令碼執行輸出會附加至活動輸出。下游活動後續可加以取用。輸出大小限制為 4 MB。
外部儲存體 - 將輸出保存到儲存體。如果輸出大小大於 2 MB，或者您想要在儲存體帳戶上明確保存輸出，請使用此選項。

附註

帳單 - Script 活動會以管線活動來計費。

請參閱下列文章，其說明如何以其他方式轉換資料：

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-05