Microsoft Fabric 中数据工厂的参数

本文档介绍如何在 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	返回字符串形式的当前时间戳。

相关内容

• 表达式语言