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

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

内部函数

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

在 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 或更高版本,以便能够在工作流程中包含所有内部函数。

数组内部函数

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

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函数在下面找到lookingForinputArray

"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 编码方案对数据进行编码或解码。

注意

这些内部函数目前在 Step Functions 控制台的数据流模拟器中不可用。

States.Base64Encode

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

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

例如,考虑以下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 函数。

此函数使用最多 10,000 个字符的 Base64 编码数据字符串作为其唯一参数进行解码。

例如,给定以下输入:

{"base64": "RGF0YSB0byBlbmNvZGU=" }

您可以使用该States.Base64Decode函数将 base64 字符串解码为人类可读的字符串:

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

States.Base64Decode function将返回以下解码后的数据作为响应:

{"data": "Decoded data" }

哈希计算的内在函数

注意

此内部函数目前在 Step Functions 控制台的数据流模拟器中不可用。

States.Hash

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

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

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

  • MD5

  • SHA-1

  • SHA-256

  • SHA-384

  • SHA-512

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

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

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

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

States.Hash函数返回以下哈希值作为响应:

{"output": "aaff4a450a104cd177d28d18d7485e8cae074b7" }

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

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

注意

这些内部函数目前在 Step Functions 控制台的数据流模拟器中不可用。

States.JsonMerge

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

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

注意

此内部函数目前在 Step Functions 控制台的数据流模拟器中不可用。

例如,您可以使用States.JsonMerge函数合并以下共享密钥的 JSON 数组a

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

你可以将 json1 和 json2 数组指定为States.JsonMerge函数中的输入,将它们合并在一起:

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

States.JsonMerge返回以下合并的 JSON 对象作为结果。在合并的 JSON 对象中outputjson2对象的密钥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 数据的路径。解释器返回一个字符串,该字符串包含表示 Path 指定的数据的 JSON 文本。例如,您可以提供以下 JSON 路径,其中包含转义值:

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

States.JsonToString函数提供包含在以下内容中的数据unescapedJson

States.JsonToString($.unescapedJson)

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

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

数学运算的内在函数

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

注意

这些内部函数目前在 Step Functions 控制台的数据流模拟器中不可用。

States.MathRandom

使用States.MathRandom内部函数返回指定起始数和结束数之间的随机数。例如,您可以使用此函数在两个或多个资源之间分配特定任务。

这个函数有三个参数。第一个参数是起始数字,第二个参数是结束数,最后一个参数控制种子值。种子值参数是可选的。

如果您使用具有相同种子值的此函数,它将返回相同的数字。

重要

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

注意

此内部函数目前在 Step Functions 控制台的数据流模拟器中不可用。

输入验证

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

    如果您为起始数字或结束数参数指定非整数值,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 会将其四舍五入到最接近的整数。

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

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

然后,使用States.MathAdd函数定义value1为起始值,并step将其定义为递增value1的值:

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

States.MathAdd函数将返回以下数字作为响应:

{"value1": 110 }

字符串操作的内在函数

注意

这些内部函数目前在 Step Functions 控制台的数据流模拟器中不可用。

States.StringSplit

可以使用States.StringSplit内部函数将字符串拆分为数组。这个函数有两个参数。第一个参数是字符串,第二个参数是该函数将用于分割字符串的分隔字符。

例如,您可以使用以下内容States.StringSplit来划分inputString,其中包含一系列以逗号分隔的值:

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

使用States.StringSplit函数和 defineinputString 作为第一个参数,将分隔字符用splitter作第二个参数:

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

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

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

此内部函数目前在 Step Functions 控制台的数据流模拟器中不可用。

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

注意

此内部函数目前在 Step Functions 控制台的数据流模拟器中不可用。

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.

内部函数中的保留字符

以下字符是为内部函数保留的,如果您希望它们出现在 Value:'{} 和,则必须使用反斜杠 ('\') 进行转义\

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

  • 文字字符串\'表示'

  • 文字字符串\{表示{

  • 文字字符串\}表示}

  • 文字字符串\\表示\

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

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

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

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

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

注意

如果在内部调用字符串中找到开放的转义反斜杠\,则解释器将返回运行时错误。

支持内部函数的字段

下表显示了哪些字段支持每种状态的内部函数。

支持内部函数的字段
State
通过 任务 选择 等待 成功 失败 平行 Map
InputPath
参数
ResultSelector
ResultPath
OutputPath
变量
<Comparison Operator>路径
TimeoutSecondsPath
HeartbeatSecondsPath