Step Functions ワークフローの Amazon States Language の組み込み関数 - AWS Step Functions

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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オブジェクト ではoutputjson2オブジェクトのキー が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 関数に startend の値を指定します。

"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 ABNFルールmember-name-shorthandの定義に含まれていない文字が含まれている場合、組み込み関数に引数として渡されるパスには角括弧表記を使用する必要があります。パスに 以外の英数字が含まれている_場合は、角括弧表記を使用する必要があります。例えば、$.abc.['def ghi'] と指定します。