Microsoft Fabric 中数据工厂的参数
本文档介绍如何在 Fabric 中的数据工厂的管道中使用参数。
本文档的重点在于通过各种示例介绍基本概念,以探索在 Fabric 中的数据工厂中创建参数化数据管道的能力。 参数化和动态表达式可以节省大量的时间,并实现更灵活的提取、转换和加载 (ETL) 解决方案,这极大地降低了解决方案的维护成本,加快了新功能在现有管道中的实现。 这些优势是因为参数化最大限度地降低了硬编码数量,并增加了解决方案中可重用对象和进程的数量。
可使用参数将外部值传递到管道。 参数传递到资源后,就不能更改。 通过将资源参数化,每次就可通过不同的值重复使用它们。 参数可单独使用,也可作为表达式的一部分使用。 定义中的参数值可以是文字,也可以是运行时计算的表达式。
表达式可出现在字符串值中的任何位置,并始终生成另一个字符串值。 此处,password 是表达式中的管道参数。 如果某个参数值为表达式,会通过删除 @ 符号来提取表达式的正文。 如果需要以“@”开头的文本字符串,则必须使用 @@ 将它转义。 以下示例演示了如何计算表达式。
参数值 | 结果 |
---|---|
"parameters" | 返回字符“parameters”。 |
"parameters[1]" | 返回字符“parameters[1]”。 |
"@@" | 返回包含\“\@\”的、由 1 个字符构成的字符串。 |
" @" | 返回包含 \“ \@ \”的、由 2 个字符构成的字符串。 |
如果使用称为字符串内插的功能(其中表达式封装在 @{ ... }
内),表达式还可以显示在字符串内。 例如,以下字符串包括参数值和字面量字符串值:
“First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}”
使用字符串内插,结果始终是字符串。 例如,如果将 myNumber
定义为 42
,将 myString
定义为 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} 。 |
若要创建参数,请选择管道编辑器画布的背景,然后选择底部属性窗口的“参数”选项卡。 选择“+ 新建”按钮,将新参数添加到管道,为其指定名称、数据类型和默认值:
然后,可以在管道中支持动态内容的任意位置使用参数。 在此示例中,参数用于在复制活动属性页的“源”选项卡上动态提供湖屋数据存储的名称。
将显示“添加动态内容”窗口,允许指定任何类型的动态内容,包括参数、系统变量、函数或管道变量。 在此示例中,选择了以前定义的参数,动态内容窗口会自动填充正确的表达式以引用参数。
以下示例显示了一个复杂的示例,该示例引用了活动输出的一个深层子字段。 若要引用计算结果为子字段的管道参数,请使用 [] 语法而不是点 (.) 运算符(如 subfield1 和 subfield2 一样)
@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*
完成编辑后,动态内容编辑器会自动转义内容中的字符。 例如,内容编辑器中的以下内容是包含表达式函数的字符串内插:
@{toUpper('myData')}
动态内容编辑器将上述内容转换为以下表达式:
MYDATA
可以调用函数并在表达式中使用变量。 以下各节提供了有关可以在表达式中使用的函数的信息。
可以在管道 JSON 中的任何位置引用这些系统变量。
变量名 | 说明 |
---|---|
@pipeline().DataFactory | 在其中运行管道运行的数据工厂或 Synapse 工作区的名称 |
@pipeline().Pipeline | 管道的名称 |
@pipeline().RunId | 特定管道运行的 ID |
@pipeline().TriggerId | 调用了管道的触发器的 ID |
@pipeline().TriggerName | 调用了管道的触发器的名称 |
@pipeline().TriggerTime | 触发器运行调用管道的时间。 这是触发器实际触发以调用管道运行的时间,它可能与触发器的计划时间略有不同。 |
@pipeline().GroupId | 管道运行所属组的 ID。 |
@pipeline()?.TriggeredByPipelineName | 触发管道运行的管道的名称。 当管道运行由 ExecutePipeline 活动触发时适用。 在其他环境中使用时,结果为“Null”。 注意 @pipeline() 后面的问号 |
@pipeline()?.TriggeredByPipelineRunId | 运行触发管道运行的管道的运行 ID。 当管道运行由 ExecutePipeline 活动触发时适用。 在其他环境中使用时,结果为“Null”。 注意 @pipeline() 后面的问号 |
备注
与触发器相关的日期/时间系统变量(在管道和触发器作用域内)以 ISO 8601 格式返回 UTC 日期,例如 2017-06-01T22:20:00.4061448Z
。
若要使用字符串,可以使用这些字符串函数以及某些集合函数。 字符串函数仅适用于字符串。
字符串函数 | 任务 |
---|---|
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 | 返回字符串形式的当前时间戳。 |