本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Step Functions 中 JSONPath 状态的内在函数 **管理状态和转换数据** 了解有关[使用变量在状态之间传递数据](workflow-variables.md)和[使用转换数据](transforming-data.md)的信息 JSONata。 **警告** 内部函数仅适用于使用**JSONPath**查询语言的州。有关信息 JSONata，请参阅[在 Step Functi JSONata ons 中使用转换数据](transforming-data.md)。 Amazon States 语言提供了几个内部函数，也称为*内在函数，用于*接受的字段。 JSONPath使用内置函数，您可以在不使用 `Task` 状态的情况下执行基本的数据处理操作。 内置函数看起来与编程语言中的函数相似。它们可以用来帮助有效载荷生成器处理来自使用 JSONPath 查询语言的`Task`状态`Resource`字段的数据。 在 Amazon States Language 中，根据您要执行的数据处理任务的类型，将内置函数分为以下类别： + [数组的内置函数](#asl-intrsc-func-arrays) + [用于数据编码和解码的内置函数](#asl-intrsc-func-data-encode-decode) + [用于哈希计算的内置函数](#asl-intrsc-func-hash-calc) + [用于 JSON 数据操作的内置函数](#asl-intrsc-func-json-manipulate) + [用于数学运算的内置函数](#asl-intrsc-func-math-operation) + [用于字符串操作的内置函数](#asl-intrsc-func-string-operation) + [用于生成唯一标识符的内置函数](#asl-intrsc-func-uuid-generate) + [用于泛型操作的内置函数](#asl-intrsc-func-generic) 要使用内置函数，您必须在状态机定义的键值中指定 `.$`，如以下示例所示： ``` "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))" ``` **QueryLanguage 内部函数所必需的** 要使用内部函数，状态机必须使用**JSONPath查询**语言。 使用的状态 JSONata 不能使用内部函数；但是，Step Function JSONata s 提供了等效的选项。 ## 支持内置函数的字段 以下状态在下面的字段中支持内置函数： + **Pass 状态**：Parameters + **任务状态**：参数、 ResultSelector、凭证 + **并行状态**：参数， ResultSelector + **地图状态**：参数， ResultSelector ## 数组的内置函数 使用以下内置函数来执行数组操作。 **`States.Array`** `States.Array` 内置函数采用零个或多个参数。解释器返回一个 JSON 数组，其中包含按提供的顺序排列的参数值。例如，给定以下输入： ``` { "Id": 123456 } ``` 您可以使用 ``` "BuildId.$": "States.Array($.Id)" ``` 返回以下响应：`` ``` “BuildId”: [123456] ``` **`States.ArrayPartition`** 使用 `States.ArrayPartition` 内置函数对大型数组进行分区。您也可以使用这个内置函数对数据进行切片，然后将有效负载分成较小的区块发送。 这个内置函数需要两个参数。第一个参数是一个数组，而第二个参数定义了区块大小。解释器将输入数组分成多个数组，其大小由区块大小指定。如果数组中剩余的项目数小于区块大小，则最后一个数组区块的长度可能小于之前的数组区块的长度。 **输入验证** + 必须指定一个数组作为函数第一个参数的输入值。 + 必须为代表区块大小值的第二个参数指定一个非零的正整数。 如果您为第二个参数指定了非整数值，Step Functions 会将其四舍五入为最接近的整数。 + 输入数组不能超过 Step Functions 的有效载荷大小限制，即 256 KiB。 例如，给定以下输入数组： ``` {"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 KiB。 例如，给定以下输入数组： ``` { "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`** 此内置函数返回指定索引的值。这个函数需要两个参数。第一个参数是值数组，第二个参数是要返回的值的数组索引。 例如，使用以下 `inputArray` 和 `index` 值： ``` { "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 编码方案对数据进行编码。您可以使用此函数将数据传递给其他 AWS 服务，而无需使用 AWS 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 解码方案对数据进行解码。您可以使用此函数将数据传递给其他 AWS 服务，而无需使用 Lambda 函数。 此函数将最多 1 万个字符的 Base64 编码数据字符串作为其唯一参数进行解码。 例如，给定以下输入： ``` {"base64": "RGF0YSB0byBlbmNvZGU=" } ``` 您可以使用 `States.Base64Decode` 函数将 base64 字符串解码为便于阅读的字符串： ``` "data.$": "States.Base64Decode($.base64)" ``` `States.Base64Decode function` 会返回以下解码数据： ``` {"data": "Decoded data" } ``` ## 用于哈希计算的内置函数 **`States.Hash`** 使用 `States.Hash` 内置函数计算给定输入的哈希值。您可以使用此函数将数据传递给其他 AWS 服务，而无需使用 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` 函数提供 `start` 和 `end` 值： ``` "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` 为起始值，`step` 为 `value1` 的增量值： ``` "value1.$": "States.MathAdd($.value1, $.step)" ``` `States.MathAdd` 函数将在响应中返回下面的数字。 ``` {"value1": 110 } ``` ## 用于字符串操作的内置函数 **`States.StringSplit`** 使用 `States.StringSplit` 内置函数将字符串拆分成一个值数组。这个函数需要两个参数。第一个参数是一个字符串，第二个参数是该函数用来拆分字符串的分隔字符。 **Example - 使用单个分隔字符拆分输入字符串** 在本示例中，使用 `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"] } ``` **Example - 使用多个分隔字符拆分输入字符串** 在本示例中，使用 `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 参数的 AWS 服务或资源，或者在 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. ``` ## 内置函数中的预留字符 以下字符是内置函数的预留字符，必须使用反斜杠 ('\$1') 转义，才会出现在值中：'\$1\$1 和 \$1。 如果字符 `\` 需要作为值的一部分出现而不用作转义字符，则必须使用反斜杠对其进行转义。以下转义字符序列与内置函数一起使用： + 文字字符串 `\'` 表示 `'`。 + 文字字符串 `\{` 表示 `{`。 + 文字字符串 `\}` 表示 `}`。 + 文字字符串 `\\` 表示 `\`。 在 JSON 中，字符串文字值中包含的反斜杠必须使用另一个反斜杠进行转义。JSON 的等效列表是： + 转义后的字符串 `\\\'` 表示 `\'`。 + 转义后的字符串 `\\\{` 表示 `\{`。 + 转义后的字符串 `\\\}` 表示 `\}`。 + 转义后的字符串 `\\\\` 表示 `\\`。 **注意** 如果在内置函数调用字符串中发现了开放的转义反斜杠 `\`，则解释器将返回运行时错误。 如果字段名包含任何未包含在 [JsonPath AB](https://www.ietf.org/archive/id/draft-ietf-jsonpath-base-21.html#jsonpath-abnf) NF 规则`member-name-shorthand`定义中的字符，则必须对作为参数传递给内部函数的 P **ath** 使用方括号表示法。如果**路径**包含除 `_` 之外的非字母数字字符，则必须使用方括号表示法。例如 `$.abc.['def ghi']`。