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}”

使用字串插補，結果一律為字串。 例如，如果您定義為 myNumber42 和 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	以字串的形式傳回目前的時間戳。

相關內容

• 表達式語言