翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
Step Functions ワークフローの Amazon States Language の組み込み関数
Amazon States Language には、Task
状態を使用せずに基本的なデータ処理操作を実行するのに役立つ、組み込み関数 がいくつか用意されています。組み込み関数はプログラミング言語の関数に似たコンストラクトです。これらを使用すると、ペイロードビルダーが Task
状態の Resource
フィールドに対して送受信されるデータを処理するために使用できます。
Amazon States Language では、実行するデータ処理タスクの種類に基づいて、組み込み関数は次のカテゴリに分類されます。
注記
組み込み関数を使用するには、次の例に示すとおり、ステートマシン定義のキー値に
.$
を指定する必要があります。"KeyId.$": "
States.Array
($.Id)"ワークフローの 1 つのフィールドには、最大 10 個の組み込み関数をネストできます。次の例は、9 つのネストされた組み込み関数を含む
という名前のフィールドを示しています。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
組み込み関数をサポートするフィールド
次の状態は、次のフィールドで組み込み関数をサポートします。
-
パス状態: パラメータ
-
タスク状態: パラメータ ResultSelector、、認証情報
-
並列状態: パラメータ、 ResultSelector
-
マップ状態: パラメータ、 ResultSelector
配列の組み込み関数
配列操作には以下の組み込み関数を使用します。
States.Array
-
States.Array
組み込み関数は 0 以上の引数を取ります。インタープリタは、指定された順序で引数の値を含むJSON配列を返します。例として、次の入力があるとします。{ "Id": 123456 }
以下を使用できます
"BuildId.$": "States.Array($.Id)"
これに対して
が返されます。
“BuildId”: [123456]
States.ArrayPartition
-
States.ArrayPartition
組み込み関数を使用して大きな配列を分割します。この組み込み関数を使用しデータをスライスしてから、ペイロードを小さなチャンクに分けて送信することもできます。この組み込み関数は 2 つの引数を取ります。1 番目の引数は配列で、2 番目の引数はチャンクサイズを定義します。インタープリタは入力配列をチャンクサイズで指定されたサイズの複数の配列にチャンクします。配列に残っている項目の数がチャンクサイズよりも小さい場合、最後の配列チャンクの長さは前の配列チャンクの長さよりも短くなることがあります。
入力の検証
-
関数の 1 番目の引数の入力値として配列を指定する必要があります。
-
チャンクサイズ値を表す 2 番目の引数には、0 以外の正の整数を指定する必要があります。
2 番目の引数に整数以外の値を指定すると、Step Functions はその値を最も近い整数に四捨五入します。
-
入力配列は Step Functions のペイロードサイズ制限である 256 KB を超えることはできません。
例えば、次の入力配列があるとします。
{"inputArray": [1,2,3,4,5,6,7,8,9] }
States.ArrayPartition
関数を使用して、配列を次の 4 つの値のチャンクに分割できます。"inputArray.$": "States.ArrayPartition($.inputArray,4)"
この場合、次のような配列チャンクが返されます。
{"inputArray": [ [1,2,3,4], [5,6,7,8], [9]] }
前の例では、
States.ArrayPartition
関数は 3 つの配列を出力します。最初の 2 つの配列にはそれぞれ、チャンクサイズで定義される 4 つの値が含まれます。3 番目の配列には残りの値が含まれ、定義されたチャンクサイズよりも小さくなっています。 -
States.ArrayContains
-
States.ArrayContains
組み込み関数を使用して、配列に特定の値が存在するかどうかを判断します。例えば、この関数を使用してMap
状態反復でエラーが発生したかどうかを検出できます。この組み込み関数は 2 つの引数を取ります。1 番目の引数は配列で、2 番目の引数は配列内で検索される値です。
入力の検証
-
関数の 1 番目の引数の入力値として配列を指定する必要があります。
2 番目の引数として有効なJSONオブジェクトを指定する必要があります。
-
入力配列は Step Functions のペイロードサイズ制限である 256 KB を超えることはできません。
例えば、次の入力配列があるとします。
{ "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 個の要素を含めることができます。この関数は 3 つの引数を取ります。1 番目の引数は新しい配列の 1 番目の要素、2 番目の引数は新しい配列の最後の要素、3 番目の引数は新しい配列の要素間の増分値です。
入力の検証
-
すべての引数に整数値を指定する必要があります。
いずれかの引数に整数以外の値を指定すると、Step Functions はその値を最も近い整数に四捨五入します。
-
3 つ目の引数には 0 以外の値を指定する必要があります。
-
新しく生成された配列には 1000 個を超える項目を含めることはできません。
例えば、
States.ArrayRange
関数を次のように使用すると、最初の値が 1、最後の値が 9 の配列が作成され、最初の値と最後の値の間の値は、項目ごとに 2 ずつ増加します。"array.$": "States.ArrayRange(1, 9, 2)"
この場合、次のような配列が返されます。
{"array": [1,3,5,7,9] }
-
States.ArrayGetItem
-
この組み込み関数は、指定されたインデックスの値を返します。この関数は 2 つの引数を取ります。1 番目の引数は値の配列で、2 番目の引数は返される値の配列インデックスです。
例えば、次の
inputArray
値およびindex
値を使用します。{ "inputArray": [1,2,3,4,5,6,7,8,9], "index": 5 }
これらの値から、
States.ArrayGetItem
関数を使用して配列内の 5 番目の位置のindex
の値を返すことができます。"item.$": "States.ArrayGetItem($.inputArray, $.index)"
この例では、
States.ArrayGetItem
は次の結果を返します。{ "item": 6 }
States.ArrayLength
-
States.ArrayLength
組み込み関数は配列の長さを返します。1 つの引数を持ち、それは長さを返す配列です。例えば、次の入力配列があるとします。
{ "inputArray": [1,2,3,4,5,6,7,8,9] }
States.ArrayLength
を使用して以下のinputArray
の長さを返すことができます。"length.$": "States.ArrayLength($.inputArray)"
この例では、 は配列の長さを表す次のJSONオブジェクト
States.ArrayLength
を返します。{ "length": 9 }
States.ArrayUnique
-
States.ArrayUnique
組み込み関数は配列から重複する値を削除し、一意の要素のみを含む配列を返します。この関数は 1 つの配列を取りますが、これは唯一の引数であるためソートされません。例えば、次の
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
組み込み関数を使用して、MIMEBase64 エンコードスキームに基づいてデータをエンコードします。この関数を使用して、データを他の に渡すことができます。 AWS を使用しない のサービス AWS Lambda function。この関数は、最大 10,000 文字のデータ文字列を取り、唯一の引数としてエンコードします。
例えば、次の
input
文字列を考えてみます。{"input": "Data to encode" }
States.Base64Encode
関数を使用して、input
文字列を MIME Base64 文字列としてエンコードできます。"base64.$": "States.Base64Encode($.input)"
States.Base64Encode
関数は応答として以下のエンコード済みデータを返します。{"base64": "RGF0YSB0byBlbmNvZGU=" }
States.Base64Decode
-
States.Base64Decode
組み込み関数を使用して、Base64 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 関数を使用しない のサービス。この関数は 2 つの引数を取ります。最初の引数は、ハッシュ値を計算するデータです。2 番目の引数は、ハッシュ計算を行うために使用するハッシュアルゴリズムです。指定するデータは 10,000 文字以下のオブジェクト文字列である必要があります。
指定するハッシュアルゴリズムは、以下のいずれかのアルゴリズムにすることができます。
-
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
組み込み関数を使用して、2 つのJSONオブジェクトを 1 つのオブジェクトにマージします。この関数は 3 つの引数を取ります。最初の 2 つの引数は、マージするJSONオブジェクトです。3 番目の引数は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)"
は、結果として次のマージされたJSONオブジェクト
States.JsonMerge
を返します。マージされたJSONオブジェクト ではoutput
、json2
オブジェクトのキー がjson1
オブジェクトのキー をa
置き換えます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データを含むパスである引数を 1 つだけ受け取ります。インタープリタは、Path で指定されたデータを表すJSONテキストを含む文字列を返します。例えば、エスケープされた値を含む次のJSONパスを指定できます。{ "unescapedJson": { "foo": "bar" } }
unescapedJson
内に含まれるデータをStates.JsonToString
関数に提供します。States.JsonToString($.unescapedJson)
States.JsonToString
関数は以下の応答を返します。{\"foo\": \"bar\"}
数学演算用組み込み関数
これらの関数を使用して数学演算を実行します。
States.MathRandom
-
States.MathRandom
組み込み関数を使用して、指定した開始番号 (含む) と終了番号 (含まない) の間の乱数を返します。この関数を使うと、特定のタスクを 2 つ以上のリソースに配布することができます。
この関数は 3 つの引数を取ります。最初の引数は開始番号、2 番目の引数は終了番号、最後の引数はオプションのシード値を制御します。この関数を同じシード値で使用すると、同じ数値が返されることに注意してください。
重要
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
組み込み関数を使用して、2 つの数の加算結果を返します。例えば、この関数を使用すると、Lambda 関数を呼び出さずにループ内の値をインクリメントできます。入力の検証
-
すべての引数に整数値を指定する必要があります。
いずれかまたは両方の引数に整数以外の値を指定すると、Step Functions はその値を最も近い整数に四捨五入します。
-
-2147483648~2147483647 までの範囲の整数値を指定する必要があります。
例えば、次の値を使用して 111 から 1 を減算することができます。
{ "value1": 111, "step": -1 }
次に、
States.MathAdd
関数を使用してvalue1
を初期値、value1
の増分値をstep
に定義します。"value1.$": "States.MathAdd($.value1, $.step)"
States.MathAdd
関数は応答として次の数を返します。{"value1": 110 }
-
String 演算の組み込み関数
States.StringSplit
-
States.StringSplit
組み込み関数を使用して、文字列を値の配列に分割します。この関数は 2 つの引数を取ります。1 番目の引数は文字列で、2 番目の引数は関数が文字列を分割するために使用する区切り文字です。例 - 単一文字列を使用して入力文字列を分割
この例では、
States.StringSplit
を使用して、カンマで区切られた一連の値を含む、以下のinputString
を分割します。{ "inputString": "1,2,3,4,5", "splitter": "," }
States.StringSplit
を使用して、inputString
を最初の引数、区切り文字splitter
を 2 番目の引数として定義します。"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" ]}
一意の ID を生成するための組み込み関数
States.UUID
-
States.UUID
組み込み関数を使用して、乱数を使用して生成されたバージョン 4 の汎用一意識別子 (v4UUID) を返します。例えば、この関数を使用して他の を呼び出すことができます。 AWS DynamoDB テーブルにUUIDパラメータまたは挿入項目を必要とする サービスまたはリソース。States.UUID
関数は引数を指定せずに呼び出されます。"uuid.$": "States.UUID()"
関数は、次の例のようにUUIDランダムに生成された を返します。
{"uuid": "ca4c1140-dcc1-40cd-ad05-7b4aa23df4a8" }
汎用操作用の組み込み関数
States.Format
-
States.Format
組み込み関数を使用して、リテラル値と補間値の両方から文字列を作成します。この関数は 1 つ以上の引数を取ります。最初の引数の値は文字列である必要があり、文字シーケンス{}
のインスタンスを 0 個以上含めることができます。組み込み関数の呼び出しには、 の出現と同じ数の引数が残っている必要があります{}
。インタープリタは、組み込み関数の呼び出しの際に各{}
を位置対応引数の値に置き換えて、最初の引数で定義された文字列を返します。例えば、次のような個人の
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']
と指定します。