Step Functions 中 JSONPath 狀態的內部函數 - AWS Step Functions

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

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函數在 中尋找lookingForinputArray

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

由於 中存放的值lookingFor包含在 中inputArrayStates.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

此內部函數會傳回指定的索引值。此函數需要兩個引數。第一個引數是值的陣列,第二個引數是要傳回值的陣列索引。

例如,使用下列 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 編碼方案來編碼資料。您可以使用此函數將資料傳遞至其他 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 物件 中outputjson2物件的金鑰 會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 }

若要產生隨機數字,請提供 startend值給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 ABNF 規則member-name-shorthand定義中未包含的任何字元,則必須對傳遞為內部函數引數的路徑使用方括號表示法。如果您的路徑包含非英數字元,除了 之外_,您還必須使用方括號表示法。例如:$.abc.['def ghi']