内置函数 - Amazon Step Functions
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

内置函数

Amazon States Language 提供了多个内置函数 (intrinsic functions),也称为 intrinsics,可帮助您在不使用 Task 状态的情况下执行基本的数据处理操作。内置函数是看起来与编程语言中的函数相似的结构。它们可以用来帮助有效载荷生成器处理进出 Task 状态 Resource 字段的数据。

在 Amazon States Language 中,根据您要执行的数据处理任务的类型,将内置函数分为以下类别:

注意
  • 要使用内置函数,必须在状态机定义的键值中指定 .$,如以下示例所示:

    "KeyId.$": "States.Array($.Id)"
  • 在工作流的字段中,您最多可以嵌套 10 个内置函数。以下示例显示了一个名为 myArn 的字段,其中包含九个嵌套的内置函数:

    "myArn.$": "States.Format('{}.{}.{}', States.ArrayGetItem(States.StringSplit(States.ArrayGetItem(States.StringSplit($.ImageRecipe.Arn, '/'), 2), '.'), 0), States.ArrayGetItem(States.StringSplit(States.ArrayGetItem(States.StringSplit($.ImageRecipe.Arn, '/'), 2), '.'), 1))"
提示

如果您在本地开发环境中使用 Step Functions,请确保您使用的是 1.12.0 或更高版本,以便能够在工作流中包含所有内置函数。

支持内置函数的字段

下面显示了每个状态的哪些字段支持内置函数。

支持内置函数的字段
State
Pass Task Choice Wait Succeed Fail Parallel Map
InputPath
Parameters
ResultSelector
ResultPath
OutputPath
Variable
<Comparison Operator>Path
TimeoutSecondsPath
HeartbeatSecondsPath
凭证

数组的内置函数

使用以下内置函数来执行数组操作。

States.Array

States.Array 内置函数采用零个或多个参数。解释器返回一个 JSON 数组,其中包含按提供的顺序排列的参数值。例如,给定以下输入:

{ "Id": 123456 }

您可以使用

"BuildId.$": "States.Array($.Id)"

返回以下响应:

“BuildId”: [123456]
States.ArrayPartition

使用 States.ArrayPartition 内置函数对大型数组进行分区。您也可以使用这个内置函数对数据进行切片,然后将有效负载分成较小的区块发送。

这个内置函数需要两个参数。第一个参数是一个数组,而第二个参数定义了区块大小。解释器将输入数组分成多个数组,其大小由区块大小指定。如果数组中剩余的项目数小于区块大小,则最后一个数组区块的长度可能小于之前的数组区块的长度。

输入验证

  • 必须指定一个数组作为函数第一个参数的输入值。

  • 必须为代表区块大小值的第二个参数指定一个非零的正整数。

    如果您为第二个参数指定了非整数值,Step Functions 会将其四舍五入为最接近的整数。

  • 输入数组不能超过 Step Functions 的有效载荷大小限制,即 256 KB。

例如,给定以下输入数组:

{"inputArray": [1,2,3,4,5,6,7,8,9] }

您可以使用 States.ArrayPartition 函数将数组分成四个值的区块:

"inputArray.$": "States.ArrayPartition($.inputArray,4)"

将返回以下数组区块:

{"inputArray": [ [1,2,3,4], [5,6,7,8], [9]] }

在前面的示例中,States.ArrayPartition 函数输出了三个数组。前两个数组根据区块大小的定义,各包含四个值。第三个数组包含剩余的值,并且小于定义的区块大小。

States.ArrayContains

使用 States.ArrayContains 内置函数来确定数组中是否存在特定值。例如,您可以使用此函数来检测 Map 状态迭代中是否存在错误。

这个内置函数需要两个参数。第一个参数是数组,而第二个参数是要在数组中搜索的值。

输入验证

  • 必须指定一个数组作为函数第一个参数的输入值。

  • 您必须指定一个有效的 JSON 对象作为第二个参数。

  • 输入数组不能超过 Step Functions 的有效载荷大小限制,即 256 KB。

例如,给定以下输入数组:

{ "inputArray": [1,2,3,4,5,6,7,8,9], "lookingFor": 5 }

您可以使用 States.ArrayContains 函数在以下位置中 inputArray 查找 lookingFor 值:

"contains.$": "States.ArrayContains($.inputArray, $.lookingFor)"

由于 lookingFor 中存储的值包含在 inputArray 中,因此 States.ArrayContains 会返回以下结果:

