在 Azure Data Factory 或 Synapse Analytics 中使用腳本活動轉換數據

發行項
01/23/2024

適用於： Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的單一分析解決方案。 Microsoft Fabric 涵蓋從數據移動到數據科學、即時分析、商業智慧和報告等所有專案。瞭解如何免費啟動新的試用版！

您可以使用 Data Factory 或 Synapse 管線中的數據轉換活動，將原始數據轉換成預測和深入解析。腳本活動是管線支援的其中一個轉換活動。本文以轉換數據一文為基礎，提供數據轉換和支援的轉換活動的一般概觀。

使用文稿活動，您可以使用資料操作語言（DML）和資料定義語言（DDL）來執行一般作業。 INSERT、UPDATE、DELETE 和SELECT等 DML 語句可讓使用者在資料庫中插入、修改、刪除和擷取數據。 DDL 語句，例如 CREATE、ALTER 和 DROP，可讓資料庫管理員建立、修改和移除資料庫物件，例如數據表、索引和使用者。

您可以使用文稿活動，在您的企業或 Azure 虛擬機上叫用下列其中一個資料存放區中的 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	活動的類型，設定為「Script」。。	Yes
typeProperties	指定要設定文稿活動的屬性。	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
log 設定	用來儲存輸出記錄的設定。如果未指定，則會停用腳本記錄。	No
log 設定.logDestination	記錄輸出的目的地。它可以是 ActivityOutput 或 ExternalStore。默認值：ActivityOutput。	No
log 設定.logLocation 設定	如果logDestination為ExternalStore，則為目標位置的設定。	No
logSettiongs.logLocation 設定.linkedServiceName	目標位置的連結服務。僅支援 Blob 記憶體。	No
log 設定.logLocation 設定.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 語句。	如果 connector 支援 log 語句且 enableScriptLogs 為 true，且未提供 logLocation 設定。
outputLogsPath	記錄檔的完整路徑。	如果 enableScriptLogs 為 true，且提供 logLocation 設定。
outputTruncated	指出輸出是否超過限制並遭到截斷。	如果輸出超過限制。

注意

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

使用UI設定文本活動

內嵌指令碼

Screenshot showing the UI to configure an inline script.

內嵌腳本與管線 CI/CD 整合良好，因為腳本會儲存為管線元數據的一部分。

記錄

Screenshot showing the UI for the logging settings for a script.

記錄選項：

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

注意

計費 - 腳本活動會以管線活動計費。

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

在 Azure Data Factory 或 Synapse Analytics 中使用腳本活動轉換數據

語法詳細數據

活動輸出

使用UI設定文本活動

內嵌指令碼

記錄

相關內容

其他資源