翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Step Functions での JSONata を使用したデータ変換
JSONata を使用すると、強力なオープンソースのクエリおよび式言語を利用して、ワークフロー内のデータを**選択**して**変換**できます。JSONata の簡単な概要と完全なリファレンスについては、[JSONata.org のドキュメント](https://docs.jsonata.org/overview.html)を参照してください。
**サポートされている JSONata バージョン**
Step Functions は JSONata バージョン 2.0.6 をサポートしています。
次のビデオでは、Step Functions の変数と JSONata を DynamoDB の例で説明しています。
既存のワークフローで JSONata のクエリおよび変換言語を使用するには、明示的に設定する必要があります。コンソールでワークフローを作成するときは、ステートマシンのトップレベル `QueryLanguage` に JSONata を選択することをお勧めします。JSONPath を使用する既存のワークフローまたは新しいワークフローを対象に、コンソールでは個々のステートを JSONata に変換するオプションが用意されています。
JSONata を選択すると、ワークフローフィールドの JSONPath フィールドは 5 つ (`InputPath`、`Parameters`、`ResultSelector`、`ResultPath`、`OutputPath`) から 2 つ (`Arguments` と `Output` のみ) に減ります。また、JSON オブジェクトのキー名に `.$` を使用することが**なくなります**。
Step Functions を初めて使用する場合は、JSONata の式が次の構文で記述されることだけを知っておけば十分です。
**JSONata 構文:** `"{% %}"`
次のコードサンプルは、JSONPath から JSONata への変換を示しています。
```
# Original sample using JSONPath
{
"QueryLanguage": "JSONPath", // Set explicitly; could be set and inherited from top-level
"Type": "Task",
...
"Parameters": {
"static": "Hello",
"title.$": "$.title",
"name.$": "$customerName", // With $customerName declared as a variable
"not-evaluated": "$customerName"
}
}
```
```
# Sample after conversion to JSONata
{
"QueryLanguage": "JSONata", // Set explicitly; could be set and inherited from top-level
"Type": "Task",
...
"Arguments": { // JSONata states do not have Parameters
"static": "Hello",
"title": "{% $states.input.title %}",
"name": "{% $customerName %}", // With $customerName declared as a variable
"not-evaluated": "$customerName"
}
}
```
入力が `{ "title" : "Doctor" }` で、変数 `customerName` に `"María"` を割り当てた場合、どちらのステートマシンも次の JSON 結果を生成します。
```
{
"static": "Hello",
"title": "Doctor",
"name": "María",
"not-evaluated": "$customerName"
}
```
次の図では、JSONPath (左) から JSONata (右) への変換により、ステートマシン内のステップ構造が簡素化される方法を示しています。
(オプション) ステートの入力からのデータを選択・変換し、**Arguments** に入れて、統合されたアクションに渡すことができます。JSONata を使用すると、(オプションで) アクションからの**結果**を選択・変換して、変数への割り当てやステートの **Output** に使用できます。
注: **Assign** と **Output** のステップは**並列**で実行されます。変数の割り当て中にデータを変換した場合、その変換されたデータは Output ステップでは**使用できません**。Output ステップで JSONata 変換を再適用する必要があります。
## QueryLanguage フィールド
ワークフローの ASL 定義では、ステートマシンのトップレベルと個々のステートに `QueryLanguage` フィールドがあります。個々のステート内で `QueryLanguage` を設定することで、ステートマシン全体を一度にアップグレードするのではなく、既存のステートマシンに JSONata を段階的に導入できます。
`QueryLanguage` フィールドは `"JSONPath"` または `"JSONata"` に設定できます。トップレベルの `QueryLanguage` フィールドは省略された場合、デフォルトで `"JSONPath"` になります。ステートにステートレベルの `QueryLanguage` フィールドが含まれている場合は、そのステートに指定されたクエリ言語が使用されます。ステートに `QueryLanguage` フィールドが含まれていない場合は、トップレベルの `QueryLanguage` フィールドで指定されたクエリ言語が使用されます。
## JSON 文字列での JSONata 式の記述
ASL フィールドの値、JSON オブジェクトのフィールド、または JSON 配列要素内の文字列が `{% %}` 文字で囲まれている場合、その文字列は JSONata として評価されます。このとき、文字列は `{%` で始まり (先頭に空白を含まない)、`%}` で終わる (末尾に空白を含まない) 必要があります。式の開始・終了が正しくないと、検証エラーになります。
例:
+ `"TimeoutSeconds" : "{% $timeout %}"`
+ `Task` ステート内の `"Arguments" : {"field1" : "{% $name %}"}` フィールド
+ `Map` ステート内の `"Items": [1, "{% $two %}", 3]` フィールド
すべての ASL フィールドが JSONata を受け入れるわけではありません。例えば、各ステートの `Type` フィールドは定数文字列に設定する必要があります。同様に、`Task` ステートの `Resource` フィールドは定数文字列である必要があります。`Map` 状態`Items`フィールドは、JSON 配列、JSON オブジェクト、または配列またはオブジェクトに対して評価する必要がある JSONata 式を受け入れます。
## 予約変数: $states
Step Functions は、 という 1 ** `$states` **つの予約変数を定義します。JSONata のステートでは、次の構造が JSONata の式用に `$states` に割り当てられます。
```
# Reserved $states variable in JSONata states
$states = {
"input": // Original input to the state
"result": // API or sub-workflow's result (if successful)
"errorOutput": // Error Output (only available in a Catch)
"context": // Context object
}
```
状態エントリでは、Step Functions は状態入力を ** `$states.input` **に割り当てます。`$states.input` の値は、JSONata 式を受け入れるすべてのフィールドで使用できます。`$states.input` は常にステートの入力の元の値を参照します。
`Task`、`Parallel`、および `Map` ステートの場合:
+ ** `$states.result` ** は、成功した場合の API またはサブワークフローの raw 結果を参照します。
+ ** `$states.errorOutput` ** は、API またはサブワークフローが失敗した場合のエラー出力を参照します。
`$states.errorOutput` は `Catch` フィールドの `Assign` または `Output` で使用できます。
アクセスできないステートやフィールドで `$states.result` や `$states.errorOutput` にアクセスしようとすると、ステートマシンの作成、更新、検証時にキャッチされます。
`$states.context` オブジェクトは、`StartTime`、タスクトークン、初期ワークフロー入力など、特定の実行に関する情報をワークフローに提供します。詳細については、[Step Functions の Context オブジェクトから実行データにアクセスする](input-output-contextobject.md)「」を参照してください。
## 式エラーの処理
実行時に、JSONata 式の評価は次のようなさまざまな理由で失敗することがあります。
+ **型エラー** – `{% $x + $y %}` などの式は、`$x` または `$y` が数値でないと失敗します。
+ **型の非互換** – 式は、フィールドで受け入れられない型に評価されると失敗します。例えば、フィールド `TimeoutSeconds` は数値入力を必要とするため、式 `{% $timeout %}` は、`$timeout` が文字列を返すと失敗します。
+ **範囲外の値** – 式は、フィールドの受け入れ範囲外の値を生成すると失敗します。例えば、`{% $evaluatesToNegativeNumber %}` などの式は `TimeoutSeconds` フィールドでは失敗します。
+ **結果が返されない** – JSON は未定義の値の式を表現できないため、式 `{% $data.thisFieldDoesNotExist %}` はエラーになります。
+ **メモリ制限を超えました** - 評価中に大量のメモリを消費する JSONata 式は`Expression evaluation memory limit exceeded`エラーで失敗します。これは、大量のデータを処理または変換する式で発生する可能性があります。この制限を回避するには、データ変換を Lambda 関数に移動することを検討してください。
+ **式タイムアウト** - 評価に 1 秒以上かかる JSONata 式は`Expression evaluation timeout`エラーで失敗します。これは、無限ループまたは非常に高価なオペレーションを含む式で発生する可能性があります。
+ **スタックオーバーフロー** - 最大再帰深度を超える JSONata 式は、 で失敗します`Stack overflow error`。再帰が終了していない場合は、関数に正しいベースケースまたは終了条件があることを確認してください。再帰が終了しても呼び出しスタックが深すぎる場合は、スタックの深さを減らすために関数をテール再帰として書き換えることを検討してください。
いずれの場合も、インタープリタはエラー `States.QueryEvaluationError` をスローします。Task、Map、および Parallel ステートでは、`Catch` フィールドでエラーをキャッチし、`Retry` フィールドでエラー時の再試行処理を行うことができます。
## JSONPath から JSONata への変換
以降のセクションでは、JSONPath と JSONata で記述されたコードの違いを比較・説明します。
### Path フィールドの廃止
ASL では、JSONPath を使用する場合、ステートデータから値を選択するために、`TimeoutSecondsPath` などのフィールドの `Path` バージョンを使用する必要がありました。JSONata を使用するとき、`Path` フィールドはもう使用しません。ASL が `TimeoutSeconds` などの非 Path フィールド内の `{% %}` で囲まれた JSONata 式を自動的に解釈するためです。
+ JSONPath のレガシー例: `"TimeoutSecondsPath": "$timeout"`
+ JSONata: `"TimeoutSeconds": "{% $timeout %}"`
同様に、 `Map`状態`ItemsPath`は、JSON 配列、JSON オブジェクト、または配列またはオブジェクトに対して評価する必要がある JSONata 式を受け入れる `Items`フィールドに置き換えられました。
### JSON オブジェクト
ASL では、`Parameters` および `ResultSelector` フィールド値の JSONPath 式を含むことができる JSON オブジェクトを表現するために、*ペイロードテンプレート* という用語を使用していました。ASL では、JSONata に対してペイロードテンプレートという用語を使用しません。JSONata の評価は、文字列が単独で出現するか、JSON オブジェクトまたは JSON 配列内で出現するかにかかわらず、すべての文字列に対して行われるためです。
### .$ の廃止
ASL では、JSONPath と組み込み関数を使用するために、ペイロードテンプレートのフィールド名に「`.$`」を付加する必要がありました。`"QueryLanguage":"JSONata"` を指定する場合、「`.$`」の記法はもう使用しません。代わりに、JSONata 式を `{% %}` 文字で囲みます。この記法は、オブジェクトや配列の階層が深くても、すべての文字列値に適用されます。
### Arguments フィールドと Output フィールド
`QueryLanguage` を `JSONata` に設定すると、従来の I/O 処理フィールド (`InputPath`、`Parameters`、`ResultSelector`、`ResultPath`、`OutputPath`) は無効になり、ほとんどのステートに `Arguments` と `Output` という 2 つの新しいフィールドが使用されるようになります。
JSONata では、これらの新しいフィールドを使用することで、JSONPath で使用されるフィールドよりも簡潔に I/O 処理を行うことができます。JSONata の機能により、`Arguments` と `Output` は、JSONPath での従来の 5 つのフィールドよりも柔軟に使用できます。これらのフィールド名により ASL の記述が簡素化され、値の受け渡しの処理モデルが明確になります。
`Arguments` および `Output` フィールド (および `ItemSelector` ステートの `Map` などの類似フィールド) では、次のような JSON オブジェクトを受け入れます。
```
"Arguments": {
"field1": 42,
"field2": "{% jsonata expression %}"
}
```
または、JSONata 式を直接使用することもできます。例:
```
"Output": "{% jsonata expression %}"
```
Output は、あらゆる型の JSON 値を受け入れることもできます。例: `"Output":true`、`"Output":42`。
`Arguments` および `Output` フィールドは JSONata 専用であるため、JSONPath を使用するワークフローで使用することはできません。逆に、`InputPath`、`Parameters`、`ResultSelector`、`ResultPath`、`OutputPath` などの JSONPath フィールドは JSONPath 専用であるため、JSONata をトップレベルのワークフローまたはステートのクエリ言語として用いている場合は使用できません。
### Pass ステート
Pass ステートでのオプションの **Result** は、以前は仮想タスクの *Output* として扱われていました。ワークフローまたはステートのクエリ言語として JSONata を選択すると、新しい **Output** フィールドを使用できるようになりました。
### Choice ステート
JSONPath を使用する場合、Choice ステートには入力 `Variable` と、次の `NumericLessThanEqualsPath` ような多数の比較パスがあります。
```
# JSONPath choice state sample, with Variable and comparison path
"Check Price": {
"Type": "Choice",
"Default": "Pause",
"Choices": [
{
"Variable": "$.current_price.current_price",
"NumericLessThanEqualsPath": "$.desired_price",
"Next": "Send Notification"
} ],
}
```
JSONata では、Choice ステートには `Condition` があり、そこで JSONata 式を使用できます。
```
# Choice state after JSONata conversion
"Check Price": {
"Type": "Choice",
"Default": "Pause"
"Choices": [
{
"Condition": "{% $current_price <= $states.input.desired_priced %}",
"Next": "Send Notification"
} ]
```
注: 変数と比較フィールドは、JSONPath でのみ使用できます。Condition は JSONata でのみ使用できます。
## JSONata の例
次の例は Workflow Studio で作成し、JSONata を試すために使用できます。ステートマシンを作成して実行することも、**Test ステート**を使用してデータを渡したり、ステートマシン定義を編集したりすることもできます。
### 例: Input と Output
この例では、JSONata を明示的に有効にするときに、`$states.input` を使用してステートの入力を取得し、`Output` フィールドを使用してステートの出力を指定する方法を示しています。
```
{
"Comment": "Input and Output example using JSONata",
"QueryLanguage": "JSONata",
"StartAt": "Basic Input and Output",
"States": {
"Basic Input and Output": {
"QueryLanguage": "JSONata",
"Type": "Succeed",
"Output": {
"lastName": "{% 'Last=>' & $states.input.customer.lastName %}",
"orderValue": "{% $states.input.order.total %}"
}
}
}
}
```
ワークフローを次の入力で実行する場合:
```
{
"customer": {
"firstName": "Martha",
"lastName": "Rivera"
},
"order": {
"items": 7,
"total": 27.91
}
}
```
Test ステートまたはステートマシンの実行結果として、次の JSON 出力が返されます。
```
{
"lastName": "Last=>Rivera",
"orderValue": 27.91
}
```
### 例: JSONata を使用したフィルタリング
JSONata [Path 演算子](https://docs.jsonata.org/path-operators)を使用してデータをフィルタリングできます。例えば、入力として商品のリストがあり、カロリーがゼロの商品のみを処理するとします。次の ASL でステートマシン定義を作成し、続くサンプル入力で `FilterDietProducts` ステートをテストできます。
**JSONata を使用したフィルタリングのためのステートマシン定義**
```
{
"Comment": "Filter products using JSONata",
"QueryLanguage": "JSONata",
"StartAt": "FilterDietProducts",
"States": {
"FilterDietProducts": {
"Type": "Pass",
"Output": {
"dietProducts": "{% $states.input.products[calories=0] %}"
},
"End": true
}
}
}
```
**テスト用のサンプル入力**
```
{
"products": [
{
"calories": 140,
"flavour": "Cola",
"name": "Product-1"
},
{
"calories": 0,
"flavour": "Cola",
"name": "Product-2"
},
{
"calories": 160,
"flavour": "Orange",
"name": "Product-3"
},
{
"calories": 100,
"flavour": "Orange",
"name": "Product-4"
},
{
"calories": 0,
"flavour": "Lime",
"name": "Product-5"
}
]
}
```
**ステートマシンのステップをテストした結果の出力**
```
{
"dietProducts": [
{
"calories": 0,
"flavour": "Cola",
"name": "Product-2"
},
{
"calories": 0,
"flavour": "Lime",
"name": "Product-5"
}
]
}
```
### 例: マップ状態で以前の状態出力を使用する
この例では、JSONata でマップ状態の入力として以前の状態の出力を使用する方法を示します。次のワークフローでは、Pass 状態を使用して項目のリストを含む順序を返すタスクをシミュレートし、Map 状態がその出力から項目配列を選択して反復処理します。
**ステートマシンの定義**
```
{
"Comment": "Example: Using previous state output in a Map state with JSONata",
"QueryLanguage": "JSONata",
"StartAt": "GetOrder",
"States": {
"GetOrder": {
"Type": "Pass",
"Output": {
"orderId": "{% $states.input.orderId %}",
"items": "{% $states.input.items %}"
},
"Next": "ProcessItems"
},
"ProcessItems": {
"Type": "Map",
"Items": "{% $states.input.items %}",
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "CalculateItemTotal",
"States": {
"CalculateItemTotal": {
"Type": "Pass",
"Output": {
"name": "{% $states.input.name %}",
"total": "{% $states.input.price * $states.input.quantity %}"
},
"End": true
}
}
},
"End": true
}
}
}
```
この定義では、 `GetOrder`状態は順序データを変更せずに出力します。Map `ProcessItems`状態は、 `"Items": "{% $states.input.items %}"`を使用して の出力から`items`配列を選択します`GetOrder`。各反復は配列から 1 つの項目を受け取り、価格に数量を掛けて項目の合計を計算します。
**入力例**
```
{
"orderId": "ORD-1234",
"items": [
{
"name": "Widget",
"price": 4.99,
"quantity": 3
},
{
"name": "Gadget",
"price": 12.50,
"quantity": 2
},
{
"name": "Bolt",
"price": 0.75,
"quantity": 10
}
]
}
```
**予想される出力**
```
[
{
"name": "Widget",
"total": 14.97
},
{
"name": "Gadget",
"total": 25
},
{
"name": "Bolt",
"total": 7.5
}
]
```
### 例: 並列状態出力のフラット化
並列状態を使用すると、各要素が 1 つのブランチの出力である配列が返されます。JSONata では、並列状態の `Output`フィールドを使用して、これらの結果を 1 つのオブジェクトにフラット化またはマージできます。このアプローチは JSONPath `ResultSelector`フィールドを置き換えます。
次の例では、2 つのブランチを持つ並列状態を使用します。各ブランチは、Pass 状態を使用して DynamoDB GetItem 呼び出しをシミュレートします。並列状態は、 `Output`フィールド`$merge($states.result)`で を使用してブランチ結果を 1 つのオブジェクトにマージします。
**ステートマシンの定義**
```
{
"Comment": "Example: Flattening Parallel state output with JSONata",
"QueryLanguage": "JSONata",
"StartAt": "GetOrderAndCustomer",
"States": {
"GetOrderAndCustomer": {
"Type": "Parallel",
"Output": "{% $merge($states.result) %}",
"Branches": [
{
"StartAt": "Get Order",
"States": {
"Get Order": {
"Type": "Pass",
"Output": {
"orderId": "{% $states.input.orderId %}",
"orderDate": "2024-11-20",
"total": 35.99
},
"End": true
}
}
},
{
"StartAt": "Get Customer",
"States": {
"Get Customer": {
"Type": "Pass",
"Output": {
"customerId": "{% $states.input.customerId %}",
"customerName": "Martha Rivera",
"email": "martha@example.com"
},
"End": true
}
}
}
],
"Next": "Done"
},
"Done": {
"Type": "Succeed"
}
}
}
```
**入力例**
```
{
"orderId": "12345",
"customerId": "C-100"
}
```
**予想される出力**
```
{
"orderId": "12345",
"orderDate": "2024-11-20",
"total": 35.99,
"customerId": "C-100",
"customerName": "Martha Rivera",
"email": "martha@example.com"
}
```
`$merge()` 関数は、オブジェクトの配列を 1 つのオブジェクトに結合します。ブランチが重複するキーを持つオブジェクトを返す場合、後の配列要素が優先されます。ブランチ結果は一貫して順序付けられます。ステートマシン定義の`Branches`配列の順序に対応します。
## Step Functions が提供する JSONata 関数
JSONata には、文字列、数値、集計、Boolean、配列、オブジェクト、日時、高階関数のための関数ライブラリが含まれています。Step Functions には、JSONata 式で使用できる追加の JSONata 関数が用意されています。これらの組み込み関数は、Step Functions の組み込み関数の代わりに使用できます。組み込み関数は、JSONPath クエリ言語を使用するステートでのみ使用できます。
注: パラメータとして整数値を必要とする組み込み JSONata 関数は、与えられた整数以外の数値を自動的に切り捨てます。
**$partition** – `States.ArrayPartition` 組み込み関数に相当する JSONata の関数で、大きな配列を分割するために使用します。
最初のパラメータは分割する配列、2 番目のパラメータはチャンクサイズを表す整数です。戻り値は 2 次元配列になります。インタープリタは入力配列をチャンクサイズで指定されたサイズの複数の配列にチャンクします。配列に残っている項目の数がチャンクサイズよりも小さい場合、最後の配列チャンクの長さは前の配列チャンクの長さよりも短くなることがあります。
```
"Assign": {
"arrayPartition": "{% $partition([1,2,3,4], $states.input.chunkSize) %}"
}
```
**$range** – `States.ArrayRange` 組み込み関数に相当する JSONata の関数で、値の配列を生成するために使用します。
この関数は 3 つの引数を取ります。最初の引数は新しい配列の最初の要素を表す整数、2 番目の引数は新しい配列の最後の要素を表す整数、3 番目の引数は新しい配列の要素のデルタ値 (整数) です。戻り値は、関数の最初の引数から 2 番目の引数までの範囲で、デルタ値に従って並べられた要素からなる新しい配列です。デルタ値には正数または負数を指定でき、前の値にそのデルタを加えたり引いたりしながら、終了値に達するか超えるまで値を生成します。
```
"Assign": {
"arrayRange": "{% $range(0, 10, 2) %}"
}
```
**$hash** – `States.Hash` 組み込み関数に相当する JSONata の関数で、指定された入力のハッシュ値を計算するために使用します。
この関数は 2 つの引数を取ります。最初の引数はハッシュ対象のソース文字列です。2 番目の引数はハッシュ計算に使用するハッシュアルゴリズムを表す文字列です。ハッシュアルゴリズムには、`"MD5"`、`"SHA-1"`、`"SHA-256"`、`"SHA-384"`、`"SHA-512"` のいずれかの値を指定する必要があります。戻り値は、データの計算されたハッシュの文字列です。
JSONata がネイティブでハッシュの計算機能をサポートしていないため、この関数が追加されました。
```
"Assign": {
"myHash": "{% $hash($states.input.content, $hashAlgorithmName) %}"
}
```
**$random** – `States.MathRandom` 組み込み関数に相当する JSONata の関数で、ランダムな数値 n (`0 ≤ n < 1`) を返します。
この関数は、乱数関数のシード値を表す*オプションの*整数引数を取ります。この関数を同じシード値で使用すると、同じ数が返されます。
組み込みの JSONata 関数 [https://docs.jsonata.org/numeric-functions#random](https://docs.jsonata.org/numeric-functions#random) がシード値を受け入れないため、このオーバーロードされた関数が追加されました。
```
"Assign": {
"randNoSeed": "{% $random() %}",
"randSeeded": "{% $random($states.input.seed) %}"
}
```
**$uuid** – `States.UUID` 組み込み関数に相当する JSONata の関数。
この関数は引数を取りません。この関数は v4 UUID を返します。
JSONata がネイティブで UUID を生成する機能をサポートしていないため、この関数が追加されました。
```
"Assign": {
"uniqueId": "{% $uuid() %}"
}
```
**$parse** – JSON 文字列を逆シリアル化する JSONata 関数。
この関数は、JSON 形式の文字列を唯一の引数として取ります。
JSONata は `$eval` を通じてこの機能をサポートしていますが、`$eval` は Step Functions のワークフローではサポートされていません。
```
"Assign": {
"deserializedPayload": "{% $parse($states.input.json_string) %}"
}
```