{"contains": true }
States.ArrayRange

使用 States.ArrayRange 内置函数创建一个包含特定元素范围的新数组。新数组最多可以包含 1000 个元素。

这个函数需要三个参数。第一个参数是新数组的第一个元素,第二个参数是新数组的最后一个元素,第三个参数是新数组中元素之间的增量值。

输入验证

  • 必须为所有参数指定整数值。

    如果您为任何参数指定了非整数值,Step Functions 会将其四舍五入为最接近的整数。

  • 必须为第三个参数指定一个非零值。

  • 新生成的数组不能包含超过 1000 个项目。

例如,以下使用 States.ArrayRange 函数将创建一个数组,其第一个值为 1,最后一个值为 9,并且第一个值和最后一个值之间的值,增量皆为二:

"array.$": "States.ArrayRange(1, 9, 2)"

将返回以下数组:

{"array": [1,3,5,7,9] }
States.ArrayGetItem

此内置函数返回指定索引的值。这个函数需要两个参数。第一个参数是值数组,第二个参数是要返回的值的数组索引。

例如,使用以下 inputArrayindex 值:

{ "inputArray": [1,2,3,4,5,6,7,8,9], "index": 5 }

根据这些值,您可以使用 States.ArrayGetItem 函数返回数组中 index 位置 5 的值:

"item.$": "States.ArrayGetItem($.inputArray, $.index)"

在本示例中,States.ArrayGetItem 返回以下结果:

{ "item": 6 }
States.ArrayLength

States.ArrayLength 内置函数返回数组的长度。它有一个参数,即要返回长度的数组。

例如,给定以下输入数组:

{ "inputArray": [1,2,3,4,5,6,7,8,9] }

您可以使用 States.ArrayLength 返回 inputArray 的长度:

"length.$": "States.ArrayLength($.inputArray)"

在本示例中,States.ArrayLength 返回以下 JSON 对象,表示数组长度:

{ "length": 9 }
States.ArrayUnique

States.ArrayUnique 内置函数从数组中删除重复的值,并返回仅包含唯一元素的数组。该函数的唯一参数是一个数组,该数组可以不排序。

例如,以下 inputArray 包含一系列重复的值:

{"inputArray": [1,2,3,3,3,3,3,3,4] }

您可以使用 States.ArrayUnique 函数指定要从中删除重复值的数组:

"array.$": "States.ArrayUnique($.inputArray)"

States.ArrayUnique 函数将返回以下仅包含唯一元素的数组,删除所有重复的值:

{"array": [1,2,3,4] }

用于数据编码和解码的内置函数

使用以下内置函数根据 Base64 编码方案对数据进行编码或解码。

States.Base64Encode

使用 States.Base64Encode 内置函数根据 MIME Base64 编码方案对数据进行编码。您可以使用此函数将数据传递给其他 Amazon 服务,而无需使用 Amazon Lambda 函数。

此函数将最多 1 万个字符的数据字符串作为其唯一参数进行编码。

例如,考虑以下 input 字符串:

{"input": "Data to encode" }

您可以使用 States.Base64Encode 函数将 input 字符串编码为 MIME Base64 字符串:

"base64.$": "States.Base64Encode($.input)"

States.Base64Encode 函数会返回以下编码数据:

{"base64": "RGF0YSB0byBlbmNvZGU=" }
States.Base64Decode

使用 States.Base64Decode 内置函数根据 MIME Base64 解码方案对数据进行解码。您可以使用此函数将数据传递给其他 Amazon 服务,而无需使用 Lambda 函数。

此函数将最多 1 万个字符的 Base64 编码数据字符串作为其唯一参数进行解码。

例如,给定以下输入:

{"base64": "RGF0YSB0byBlbmNvZGU=" }

您可以使用 States.Base64Decode 函数将 base64 字符串解码为便于阅读的字符串:

"data.$": "States.Base64Decode($.base64)"

States.Base64Decode function 会返回以下解码数据:

{"data": "Decoded data" }

用于哈希计算的内置函数

States.Hash

使用 States.Hash 内置函数计算给定输入的哈希值。您可以使用此函数将数据传递给其他 Amazon 服务,而无需使用 Lambda 函数。

这个函数需要两个参数。第一个参数是您要计算哈希值的数据。第二个参数是用于执行哈希计算的哈希算法。您提供的数据必须是包含 1 万个或更少字符的对象字符串。

