Data Factory in Microsoft Fabric 的參數

本文將教你如何在 Fabric 中的 Data Factory 管線中使用參數，讓你能建立靈活且可重用的工作流程。

在資料工廠管線中使用參數、表達式與函式

本節將引導你了解如何在 Data Factory for Fabric 中建立參數化管線的基本知識，並沿途使用清晰的範例。 參數與動態表達式節省時間，並讓您能建立靈活的擷取、轉換、載入（ETL）或擷取、載入、轉換（ELT）解決方案。 它們減少硬編碼，並允許你重用物件和程序，讓管線更容易維護，也能更快推出新功能。

參數和運算式概念

您可以使用參數將外部值傳遞至管線。 設定參數後，它的值在整個執行過程中保持不變。 參數允許你每次重複使用同一條管線，但值會不同。 你可以單獨使用參數，也可以在表達式中使用，這些數值是固定的，或是在管線執行時計算出來的。

表達式可以移至字串值中的任何位置，並一律傳回另一個字元串值。 例如，如果您使用 @password，管線會將密碼視為參數。 如果是表達式，移除 @ 即可取得實際內容。 若要使用以 @ 開頭的字串，請輸入 @@ 來加以逸出。 以下範例說明了實際運作方式。

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

表達式也可以透過 字串插值出現在字串內部，將表達式包裹在 @{ ... }中。 例如，下列字串包含參數值和常量字串值：

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

字串插值總是回傳一個字串。 例如，若定義 myNumber 為 42 和 myString 為 foo：

參數值	Result
"@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} 字串。

參數表達式範例

建立並使用參數

要建立參數，請選擇管線編輯器畫布的背景，然後在屬性視窗底部選擇 參數 標籤。 選擇 + 新以 在管線中新增參數，並賦予其名稱、資料型態及預設值：

接著你可以在管線支援動態內容的任何地方使用這個參數。 在此範例中，參數會在「複製活動」屬性頁面的 Source 索引標籤上，動態提供湖屋資料存放區的名稱。

[新增動態內容] 視窗會隨即開啟。 可用它來指定任何動態內容，包括參數、 系統變數、 函式或管線變數。 在這個例子中，你選擇先前定義的參數，動態內容視窗會自動填入正確的表達式以參考該參數。

參數化連接

要參數化管線中的連接，請使用你想要動態替換的連線的全域唯一識別碼（GUID）。

1. 在動態修改管線中的連線之前，先取得你想設定的連線的 GUID。
2. 到 設定>管理連線與閘道。
3. 找到連線名稱，並選擇旁邊的省略號（...）。
4. 選擇 設定 並複製 連線 ID。
5. 把 GUID 貼到字串參數中，並在動態表達式中引用該參數。

複雜運算式範例

以下表達式指涉一個深層的活動輸出子領域。 若要參照其求值結果為子欄位的管線參數，請使用 [] 語法，而不要使用點號（.）運算子，例如 subfield1 和 subfield2。

@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*

動態內容編輯器

完成編輯時，動態內容編輯器會自動逸出內容中的字元。 例如，內容編輯器中的下列內容是具有表達式的字串內插：

@{toUpper('myData')}

動態內容編輯器會將先前的內容轉換成下列表示式：

MYDATA

在表達式中使用函數和變數

您可以在運算式內呼叫函數並使用變數。 下列各節提供可在運算式中使用之函式的相關資訊。

管線範圍變數

你可以在管線 JSON 中任何地方引用這些系統變數。

變數名稱	Description
@pipeline().DataFactory	管線執行所在的工作區名稱
@pipeline().Pipeline	管線名稱
@pipeline().RunId	特定管線執行識別碼
@pipeline().TriggerId	觸發管線的觸發器識別碼
@pipeline().TriggerName	觸發管線的觸發器名稱
@pipeline().TriggerTime	叫用管線的觸發程序執行的時間。 這個值是觸發器實際觸發以啟動管線運行的時間，可能與觸發器排程的時間略有不同。
@pipeline().GroupId	管線所屬的群組識別碼。 在 Microsoft Fabric 中，群組是一組相關資源的集合，你可以一起管理。 群組組織並控制資源存取，使管理權限與監控多條管線間的活動變得更容易。
@pipeline()?.由管道名稱觸發	觸發流程執行的管線名稱。 當執行管線活動觸發管線執行時適用。 在其他情況下會評估為 Null。 請注意後面 @pipeline()的問號。
@pipeline()?.由管道運行ID觸發	用於觸發此管線執行的管線執行識別碼。 當「執行管線」活動觸發管線執行時適用。 在其他情況下會求值為 Null。 請注意後面 @pipeline()的問號。

Note

與觸發器相關的日期/時間系統變數（無論是在管線範圍或觸發程序範圍內）都會回傳採用 ISO 8601 格式的協調世界時（UTC）日期/時間，例如 2017-06-01T22:20:00.4061448Z。

字串函數

要處理字串，可以使用這些字串函數以及一些 集合函數。 字串函式只能用於字串。

字串函數	Task
concat	結合兩個或多個字串，並傳回合併的字串。
endsWith	檢查字串是否以指定的子字串結束。
guid	以字串形式產生全域唯一識別碼 (GUID)。
indexOf	傳回子字串的起始位置。
lastIndexOf	傳回子字串最後一次出現的起始位置。
replace	使用指定字串取代子字串，並傳回已更新的字串。
split	根據原始字串中指定的分隔符號字元，從較大型字串傳回包含以逗號分隔之子字串的陣列。
startsWith	檢查字串是否以特定的子字串開始。
substring	傳回字串中的字元 (從指定的位置起始)。
toLower	傳回小寫格式的字串。
toUpper	傳回大寫格式的字串。
trim	移除字串的開頭和尾端空白字元，並傳回更新後的字串。

集合函數

要處理像陣列、字串和字典這類集合，請使用這些集合函式。

集合函式	Task
contains	檢查集合是否具有特定項目。
empty	檢查集合是否是空的。
first	傳回集合中的第一個項目。
intersection	在指定的集合中，傳回只有共同項目的集合。
join	傳回具有陣列中「所有」項目 (以指定的字元隔開) 的字串。
last	傳回集合中的最後一個項目。
length	傳回字串或陣列中的項目數目。
skip	移除集合前端的項目，並傳回「其他所有」項目。
take	傳回集合中的前端項目。
union	傳回具有指定集合中「所有」項目的集合。

邏輯函式

在條件下使用這些函式來評估任何類型的邏輯。

邏輯比較函式	Task
and	檢查是否所有表達式均為真。
equals	檢查兩個值是否相等。
greater	檢查第一個值是否大於第二個值。
greaterOrEquals	檢查第一個值是否大於或等於第二個值。
if	檢查運算式是否為 true 或 false。 根據結果，傳回指定的值。
less	檢查第一個值是否小於第二個值。
lessOrEquals	檢查第一個值是否小於或等於第二個值。
not	檢查運算式是否為 False。
or	檢查是否至少有一個運算式為真。

轉換函數

使用這些函式在該語言中的各種原生型別之間進行轉換：

• 字串
• 整數
• float
• boolean
• arrays
• dictionaries

轉換函式	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 中不安全的字元替換為轉義字元。
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	傳回目前的時間戳記作為字串。

相關內容

• 表達式語言