如何在 Azure Data Factory 中使用參數、運算式和函式

發行項
04/27/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。了解如何免費開始新的試用！

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

Azure Data Factory UI 和參數

如果您不熟悉在 ADF 使用者介面中 Azure Data Factory 參數的使用方式，請檢閱具有參數的連結服務的 Data Factory UI 和具有參數的中繼資料驅動管線的 Data Factory UI，以取得視覺化說明。

參數和運算式概念

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

例如：

"name": "value"

或

"name": "@pipeline().parameters.password"

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

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

使用稱為「字串插補」的功能，運算式也可以出現在字串內，其中運算式會包含在 @{ ... } 內。例如："name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"

使用字串插補時，結果一律為字串。假設我將 myNumber 定義為 42，將 myString 定義為 foo：

JSON 值	結果
"@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}` 字串。

在運算式中使用參數的範例

複雜運算式範例

下列範例顯示的複雜範例參考活動輸出的深度子欄位。若要參考評估為子欄位的管道參數，請使用 [] 語法，而不是點 (.) 運算子 (如同 subfield1 和 subfield2 的情況)

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

動態內容編輯器

完成編輯時，動態內容編輯器會自動逸出內容中的字元。例如，內容編輯器中的下列內容是具有兩個運算式函式的字串插補。

{ 
  "type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
  "name": "@{toUpper('myData')}"
}

動態內容編輯器會將上述內容轉換成運算式 "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}"。此運算式的結果是如下所示的 JSON 格式字串。

{
  "type": "Table",
  "name": "MYDATA"
}

具有參數的資料集

在以下範例中，BlobDataset 會採用一個名為 path 的參數。其值會藉由使用下列運算式，設定 folderPath 屬性的值：dataset().path。

{
    "name": "BlobDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": "@dataset().path"
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "path": {
                "type": "String"
            }
        }
    }
}

具有參數的管線

在以下範例中，管線會採用 inputPath 和 outputPath 參數。這些參數的值會用來設定參數化 Blob 資料集的 path。這裡使用的語法為：pipeline().parameters.parametername.

{
    "name": "Adfv2QuickStartPipeline",
    "properties": {
        "activities": [
            {
                "name": "CopyFromBlobToBlob",
                "type": "Copy",
                "inputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.inputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.outputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "typeProperties": {
                    "source": {
                        "type": "BlobSource"
                    },
                    "sink": {
                        "type": "BlobSink"
                    }
                }
            }
        ],
        "parameters": {
            "inputPath": {
                "type": "String"
            },
            "outputPath": {
                "type": "String"
            }
        }
    }
}

在運算式內呼叫函式

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

字串函數

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

字串函數	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	傳回目前的時間戳記作為字串。

詳述練習範例

詳述具有參數的 Azure Data Factory 複製管線

此 Azure Data Factory 複製管線參數傳遞教學課程會引導您如何在管道與活動之間，以及活動之間傳遞參數。

詳述具有參數的對應資料流管線

如需如何在資料流程中使用參數的完整範例，請遵循具有參數的對應資料流。

詳述具有參數的中繼資料驅動管線

若要深入了解如何使用參數來設計中繼資料驅動管線，請遵循具有參數的中繼資料驅動管線。這是參數的熱門使用案例。

如需可在運算式中使用之系統變數的清單，請參閱系統變數。