您指定的哈希算法可以是以下任何算法:

  • MD5

  • SHA-1

  • SHA-256

  • SHA-384

  • SHA-512

例如,您可以使用此函数,使用指定 Algorithm 来计算 Data 字符串的哈希值:

{ "Data": "input data", "Algorithm": "SHA-1" }

您可以使用 States.Hash 函数来计算哈希值:

"output.$": "States.Hash($.Data, $.Algorithm)"

States.Hash 函数会返回以下哈希值:

{"output": "aaff4a450a104cd177d28d18d7485e8cae074b7" }

用于 JSON 数据操作的内置函数

使用这些函数对 JSON 对象执行基本的数据处理操作。

States.JsonMerge

使用 States.JsonMerge 内置函数将两个 JSON 对象合并为一个对象。这个函数需要三个参数。前两个参数是您要合并的 JSON 对象。第三个参数是布尔值 false。此布尔值决定是否启用深合并模式。

目前,Step Functions 仅支持浅合并模式;因此,必须将布尔值指定为 false。在浅模式下,如果两个 JSON 对象中存在相同的键,则后一个对象的键将覆盖第一个对象中的相同键。此外,当您使用浅合并时,嵌套在 JSON 对象中的对象不会合并。

例如,您可以使用 States.JsonMerge 函数合并以下两个相同键 a 的 JSON 对象。

{ "json1": { "a": {"a1": 1, "a2": 2}, "b": 2 }, "json2": { "a": {"a3": 1, "a4": 2}, "c": 3 } }

您可以在 States.JsonMerge 函数中指定 json1 和 json2 对象作为输入,将它们合并在一起:

"output.$": "States.JsonMerge($.json1, $.json2, false)"

States.JsonMerge 返回以下合并的 JSON 对象结果。在合并的 JSON 对象 output 中,json2 对象的键 a 替换了 json1 对象的键 a。此外,json1 对象键 a 中的嵌套对象被丢弃,因为浅模式不支持合并嵌套对象。

{ "output": { "a": {"a3": 1, "a4": 2}, "b": 2, "c": 3 } }
States.StringToJson

States.StringToJson 函数将转义的 JSON 字符串的引用路径作为其唯一参数。

解释器应用 JSON 分析器并返回输入分析后的 JSON 表单。例如,您可以使用此函数来转义以下输入字符串:

{ "escapedJsonString": "{\"foo\": \"bar\"}" }

使用 States.StringToJson 函数并指定 escapedJsonString 作为输入参数:

States.StringToJson($.escapedJsonString)

States.StringToJson 函数返回以下结果:

{ "foo": "bar" }
States.JsonToString

States.JsonToString 函数只接受一个参数,即包含要作为未转义字符串返回的 JSON 数据的路径。解释器返回一个字符串,其中包含表示路径指定数据的 JSON 文本。例如,您可以提供以下包含转义值的 JSON 路径:

{ "unescapedJson": { "foo": "bar" } }

States.JsonToString 函数提供 unescapedJson 中包含的数据:

States.JsonToString($.unescapedJson)

States.JsonToString 函数会返回以下响应:

