Microsoft Fabric 中 Data Factory 的參數
本文件說明如何在您的管線中使用 Fabric 中 Data Factory 的參數。
如何在 Fabric 中 Data Factory 的管線中使用參數、表達式和函式
在本檔中,我們著重於使用各種範例來學習基本概念,以探索在 Fabric 的 Data Factory 內建立參數化數據管線的能力。 參數化和動態表達式可以節省大量的時間,並允許更有彈性的擷取、轉換、負載(ETL)或擷取、載入、轉換(ELT)解決方案,這將大幅降低解決方案維護的成本,並加速將新功能實作到現有的管線。 這些收益是因為參數化可將硬式編碼的數量降到最低,並增加解決方案中可重複使用的對象和進程數目。
參數和表達式概念
您可以使用參數將外部值傳遞至管線。 一旦參數傳遞至資源,就無法變更。 藉由參數化資源,您可以每次以不同的值重複使用它們。 參數可以個別或作為表達式的一部分使用。 定義中的參數值可以是在運行時間評估的常值或表達式。
表達式可以出現在字串值中的任何位置,而且一律會產生另一個字元串值。 在這裡,密碼是表達式中的管線參數。 如果參數值是表達式,則會藉由移除 at-sign (@) 來擷取表達式的主體。 如果需要以 @开头的常值字符串,則必須使用 @@逸出它。 下列範例示範如何評估表達式。
參數值 | 結果 |
---|---|
“parameters” | 傳回 'parameters' 字元。 |
“parameters[1]” | 傳回 'parameters[1]' 字元。 |
"@@" | 傳回包含 『@』 的 1 個字元字串。 |
" @" | 傳回包含 ' @' 的 2 個字元字串。 |
表達式也可以出現在字串內,使用稱為 字串插補 的功能,其中表達式會包裝在 中 @{ ... }
。 例如,下列字串包含參數值和常值字串值:
“名字: @{pipeline(.parameters.firstName} 姓氏: @{pipeline(.parameters.lastName}”
使用字串插補,結果一律為字串。 例如,如果您定義為 myNumber
42
和 myString
,則為 foo
:
參數值 | 結果 |
---|---|
“@pipeline(.parameters.myString” | 以 foo 字串的形式傳回。 |
“@{pipeline(.parameters.myString}” | 以 foo 字串的形式傳回。 |
“@pipeline(.parameters.myNumber” | 以42 數位傳回。 |
“@{pipeline(.parameters.myNumber}” | 以42 字串的形式傳回。 |
“答案是: @{pipeline(.parameters.myNumber}” | 傳回 Answer is: 42 字串。 |
“@concat('Answer is: ', string(pipeline(.parameters.myNumber))” | 傳回字串 Answer is: 42 |
“答案是: @@{pipeline(.parameters.myNumber}” | 傳回 Answer is: @{pipeline().parameters.myNumber} 字串。 |
在表達式中使用參數的範例
建立和使用參數
若要建立參數,請選取管線編輯器畫布的背景,然後 選取底部屬性視窗的 [參數 ] 索引標籤。 選取 [ + 新增 ] 按鈕,將新的參數新增至管線、提供名稱、資料類型和預設值:
接著,您可以在管線中支援動態內容的任何位置使用 參數。 在此範例中,參數可用來在複製活動屬性頁的 [來源] 索引標籤上動態提供 Lakehouse 資料存放區的名稱。
[新增動態內容] 視窗隨即顯示,可讓您指定任何類型的動態內容,包括參數、系統變數、函式或管線變數。 在此範例中,會選取先前定義的參數,而且動態內容視窗會自動填入正確的表達式來參考參數。
複雜表達式範例
下列範例顯示參考活動輸出深度子欄位的複雜範例。 若要參考評估為子欄位的管線參數,請使用 [] 語法,而不是 dot(.) 運算符(如 subfield1 和 subfield2 的情況所示)
@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*
動態內容編輯器
當您完成編輯時,動態內容編輯器會自動逸出內容中的字元。 例如,內容編輯器中的下列內容是具有運算式函式的字串插補:
@{toUpper('myData')}
動態內容編輯器會將上述內容轉換成下列運算式:
MYDATA
在表達式中使用函式和變數
您可以呼叫函式,並在表達式中使用變數。 下列各節提供可在表達式中使用的函式相關信息。
管線範圍變數
這些系統變數可以在管線 JSON 中的任何位置參考。
變數名稱 | 描述 |
---|---|
@pipeline().DataFactory | 管線執行中執行的數據或 Synapse 工作區名稱 |
@pipeline().Pipeline | 管線名稱 |
@pipeline().RunId | 特定管線執行識別碼 |
@pipeline().TriggerId | 叫用管線的觸發程式標識碼 |
@pipeline().TriggerName | 叫用管線的觸發程序名稱 |
@pipeline().TriggerTime | 叫用管線的觸發程式執行時間。 這是觸發 程式實際 引發以叫用管線執行的時間,它可能會與觸發程式的排程時間稍有不同。 |
@pipeline().GroupId | 管線執行所屬群組的標識碼。 |
@pipeline()?.TriggeredByPipelineName | 觸發管線執行的管線名稱。 當管線執行是由 ExecutePipeline 活動觸發時適用。 在其他情況下使用時,評估為 Null 。 記下之後的問號 @pipeline() |
@pipeline()?.TriggeredByPipelineRunId | 觸發管線執行的管線執行標識碼。 當管線執行是由 ExecutePipeline 活動觸發時適用。 在其他情況下使用時,評估為 Null 。 記下之後的問號 @pipeline() |
注意
觸發程式相關的日期/時間系統變數(在管線和觸發程式範圍中)會以 ISO 8601 格式傳回 UTC 日期,例如 2017-06-01T22:20:00.4061448Z
。
字串函數
若要使用字串,您可以使用這些字串函式和一些 集合函式。 字串函式僅適用於字串。
字串函數 | Task |
---|---|
concat | 結合兩個或多個字串,並傳回合並的字串。 |
endsWith | 檢查字串是否以指定的子字串結尾。 |
guid | 產生全域唯一標識碼 (GUID) 作為字串。 |
indexOf | 傳回子字串的起始位置。 |
lastIndexOf | 傳回子字串最後一次出現的開始位置。 |
replace | 以指定的字串取代子字串,並傳回更新的字串。 |
split | 根據原始字串中指定的分隔符,傳回包含以逗號分隔的子字串數位。 |
startsWith | 檢查字串是否以特定子字串開頭。 |
子 | 從指定的位置開始,從字串傳回字元。 |
toLower | 以小寫格式傳回字串。 |
toUpper | 以大寫格式傳回字串。 |
修剪 | 從字串中移除開頭和尾端空格符,並傳回更新的字串。 |
集合函數
若要使用集合,一般是數位、字串,有時是字典,您可以使用這些集合函式。
集合函式 | Task |
---|---|
contains | 檢查集合是否有特定專案。 |
empty | 檢查集合是否為空白。 |
first | 從集合傳回第一個專案。 |
交叉口 | 傳回集合,該集合只具有指定集合中的一般專案。 |
join | 傳回字串,其中包含 數位中的所有 專案,並以指定的字元分隔。 |
last | 從集合傳回最後一個專案。 |
length | 傳回字串或陣列中的項目數。 |
跳 | 從集合前面移除專案,並傳回 所有其他 專案。 |
take | 傳回集合前端的專案。 |
union | 傳回具有 指定集合中所有 專案的集合。 |
邏輯函式
這些函式在條件內很有用,可用來評估任何類型的邏輯。
邏輯比較函式 | Task |
---|---|
and | 檢查所有表達式是否為 true。 |
equals | 檢查這兩個值是否相等。 |
greater | 檢查第一個值是否大於第二個值。 |
greaterOrEquals | 檢查第一個值是否大於或等於第二個值。 |
if | 檢查表達式是否為 true 或 false。 根據結果,傳回指定的值。 |
less | 檢查第一個值是否小於第二個值。 |
lessOrEquals | 檢查第一個值是否小於或等於第二個值。 |
not | 檢查表達式是否為 false。 |
or | 檢查是否至少有一個表達式為 true。 |
轉換函數
這些函式可用來在語言中的每個原生類型之間進行轉換:
- string
- 整數
- float
- boolean
- 陣 列
- 字典
轉換函式 | Task |
---|---|
array | 從單一指定的輸入傳回數位。 如需多個輸入,請參閱 createArray。 |
base64 | 傳回字串的base64編碼版本。 |
base64ToBinary | 傳回base64編碼字串的二進位版本。 |
base64ToString | 傳回base64編碼字串的字串版本。 |
binary | 傳回輸入值的二進位版本。 |
bool | 傳回輸入值的布爾值版本。 |
合併 | 從一或多個參數傳回第一個非 Null 值。 |
createArray | 從多個輸入傳回陣列。 |
dataUri | 傳回輸入值的數據 URI。 |
dataUriToBinary | 傳回數據 URI 的二進位版本。 |
dataUriToString | 傳回數據 URI 的字串版本。 |
decodeBase64 | 傳回base64編碼字串的字串版本。 |
decodeDataUri | 傳回數據 URI 的二進位版本。 |
decodeUriComponent | 傳回字串,以譯碼版本取代逸出字元。 |
encodeUriComponent | 傳回字串,以逸出字元取代 URL 不安全字元。 |
float | 傳回輸入值的浮點數。 |
int | 傳回字串的整數版本。 |
Json | 傳回字串或 XML 的 JavaScript 物件表示法 (JSON) 類型值或物件。 |
string | 傳回輸入值的字串版本。 |
uriComponent | 將 URL 不安全字元取代為逸出字元,以傳回輸入值的 URI 編碼版本。 |
uriComponentToBinary | 傳回 URI 編碼字串的二進位版本。 |
uriComponentToString | 傳回 URI 編碼字串的字串版本。 |
xml | 傳回字串的 XML 版本。 |
Xpath | 檢查 XML 是否有符合 XPath (XML 路徑語言) 表示式的節點或值,並傳回相符的節點或值。 |
數學函數
這些函式可用於任一類型的數位: 整數 和 浮點數。
數學函式 | Task |
---|---|
add | 傳回加兩個數字的結果。 |
div | 傳回除兩個數字的結果。 |
max | 從一組數位或陣列傳回最高值。 |
min | 從一組數位或陣列傳回最小值。 |
國防部 | 傳回除兩個數位的餘數。 |
mul | 傳回乘兩個數字的產品。 |
rand | 從指定的範圍傳回隨機整數。 |
range | 傳回從指定整數開始的整數數位。 |
子 | 傳回從第一個數字減去第二個數字的結果。 |
日期函式
日期或時間函式 | Task |
---|---|
addDays | 將天數新增至時間戳。 |
addHours | 將小時數新增至時間戳。 |
addMinutes | 將分鐘數新增至時間戳。 |
addSeconds | 將秒數新增至時間戳。 |
addToTime | 將一些時間單位新增至時間戳。 另 請參閱 getFutureTime。 |
convertFromUtc | 將時間戳從通用時間協調 (UTC) 轉換為目標時區。 |
convertTimeZone | 將時間戳從來源時區轉換為目標時區。 |
convertToUtc | 將時間戳從來源時區轉換為通用時間國際標準時間(UTC)。 |
dayOfMonth | 從時間戳傳回月份元件的日期。 |
dayOfWeek | 從時間戳傳回星期幾元件。 |
dayOfYear | 從時間戳傳回年份元件的日期。 |
formatDateTime | 以選擇性格式傳回時間戳作為字串。 |
getFutureTime | 傳回目前的時間戳加上指定的時間單位。 另 請參閱 addToTime。 |
getPastTime | 傳回目前的時間戳減去指定的時間單位。 另 請參閱減去FromTime。 |
startOfDay | 傳回時間戳的當天開始時間。 |
startOfHour | 傳回時間戳的小時開始。 |
startOfMonth | 傳回時間戳的月份開始。 |
subtractFromTime | 從時間戳減去一些時間單位。 另 請參閱 getPastTime。 |
蜱 | ticks 傳回指定時間戳的屬性值。 |
utcNow | 以字串的形式傳回目前的時間戳。 |
相關內容
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應