閱讀英文

共用方式為


Data Factory in Microsoft Fabric 的參數

本文件說明如何在您的管線中使用 Fabric 中 Data Factory 的參數。

如何在 Data Factory in Fabric 的管線中使用參數、運算式和函數

在本文件中,我們著重在學習基本概念與各種範例,以探索在 Fabric 中的 Data Factory 內建立參數化資料管線的能力。 參數化和動態運算式可以節省大量時間,並允許更有彈性的「擷取、轉換和下載 (ETL)」或「擷取、載入、轉換 (ELT)」解決方案,這將大幅降低解決方案維護的成本,並加速將新功能實作到現有的管線。 這些提升的原因是參數化可將硬式編碼的數量降到最低,並增加解決方案中可重複使用的物件和程序數目。

參數和運算式概念

您可以使用參數將外部值傳遞至管線。 參數傳遞至資源之後,就無法變更。 藉由將資源參數化,您可以每次以不同的值重複使用它們。 參數可以個別使用或做為運算式的一部分。 定義中的參數值可以是常值,或是在執行階段評估的運算式。

運算式可以出現在字串值中的任何一處,並一律產生另一個字串值。 在這裡,password 是運算式中的管線參數。 當參數值為運算式時,藉由移除 @ 符號來擷取運算式的主體。 如果需要的常值字串開頭為 @,就必須使用 @@ 逸出。 下列範例顯示如何評估運算式。

參數值 結果
"parameters" 傳回字元 'parameters'。
"parameters[1]" 傳回字元 'parameters[1]'。
"@@" 傳回包含 \'\@\' 的 1 個字元字串。
" @" 傳回包含 '\@\' 的 2 個字元字串。

使用稱為「字串插補」的功能,運算式也可以出現在字串內,其中運算式會包含在 @{ ... } 內。 例如,下列字串包含參數值和常值字串值:

“名字: @{pipeline(.parameters.firstName} 姓氏: @{pipeline(.parameters.lastName}”

使用字串插補時,結果一律為字串。 例如,如果您定義為 myNumber 42myString ,則為 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 傳回目前的時間戳記作為字串。