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

適用於:Azure Data Factory Azure Synapse Analytics

您在 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 陳述式。 您可將執行 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 
               }, 
               ... 
            ] 
         }, 
         ... 
      ],     
         ... 
         ] 
      }, 
      "logSettings": { 
         "logDestination": "<ActivityOutput> or <ExternalStore>", 
         "logLocationSettings":{ 
            "linkedServiceName":{ 
               "referenceName": "<name>", 
               "type": "<LinkedServiceReference>" 
            }, 
            "path": "<folder path>" 
         } 
      } 
    } 
} 

下表說明這些 JSON 屬性:

屬性名稱 描述 必要
NAME 活動名稱。
type 將 activity 的 type 設定為「Script」。
typeProperties 指定要設定 Script Activity 的屬性。
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
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 指令碼所傳回的結果集計數。 Always
resultSets 包含所有結果集的陣列。 Always
resultSets.rowCount 結果集中的資料列總計。 Always
resultSets.rows 結果集中的資料列陣列。 Always
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 個資料列/2MB 大小限制。

使用 UI 設定 Script 活動

內嵌指令碼

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

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

記錄

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

記錄選項:

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

注意

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

後續步驟

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