如何在 Azure 数据工厂中使用参数、表达式和函数

适用于：Azure 数据工厂 Azure Synapse Analytics

本文档的重点主要在于通过各种示例介绍基本概念，以探索在 Azure 数据工厂中创建参数化数据管道的能力。 参数化和动态表达式是对 ADF 的重要补充，因为它们可以节省大量的时间，并实现更灵活的提取、转换、加载 (ETL) 或提取、加载、转换 (ELT) 解决方案，这极大地降低了解决方案的维护成本，加快了新功能在现有管道中的实现。 这些优势是因为参数化最大限度地降低了硬编码数量，并增加了解决方案中可重用对象和进程的数量。

Azure 数据工厂 UI 和参数

如果你不熟悉 ADF 用户界面中的 Azure 数据工厂参数用法，请查看使用参数的链接服务的数据工厂 UI 和使用参数的元数据驱动管道的数据工厂 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 数据集的路径使用这些参数的值进行设置。 此处使用的语法是：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"
            }
        }
    }
}

在表达式中调用函数

可以在表达式中调用函数。 以下各节提供了有关可以在表达式中使用的函数的信息。

字符串函数

若要使用字符串，可以使用这些字符串函数以及某些集合函数。 字符串函数仅适用于字符串。

字符串函数	任务
concat	组合两个或更多字符串，并返回组合后的字符串。
endsWith	检查字符串是否以指定的子字符串结尾。
guid	生成字符串形式的全局唯一标识符 (GUID)。
indexOf	返回子字符串的起始位置。
lastIndexOf	返回最后一次出现的子字符串的起始位置。
replace	将子字符串替换为指定的字符串，并返回更新的字符串。
split	根据原始字符串中指定的分隔符字符，从较大字符串中返回一个包含子字符串（以逗号分隔）的数组。
startsWith	检查字符串是否以特定的子字符串开头。
substring	返回字符串中的字符，从指定的位置开始。
toLower	返回小写格式的字符串。
toUpper	返回大写格式的字符串。
trim	从字符串中删除前导和尾随空格，并返回更新后的字符串。

集合函数

若要使用集合（通常是数组或字符串，有时是字典），可以使用这些集合函数。

集合函数	任务
contains	检查集合是否包含某个特定项。
empty	检查集合是否为空。
first	返回集合中的第一个项。
intersection	返回其中仅包含指定集合的共有项的一个集合。
join	返回一个字符串，其中包含某个数组中的所有项并以指定的分隔符分隔每个项。
last	返回集合中的最后一个项。
length	返回字符串或数组中的项数。
skip	删除集合开头的项，并返回所有其他项。
take	返回集合开头的项。
union	返回一个集合，其中包含指定集合中的所有项。

逻辑函数

这些函数可在条件中使用，并可用于评估任何类型的逻辑。

逻辑比较函数	任务
and	检查所有表达式是否为 true。
equals	检查两个值是否相等。
greater	检查第一个值是否大于第二个值。
greaterOrEquals	检查第一个值是否大于或等于第二个值。
if	检查表达式为 true 还是 false。 根据结果返回指定的值。
less	检查第一个值是否小于第二个值。
lessOrEquals	检查第一个值是否小于或等于第二个值。
not	检查表达式是否为 false。
or	检查是否至少一个表达式为 true。

转换函数

这些函数用于在语言中的每个本机类型之间转换：

• string
• integer
• FLOAT
• boolean
• arrays
• dictionaries

转换函数	任务
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 不安全字符替换为转义字符来返回输入值的 URI 编码版本。
uriComponentToBinary	返回 URI 编码字符串的二进制版本。
uriComponentToString	返回 URI 编码字符串的字符串版本。
xml	返回字符串的 XML 版本。
xpath	检查 XML 中是否存在与 XPath（XML 路径语言）表达式匹配的节点或值，并返回匹配的节点或值。

数学函数

这些函数可用于以下任一数字类型：整数和浮点数。

数学函数	任务
add	返回两个数字相加的结果。
div	返回两个数字相除的结果。
max	返回一组数字或数组中的最大值。
min	返回一组数字或数组中的最小值。
mod	返回将两个数字相除后的余数。
mul	返回将两个数字相乘得到的乘积。
rand	返回指定范围内的随机整数。
range	返回以指定整数开头的一个整数数组。
sub	返回第一个数字减去第二个数字得到的结果。

日期函数

日期或时间函数	任务
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 数据工厂复制管道详情

此 Azure 数据工厂复制管道参数传递教程逐步讲解如何在管道和活动之间以及活动之间传递参数。

使用参数的映射数据流管道详情

请遵循使用参数的映射数据流中的说明操作，了解有关如何在数据流中使用参数的全面示例。

使用参数的元数据驱动管道详情

请按照使用参数的元数据驱动管道中的说明操作，详细了解如何使用参数设计元数据驱动管道。 这是热门的参数用例。

相关内容

对于可以在表达式中使用的系统变量列表，请参阅系统变量。