{\"foo\": \"bar\"}

用于数学运算的内置函数

使用这些函数来执行数学运算。

States.MathRandom

使用 States.MathRandom 内置函数返回介于指定起始数字(包括)和结束数字(不包括)之间的随机数。

您可以使用此函数在两个或多个资源之间分配特定任务。

这个函数需要三个参数。第一个参数是起始数字,第二个参数是结束数字,最后一个参数控制种子值。种子值参数是可选的。如果您使用具有相同种子值的函数,它将返回相同的数字。

重要

由于 States.MathRandom 函数不返回加密安全的随机数,因此我们建议您不要将其用于安全敏感型应用程序。

输入验证

  • 必须为起始数字和结束数字参数指定整数值。

    如果您为起始数字或结束数字参数指定非整数值,Step Functions 会将其四舍五入为最接近的整数。

例如,要生成介于 1 到 999 之间的随机数,可以使用以下输入值:

{ "start": 1, "end": 999 }

要生成随机数,请为 States.MathRandom 函数提供 startend 值:

"random.$": "States.MathRandom($.start, $.end)"

States.MathRandom 函数返回以下随机数:

{"random": 456 }
States.MathAdd

使用 States.MathAdd 内置函数返回两个数字的总和。例如,您可以使用此函数在循环内递增值,而无需调用 Lambda 函数。

输入验证

  • 必须为所有参数指定整数值。

    如果您为一个或两个参数指定了非整数值,Step Functions 会将其四舍五入为最接近的整数。

  • 必须指定介于 -2147483648 和 2147483647 范围内的整数值。

例如,您可以使用以下值从 111 中减去 1:

{ "value1": 111, "step": -1 }

然后,使用 States.MathAdd 函数,定义 value1 为起始值,stepvalue1 的增量值:

"value1.$": "States.MathAdd($.value1, $.step)"

States.MathAdd 函数将在响应中返回下面的数字。

{"value1": 110 }

用于字符串操作的内置函数

States.StringSplit

使用 States.StringSplit 内置函数将字符串拆分成一个值数组。这个函数需要两个参数。第一个参数是一个字符串,第二个参数是该函数用来拆分字符串的分隔字符。

例 - 使用单个分隔字符拆分输入字符串

在本示例中,使用 States.StringSplit 对下方的 inputString 进行划分,其中包含一系列以逗号分隔的值:

{ "inputString": "1,2,3,4,5", "splitter": "," }

使用 States.StringSplit 函数并将inputString 定义为第一个参数,将分隔字符 splitter 用作第二个参数:

"array.$": "States.StringSplit($.inputString, $.splitter)"

States.StringSplit 函数返回以下字符串数组作为结果:

{"array": ["1","2","3","4","5"] }
例 - 使用多个分隔字符拆分输入字符串

在本示例中,使用 States.StringSplit 来划分下方的 inputString,其中包含多个分隔字符:

{ "inputString": "This.is+a,test=string", "splitter": ".+,=" }

按如下方式使用 States.StringSplit 函数:

{ "myStringArray.$": "States.StringSplit($.inputString, $.splitter)" }

States.StringSplit 函数返回以下字符串数组作为结果:

{"myStringArray": [ "This", "is", "a", "test", "string" ]}

用于生成唯一标识符的内置函数

States.UUID

使用 States.UUID 内置函数返回使用随机数生成的版本 4 通用唯一标识符 (v4 UUID)。例如,您可以使用此函数调用其他需要 UUID 参数的 Amazon 服务或资源,或者在 DynamoDB 表中插入项目。

调用 States.UUID 函数时不指定任何参数:

"uuid.$": "States.UUID()"

该函数返回一个随机生成的 UUID,如下例所示:

{"uuid": "ca4c1140-dcc1-40cd-ad05-7b4aa23df4a8" }

用于泛型操作的内置函数

States.Format

使用 States.Format 内置函数根据文本值和插值构造字符串。此函数采用一个或多个参数。第一个参数的值必须是字符串,并且可以包含字符序列 {} 的零个或多个实例。内置函数的调用中,其余参数的个数必须与出现的 {} 个数一样多。解释器会返回第一个参数中定义的字符串,每个 {} 都会被内置函数调用中位置对应的参数值替换。

例如,您可以使用以下输入,输入一个人的 name,并在 template 句子中插入其姓名:

{ "name": "Arnav", "template": "Hello, my name is {}." }

使用 States.Format 函数,指定 template 字符串和要插入以代替 {} 字符的字符串:

States.Format('Hello, my name is {}.', $.name)

States.Format($.template, $.name)

对于前面的任何一个输入,States.Format 函数都会返回已完成的字符串:

Hello, my name is Arnav.

内置函数中的预留字符

以下字符是内置函数的预留字符,必须使用反斜杠 ('\') 转义,才会出现在值中:'{}\

如果字符 \ 需要作为值的一部分出现而不用作转义字符,则必须使用反斜杠对其进行转义。以下转义字符序列与内置函数一起使用:

  • 文字字符串 \' 表示 '

  • 文字字符串 \{ 表示 {

  • 文字字符串 \} 表示 }

  • 文字字符串 \\ 表示 \

在 JSON 中,字符串文字值中包含的反斜杠必须使用另一个反斜杠进行转义。JSON 的等效列表是:

  • 转义后的字符串 \\\' 表示 \'

  • 转义后的字符串 \\\{ 表示 \{

  • 转义后的字符串 \\\} 表示 \}

  • 转义后的字符串 \\\\ 表示 \\

注意

如果在内置函数调用字符串中发现了开放的转义反斜杠 \,则解释器将返回运行时错误。