Data Factory in Microsoft Fabric 的參數
本文件說明如何在您的管線中使用 Fabric 中 Data Factory 的參數。
在本文件中,我們著重在學習基本概念與各種範例,以探索在 Fabric 中的 Data Factory 內建立參數化資料管線的能力。 參數化和動態運算式可以節省大量時間,並允許更有彈性的「擷取、轉換和下載 (ETL)」或「擷取、載入、轉換 (ELT)」解決方案,這將大幅降低解決方案維護的成本,並加速將新功能實作到現有的管線。 這些提升的原因是參數化可將硬式編碼的數量降到最低,並增加解決方案中可重複使用的物件和程序數目。
您可以使用參數將外部值傳遞至管線。 參數傳遞至資源之後,就無法變更。 藉由將資源參數化,您可以每次以不同的值重複使用它們。 參數可以個別使用或做為運算式的一部分。 定義中的參數值可以是常值,或是在執行階段評估的運算式。
運算式可以出現在字串值中的任何一處,並一律產生另一個字串值。 在這裡,password 是運算式中的管線參數。 當參數值為運算式時,藉由移除 @ 符號來擷取運算式的主體。 如果需要的常值字串開頭為 @,就必須使用 @@ 逸出。 下列範例顯示如何評估運算式。
參數值 | 結果 |
---|---|
"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 做為「字串」。 |
"Answer is: @{pipeline().parameters.myNumber}" | 傳回 Answer is: 42 字串。 |
"@concat('Answer is: ', string(pipeline().parameters.myNumber))" | 傳回字串 Answer is: 42 |
"Answer is: @@{pipeline().parameters.myNumber}" | 傳回 Answer is: @{pipeline().parameters.myNumber} 字串。 |
若要建立參數,請選取管線編輯器創作區的背景,然後 選取底部屬性視窗的 [參數 ] 索引標籤。 選取 [ + 新增 ] 按鈕,將新的參數新增至管線、提供名稱、資料類型和預設值:
接著,您可以在管線中支援動態內容的任何位置使用 參數。 在此範例中,參數可用來在複製活動屬性頁的 [來源] 索引標籤上動態提供 Lakehouse 資料存放區的名稱。
[新增動態內容] 視窗隨即顯示,可讓您指定任何類型的動態內容,包括參數、系統變數、函式或管線變數。 在此範例中,會選取先前定義的參數,而且動態內容視窗會自動填入正確的表達式來參考參數。
下列範例顯示的複雜範例參考活動輸出的深度子欄位。 若要參考評估為子欄位的管線參數,請使用 [] 語法,而不是點 (.) 運算子 (如同 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 | 檢查字串是否以特定的子字串開始。 |
substring | 傳回字串中的字元 (從指定的位置起始)。 |
toLower | 傳回小寫格式的字串。 |
toUpper | 傳回大寫格式的字串。 |
修剪 | 移除字串的開頭和尾端空白字元,並傳回更新後的字串。 |
若要處理集合 (通常為陣列、字串,而有時候為字典),您可以使用這些集合函式。
集合函式 | Task |
---|---|
contains | 檢查集合是否具有特定項目。 |
empty | 檢查集合是否是空的。 |
first | 傳回集合中的第一個項目。 |
intersection | 在指定的多個集合中,傳回「只有」共同項目的集合。 |
join | 傳回具有陣列中「所有」項目 (以指定的字元隔開) 的字串。 |
last | 傳回集合中的最後一個項目。 |
length | 傳回字串或陣列中的項目數目。 |
skip | 移除集合前端的項目,並傳回「其他所有」項目。 |
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 | 傳回輸入值的布林值版本。 |
coalesce | 從一個或多個參數中傳回第一個非 Null 值。 |
createArray | 從多個輸入傳回陣列。 |
dataUri | 傳回輸入值的資料 URI。 |
dataUriToBinary | 傳回資料 URI 的二進位版本。 |
dataUriToString | 傳回資料 URI 的字串版本。 |
decodeBase64 | 傳回 base64 編碼字串的字串版本。 |
decodeDataUri | 傳回資料 URI 的二進位版本。 |
decodeUriComponent | 傳回以已解碼版本取代逸出字元的字串。 |
encodeUriComponent | 傳回以逸出字元取代 URL 中 Unsafe 字元的字串。 |
float | 傳回輸入值的浮點數。 |
int | 傳回字串的整數版本。 |
json | 傳回字串或 XML 的 JavaScript 物件標記法 (JSON) 類型值或物件。 |
string | 傳回輸入值的字串版本。 |
uriComponent | 藉由以逸出字元取代 URL 中的 Unsafe 字元,傳回輸入值的 URI 編碼版本。 |
uriComponentToBinary | 傳回 URI 編碼字串的二進位版本。 |
uriComponentToString | 傳回 URI 編碼字串的字串版本。 |
xml | 傳回字串的 SML 版本。 |
xpath | 檢查 XML 中是否有符合 XPath (XML 路徑語言) 運算式的節點或值,並傳回符合的節點或值。 |
這些函式可用於任一類型的數字︰整數和浮點數。
數學函式 | Task |
---|---|
add | 傳回兩個數字相加的結果。 |
div | 傳回兩個數字相除的結果。 |
max | 從數字集合或陣列中傳回最大值。 |
min | 從數字集合或陣列中傳回最小值。 |
mod | 傳回兩數相除的餘數。 |
mul | 傳回將兩數相乘的乘積。 |
rand | 從指定範圍傳回隨機整數。 |
range | 傳回從指定整數開始的整數陣列。 |
sub | 傳回第一個數字減去第二個數字的結果。 |
日期或時間函式 | Task |
---|---|
addDays | 將天數加入時間戳記。 |
addHours | 將時數加入時間戳記。 |
addMinutes | 將分鐘數加入時間戳記。 |
addSeconds | 將秒數加入時間戳記。 |
addToTime | 將時間單位數字加入時間戳記。 另請參閱 getFutureTime。 |
convertFromUtc | 將時間戳記從國際標準時間 (UTC) 轉換為目標時區。 |
convertTimeZone | 將時間戳記從來源時區轉換為目標時區。 |
convertToUtc | 將時間戳記從來源時區轉換為國際標準時間 (UTC)。 |
dayOfMonth | 傳回時間戳記中的當月日期元件。 |
dayOfWeek | 傳回時間戳記中的星期幾元件。 |
dayOfYear | 傳回時間戳記中一年的第幾天元件。 |
formatDateTime | 以選用格式將時間戳記當作字串傳回。 |
getFutureTime | 傳回目前時間戳記加上指定時間單位的結果。 另請參閱 addToTime。 |
getPastTime | 傳回目前時間戳記減去指定時間單位的結果。 另請參閱 subtractFromTime。 |
startOfDay | 傳回時間戳記中當天的起始點。 |
startOfHour | 傳回時間戳記中小時的起始點。 |
startOfMonth | 傳回時間戳記中月份的起始點。 |
subtractFromTime | 從時間戳記減去時間單位數字。 另請參閱 getPastTime。 |
ticks | 傳回指定時間戳記的 ticks 屬性值。 |
utcNow | 傳回目前的時間戳記作為字串。 |