本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
Step Functions 中 JSONPath 狀態的內部函數
管理狀態和轉換資料
警告
內部函數僅適用於使用 JSONPath 查詢語言的狀態。如需 JSONata,請參閱 在 Step Functions 中使用 JSONata 轉換資料。
Amazon States Language 提供數個內部函數,也稱為內部函數,可用於接受 JSONPath 的欄位。透過內部,您可以執行基本資料處理操作,而無需使用 Task
狀態。
內部看起來類似於程式設計語言中的 函數。它們可用來協助承載建置器處理進出使用 JSONPath 查詢語言之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))"
內部函數所需的 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
內部 函數將字串分割為 值陣列。此函數需要兩個引數。第一個引數是字串,第二個引數是函數用來分割字串的分隔字元。範例 - 使用單一分隔字元分割輸入字串
在此範例中,使用
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 參數 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.
內部函數中的預留字元
下列字元會保留給內部函數使用,如果您希望它們出現在值中,則必須以反斜線 ('\') 逸出:'{}、 和 \。
如果角色\
需要顯示為值的一部分,而不充當逸出字元,您必須以反斜線逸出它。下列逸出字元序列會與內部函數搭配使用:
常值字串
\'
代表'
。常值字串
\{
代表{
。常值字串
\}
代表}
。常值字串
\\
代表\
。
在 JSON 中,字串常值中包含的反斜線必須以另一個反斜線逸出。JSON 的同等清單為:
-
逸出字串
\\\'
代表\'
。 -
逸出字串
\\\{
代表\{
。 -
逸出字串
\\\}
代表\}
。 -
逸出字串
\\\\
代表\\
。
注意
如果在內部調用字串\
中找到開啟的逸出反斜線,解譯器將傳回執行期錯誤。
如果欄位名稱包含 JsonPath ABNFmember-name-shorthand
定義中未包含的任何字元,則必須對傳遞為內部函數引數的路徑使用方括號表示法。如果您的路徑包含非英數字元,除了 之外_
,您還必須使用方括號表示法。例如:$.abc.['def ghi']
。