使用 Azure Data Factory 或 Synapse Analytics 中的指令碼活動來轉換資料

適用於：Azure Data Factory Azure Synapse Analytics

提示

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

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

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

您可以使用「指令碼活動」來叫用您企業或 Azure 虛擬機器 (VM) 中，在下列其中一個資料存放區中的 SQL 指令碼：

• Azure SQL Database
• Azure Synapse Analytics
• SQL Server Database。 如果您使用 SQL Server，請在裝載資料庫的同一部電腦上或可存取資料庫的個別電腦上安裝自我裝載整合執行階段。 自我裝載整合執行階段是一套透過安全且可管理的方式，將內部部署/Azure VM 上的資料來源連結至雲端服務的元件。 如需詳細資料，請參閱自我裝載整合執行階段一文。
• 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	活動的名稱。	Yes
type	將 activity 的 type 設定為「Script」。	Yes
typeProperties	指定要設定 Script Activity 的屬性。	Yes
linkedServiceName	指令碼執行的目標資料庫。 其應該是連結服務的參考。	Yes
指令碼	物件的陣列，表示指令碼。	No
scripts.text	查詢區塊的純文字。	No
scripts.type	查詢區塊的類型。 其可以是 Query 或 NonQuery。 預設：查詢。	No
scripts.parameter	指令碼的參數陣列。	No
scripts.parameter.name	參數名稱。	No
scripts.parameter.value	參數的值。	No
scripts.parameter.type	參數的資料類型。 這個類型為邏輯類型，並遵循每個連接器的類型對應。	No
scripts.parameter.direction	參數的方向。 其可以是 Input、Output、InputOutput。 如果方向為 Output，則會忽略此值。 不支援 ReturnValue 類型。 將 SP 的傳回值設定為輸出參數來加以擷取。	No
scripts.parameter.size	參數的大小上限。 僅適用於 string/byte[] 類型的 Output/InputOutput 方向參數。	No
scriptBlockExecutionTimeout	在逾時之前等候指令碼區塊執行作業完成的時間。	No
logSettings	用來儲存輸出記錄的設定。 如果未指定，則會停用指令碼記錄。	No
logSettings.logDestination	記錄輸出的目的地。 其可以是 ActivityOutput 或 ExternalStore。 預設值：ActivityOutput。	No
logSettings.logLocationSettings	如果 logDestination 是 ExternalStore，則為目標位置的設定。	No
logSettiongs.logLocationSettings.linkedServiceName	目標位置的連結服務。 僅支援 Blob 儲存體。	No
logSettings.logLocationSettings.path	將儲存記錄的資料夾路徑。	No

活動輸出

範例輸出：

{ 
    "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 活動

內嵌指令碼

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

記錄

記錄選項：

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

注意

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

相關內容

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

• U-SQL 活動
• Hive 活動
• Pig 活動
• MapReduce 活動
• Hadoop 串流活動
• Spark 活動
• .NET 自訂活動
• 預存程序活動