本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Step Functions 中 JSONPath 狀態的內部函數 **管理狀態和轉換資料** 了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md) **警告** 內部函數僅適用於使用 **JSONPath** 查詢語言的狀態。如需 JSONata，請參閱 [在 Step Functions 中使用 JSONata 轉換資料](transforming-data.md)。 Amazon States Language 提供數個內部函數，也稱為*內部*函數，可用於接受 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 的狀態無法使用內部函數；不過，JSONata 和 Step Functions 會提供同等選項。 ## 支援內部函數的欄位 下列狀態支援下列欄位中的內部函數： + **通過狀態**：參數 + **任務狀態**：參數、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`函數來尋找 中的`lookingFor`值`inputArray`： ``` "contains.$": "States.ArrayContains($.inputArray, $.lookingFor)" ``` 由於存放在 中的值`lookingFor`包含在 中`inputArray`， `States.ArrayContains`會傳回下列結果： ``` {"contains": true } ``` **`States.ArrayRange`** 使用`States.ArrayRange`內部 函數來建立新的陣列，其中包含特定範圍的元素。新陣列最多可包含 1000 個元素。 此函數需要三個引數。第一個引數是新陣列的第一個元素，第二個引數是新陣列的最終元素，第三個引數是新陣列中元素之間的增量值。 **輸入驗證** + 您必須為所有引數指定整數值。 如果您為任何引數指定非整數值，Step Functions 會將其四捨五入至最接近的整數。 + 您必須為第三個引數指定非零值。 + 新產生的陣列不能包含超過 1000 個項目。 例如，下列 `States.ArrayRange`函數的使用將建立一個陣列，其第一個值為 1、最終值為 9，且每個項目第一個值與最終值之間的值會增加 2： ``` "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 函數。 此函數最多需要 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 解碼結構描述來解碼資料。您可以使用此函數將資料傳遞至其他 AWS 服務，而無需使用 Lambda 函數。 此函數最多需要 10，000 個字元的 Base64 編碼資料字串，才能解碼為其唯一的引數。 例如，假設有下列輸入： ``` {"base64": "RGF0YSB0byBlbmNvZGU=" } ``` 您可以使用 `States.Base64Decode`函數將 base64 字串解碼為人類可讀取的字串： ``` "data.$": "States.Base64Decode($.base64)" ``` `States.Base64Decode function` 會傳回下列解碼資料以回應： ``` {"data": "Decoded data" } ``` ## 雜湊計算的內部 **`States.Hash`** 使用`States.Hash`內部 函數來計算指定輸入的雜湊值。您可以使用此函數將資料傳遞給其他服務， AWS 而無需使用 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 物件執行基本資料處理操作。 **`States.JsonMerge`** 使用`States.JsonMerge`內部 函數將兩個 JSON 物件合併為單一物件。此函數需要三個引數。前兩個引數是您要合併的 JSON 物件。第三個引數是布林值 `false`。此布林值會判斷是否啟用深度合併模式。 目前，Step Functions 僅支援淺合併模式；因此，您必須將布林值指定為 `false`。在淺模式中，如果兩個 JSON 物件中都存在相同的金鑰，則後者物件的金鑰會覆寫第一個物件中的相同金鑰。此外，當您使用淺合併時，不會合併巢狀在 JSON 物件中的物件。 例如，您可以使用 `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 物件 中`output`，`json2`物件的金鑰 會`a`取代`json1`物件的金鑰 `a`。此外，`a`會捨棄`json1`物件金鑰中的巢狀物件，因為淺層模式不支援合併巢狀物件。 ``` { "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 } ``` 若要產生隨機數字，請將 `start`和 `end`值提供給`States.MathRandom`函數： ``` "random.$": "States.MathRandom($.start, $.end)" ``` `States.MathRandom` 函數會傳回下列隨機數字做為回應： ``` {"random": 456 } ``` **`States.MathAdd`** 使用 `States.MathAdd` 內部函數來傳回兩個數字的總和。例如，您可以使用此函數來增加迴圈內的值，而無需叫用 Lambda 函數。 **輸入驗證** + 您必須為所有引數指定整數值。 如果您為一個或兩個引數指定非整數值，Step Functions 會將其四捨五入至最接近的整數。 + 您必須指定 -2147483648 和 2147483647 範圍內的整數值。 例如，您可以使用下列值從 111 中減去一個值： ``` { "value1": 111, "step": -1 } ``` 然後，使用`value1`定義為起始值的 `States.MathAdd` 函數，以及`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 ABNF](https://www.ietf.org/archive/id/draft-ietf-jsonpath-base-21.html#jsonpath-abnf) 規則`member-name-shorthand`定義中未包含的任何字元，您必須對傳遞為內部函數引數的**路徑**使用方括號表示法。如果您的**路徑**包含非英數字元，除了 之外`_`，您還必須使用方括號表示法。例如 `$.abc.['def ghi']`。