組み込み関数をサポートするフィールド配列の組み込み関数データのエンコードとデコードのための組み込み関数ハッシュ計算用組み込み関数 JSON データ操作用の組み込み関数数学演算用組み込み関数 String 演算の組み込み関数一意の ID を生成するための組み込み関数汎用操作用の組み込み関数組み込み関数の予約文字

組み込み関数

Amazon States Language には、Task 状態を使用せずに基本的なデータ処理操作を実行するのに役立つ、組み込み関数 がいくつか用意されています。組み込み関数はプログラミング言語の関数に似たコンストラクトです。これらを使用すると、ペイロードビルダーが Task 状態の Resource フィールドに対して送受信されるデータを処理するために使用できます。

Amazon States Language では、実行するデータ処理タスクの種類に基づいて、組み込み関数は次のカテゴリに分類されます。

配列の組み込み関数
データのエンコードとデコードのための組み込み関数
ハッシュ計算用組み込み関数
JSON データ操作用の組み込み関数
数学演算用組み込み関数
String 演算の組み込み関数
一意の ID を生成するための組み込み関数
汎用操作用の組み込み関数

注記

組み込み関数を使用するには、次の例に示すとおり、ステートマシン定義のキー値に　.$ を指定する必要があります。
```
"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 以降を使用していることを確認してください。

組み込み関数をサポートするフィールド

次の表は、どのフィールドが各状態で組み込み関数をサポートするかを示します。

組み込み関数をサポートするフィールド
State
	パス	タスク	選択	待機	成功	失敗	並行	マップ
InputPath
パラメータ	✓	✓					✓	✓
ResultSelector		✓					✓	✓
ResultPath
OutputPath
変数
<Comparison Operator(比較演算子)>Path
TimeoutSecondsPath
Heartbeat secondsPath
認証情報		✓

配列の組み込み関数

配列操作には以下の組み込み関数を使用します。

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)"

この例では、States.ArrayLength は配列の長さを表す次の JSON オブジェクトを返します。


{ "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 組み込み関数を使用して、MIME Base64 エンコーディングスキームに基づいてデータをエンコードします。この関数を使うと、AWS Lambda 関数を使わずにデータを他の AWS サービスに渡すことができます。

この関数は、最大 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 デコーディングスキームに基づいてデータをデコードします。この関数を使うと、Lambda 関数を使わずにデータを他の AWS サービスに渡すことができます。

この関数は、最大 10,000 文字の Base64 エンコード済みデータ文字列を取り、唯一の引数としてデコードします。

例として、次の入力があるとします。


{"base64": "RGF0YSB0byBlbmNvZGU=" }

States.Base64Decode 関数を使用して base64 文字列を人間が読める文字列にデコードできます。


"data.$": "States.Base64Decode($.base64)"

States.Base64Decode function は応答として次のデコード済みデータを返します。


{"data": "Decoded data" }

ハッシュ計算用組み込み関数

States.Hash

States.Hash 組み込み関数を使用して、特定の入力のハッシュ値を計算します。この関数を使うと、Lambda 関数を使わずにデータを他の AWS サービスに渡すことができます。

この関数は 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 オブジェクトを単一オブジェクトにマージします。この関数は 3 つの引数を取ります。最初の 2 つの引数はマージする JSON オブジェクトです。3 番目の引数は false のブール値です。このブール値により、ディープマージモードが有効かどうか決定されます。

現在、Step Functions はシャローマージモードのみをサポートしているため、ブーリアン値を false として指定する必要があります。シャローモードでは、両方の JSON オブジェクトに同じキーが存在する場合、後者のオブジェクトのキーが最初のオブジェクトの同じキーよりも優先されます。さらに、JSON オブジェクト内にネストされたオブジェクトは、シャローマージを使用してもマージされません。

例えば、States.JsonMerge 関数を使用して、キー a を共有する次の JSON オブジェクトをマージできます。


{
   "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 が置き換えられます。また、シャローモードはネストされたオブジェクトのマージをサポートしていないため、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 関数は引数を 1 つのみ取ります。それはエスケープ処理されていない文字列として返される JSON データを含むパスです。インタープリタは、パスで指定されたデータを表す JSON テキストを含む文字列を返します。例えば、エスケープ処理された値を含む次の JSON パスを指定できます。


{
  "unescapedJson": {
     "foo": "bar"
  }
}

unescapedJson 内に含まれるデータを States.JsonToString 関数に提供します。


States.JsonToString($.unescapedJson)

States.JsonToString 関数は以下の応答を返します。


{\"foo\": \"bar\"}

数学演算用組み込み関数

これらの関数を使用して数学演算を実行します。

States.MathRandom

States.MathRandom 組み込み関数を使用して、指定した開始番号 (含む) と終了番号 (含まない) の間の乱数を返します。

この関数を使うと、特定のタスクを 2 つ以上のリソースに配布することができます。

この関数は 3 つの引数を取ります。1 番目の引数は開始番号、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 汎用一意識別子 (v4 UUID) を返します。例えば、この関数を使用して、UUID パラメータを必要とする他の AWS サービスやリソースを呼び出したり、DynamoDB テーブルに項目を挿入したりできます。

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 の同等のリストは次のとおりです。

エスケープされた文字列 \\\' は \' を表します。
エスケープされた文字列 \\\{ は \{ を表します。
エスケープされた文字列 \\\} は \} を表します。
エスケープされた文字列 \\\\ は \\ を表します。

注記

オープンエスケープバックスラッシュ \ が組み込み関数の呼び出し文字列で見つかると、インタープリタはランタイムエラーを返します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ステートマシン構造

[Common State] (共通状態) フィールド