翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # Step Functions での JSONPath ステートの組み込み関数 **ステートの管理とデータの変換** [変数を使用したステート間のデータ受け渡し](workflow-variables.md)と [JSONata を使用したデータ変換](transforming-data.md)について説明します。 **警告** 組み込み関数は、**JSONPath** クエリ言語を使用するステートでのみ利用できます。JSONata については、「[Step Functions での JSONata を使用したデータ変換](transforming-data.md)」を参照してください。 Amazon States Language では、複数の組み込み関数 (*intrinsics*) が用意されており、JSONPath を受け入れるフィールドで使用できます。組み込み関数を使用すると、`Task` ステートを使用せずに基本的なデータ処理オペレーションを実行できます。 組み込み関数はプログラミング言語の関数に似ています。組み込み関数が便利なのは、ペイロードビルダーで、JSONPath クエリ言語を使用する `Task` ステートの `Resource` フィールドに出入りするデータを処理するときです。 Amazon States Language では、実行するデータ処理タスクの種類に基づいて、組み込み関数は次のカテゴリに分類されます。 + [配列の組み込み関数](#asl-intrsc-func-arrays) + [データのエンコードとデコードのための組み込み関数](#asl-intrsc-func-data-encode-decode) + [ハッシュ計算用組み込み関数](#asl-intrsc-func-hash-calc) + [JSON データ操作用の組み込み関数](#asl-intrsc-func-json-manipulate) + [数学演算用組み込み関数](#asl-intrsc-func-math-operation) + [String 演算の組み込み関数](#asl-intrsc-func-string-operation) + [一意の ID を生成するための組み込み関数](#asl-intrsc-func-uuid-generate) + [汎用操作用の組み込み関数](#asl-intrsc-func-generic) 組み込み関数を使用するには、次の例に示すとおり、ステートマシン定義のキー値に `.$` を指定する必要があります。 ``` "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))" ``` **組み込み関数に必要な QueryLanguage** 組み込み関数を利用するには、ステートマシンで **JSONPath クエリ言語**を使用する必要があります。 JSONata を使用するステートでは組み込み関数は使用できませんが、JSONata と Step Functions で同等の処理手段が提供されています。 ## 組み込み関数をサポートするフィールド 次の状態は、次のフィールドで組み込み関数をサポートします。 + **Pass 状態**: Parameters + **Task 状態** : Parameters、ResultSelector、Credentials + **Parallel 状態:** Parameters、ResultSelector + **Map 状態 **: Parameters、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 KiB を超えることはできません。 例えば、次の入力配列があるとします。 ``` {"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 KiB を超えることはできません。 例えば、次の入力配列があるとします。 ``` { "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 つの引数を取ります。最初の引数は開始番号、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 番目の引数は関数が文字列を分割するために使用する区切り文字です。 **Example - 単一文字列を使用して入力文字列を分割** この例では、`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"] } ``` **Example - 複数の区切り文字を使用して入力文字列を分割** この例では、`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. ``` ## 組み込み関数の予約文字 次の文字は組み込み関数用に予約されており、値に表示したい場合は、バックスラッシュ ('\$1') を使ってエスケープする必要があります。'\$1\$1、および\$1。 文字 `\` をエスケープ文字として機能させずに値の一部として表示する必要があれば、最初にバックスラッシュをエスケープ文字にする必要があります。組み込み関数では、以下のエスケープ文字シーケンスが使用されます。 + リテラル文字列 `\'` は `'` を表します。 + リテラル文字列 `\{` は `{` を表します。 + リテラル文字列 `\}` は `}` を表します。 + リテラル文字列 `\\` は `\` を表します。 JSON では、文字列リテラル値に含まれるバックスラッシュを別のバックスラッシュでエスケープする必要があります。JSON の同等のリストは次のとおりです。 + エスケープされた文字列 `\\\'` は `\'` を表します。 + エスケープされた文字列 `\\\{` は `\{` を表します。 + エスケープされた文字列 `\\\}` は `\}` を表します。 + エスケープされた文字列 `\\\\` は `\\` を表します。 **注記** オープンエスケープバックスラッシュ `\` が組み込み関数の呼び出し文字列で見つかると、インタープリタはランタイムエラーを返します。 フィールド名に [JsonPath ABNF](https://www.ietf.org/archive/id/draft-ietf-jsonpath-base-21.html#jsonpath-abnf) ルールの `member-name-shorthand` 定義に含まれていない文字が含まれている場合は、組み込み関数の引数として渡される **Path** に角かっこ表記を使用する必要があります。**Path** に `_` 以外の非英数字が含まれている場合は、角かっこ表記を使用する必要があります。例えば、`$.abc.['def ghi']`。