翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
ResultWriter (Map)
状態の管理とデータの変換
変数を使用して状態間でデータを渡す方法と、JSONata を使用してデータを変換する方法について説明します。
ResultWriter フィールドは、分散マップ状態によって開始された子ワークフロー実行の出力結果のオプションを提供する JSON オブジェクトです。出力結果のさまざまな書式設定オプションと Amazon S3 の場所を指定して、エクスポートする場合は保存できます。Step Functions は、デフォルトではこれらの結果をエクスポートしません。
ResultWriter フィールドの内容
ResultWriter フィールドには、次のサブフィールドが含まれます。フィールドの選択によって、出力のフォーマット方法とAmazon S3にエクスポートされるかどうかが決まります。
ResultWriter-
以下の詳細を指定する JSON オブジェクト。
-
ResourceStep Functions が実行結果をエクスポートするために呼び出す Amazon S3 API アクション。
-
Parameters実行出力を保存する Amazon S3 バケット名とプレフィックスを指定する JSON オブジェクト。
-
WriterConfigこのフィールドでは、次のオプションを設定できます。
-
Transformation-
NONE- ワークフローメタデータに加えて、子ワークフロー実行の出力を変更せずに返します。子ワークフロー実行結果を Amazon S3 にエクスポートする場合のデフォルトWriterConfigであり、指定されていません。 -
COMPACT- 子ワークフロー実行の出力を返します。が指定されていない場合ResultWriterのデフォルト。 -
FLATTEN- 子ワークフロー実行の出力を返します。子ワークフロー実行が配列を返す場合、このオプションは、結果を状態出力に返すか、結果を Amazon S3 オブジェクトに書き込む前に、配列をフラット化します。注記
子ワークフローの実行が失敗した場合、Step Functions は実行結果を変更せずに返します。結果は、 を
Transformationに設定した場合と同等ですNONE。
-
-
OutputType-
JSON- 結果を JSON 配列としてフォーマットします。 -
JSONL- 結果を JSON 行としてフォーマットします。
-
-
-
必須フィールドの組み合わせ
ResultWriter フィールドを空にすることはできません。これらのサブフィールドのセットのいずれかを指定する必要があります。
-
WriterConfig- 結果を Amazon S3 に保存せずに、フォーマットされた出力をプレビューします。 -
ResourceおよびParameters- 追加のフォーマットなしで結果を Amazon S3 に保存します。 -
出力をフォーマット
Resourceして Amazon S3Parametersに保存するにはWriterConfig、、、 の 3 つのフィールドすべてを使用します。
設定例と変換出力
以下のトピックでは、 の可能な設定ResultWriterと、さまざまな変換オプションで処理された結果の例を示します。
次の例は、、WriterConfig、 Resources の 3 つのフィールドの可能な組み合わせでの設定を示していますParameters。
WriterConfig のみ
この例では、 WriterConfigフィールドで指定された出力形式と変換を使用して、状態出力をプレビューで表示する方法を設定します。Amazon S3 バケット仕様を提供していたであろう存在しない フィールドResourceと Parametersフィールドは、状態出力リソースを意味します。結果は次の状態に渡されます。
"ResultWriter": { "WriterConfig": { "Transformation": "FLATTEN", "OutputType": "JSON" } }
リソースとパラメータのみ
この例では、状態出力を指定された Amazon S3 バケットにエクスポートします。存在しないWriterConfigフィールドが指定した追加のフォーマットと変換は必要ありません。
"ResultWriter": { "Resource": "arn:aws:states:::s3:putObject", "Parameters": { "Bucket": "amzn-s3-demo-destination-bucket", "Prefix": "csvProcessJobs" }
WriterConfig、パラメータの 3 つのフィールドすべて
この例では、 WriterConfigフィールドの仕様に従って状態出力をフォーマットします。また、 Resourceおよび Parametersフィールドの仕様に従って Amazon S3 バケットにエクスポートします。
"ResultWriter": { "WriterConfig": { "Transformation": "FLATTEN", "OutputType": "JSON" }, "Resource": "arn:aws:states:::s3:putObject", "Parameters": { "Bucket": "amzn-s3-demo-destination-bucket", "Prefix": "csvProcessJobs" } }
これらの例では、各子ワークフロー実行がオブジェクトの配列である出力を返すことを前提としています。
[ { "customer_id": "145538", "order_id": "100000" }, { "customer_id": "898037", "order_id": "100001" } ]
これらの例は、 OutputTypeの を使用して、さまざまなTransformation値のフォーマットされた出力を示していますJSON。
変換なし
これは、NONE変換を使用する場合の処理結果の例です。出力は変更されず、ワークフローメタデータが含まれます。
[ { "ExecutionArn": "arn:aws:states:region:account-id:execution:orderProcessing/getOrders:da4e9fc7-abab-3b27-9a77-a277e463b709", "Input": ..., "InputDetails": { "Included": true }, "Name": "da4e9fc7-abab-3b27-9a77-a277e463b709", "Output": "[{\"customer_id\":\"145538\",\"order_id\":\"100000\"},{\"customer_id\":\"898037\",\"order_id\":\"100001\"}]", "OutputDetails": { "Included": true }, "RedriveCount": 0, "RedriveStatus": "NOT_REDRIVABLE", "RedriveStatusReason": "Execution is SUCCEEDED and cannot be redriven", "StartDate": "2025-02-04T01:49:50.099Z", "StateMachineArn": "arn:aws:states:region:account-id:stateMachine:orderProcessing/getOrders", "Status": "SUCCEEDED", "StopDate": "2025-02-04T01:49:50.163Z" }, ... { "ExecutionArn": "arn:aws:states:region:account-id:execution:orderProcessing/getOrders:f43a56f7-d21e-3fe9-a40c-9b9b8d0adf5a", "Input": ..., "InputDetails": { "Included": true }, "Name": "f43a56f7-d21e-3fe9-a40c-9b9b8d0adf5a", "Output": "[{\"customer_id\":\"169881\",\"order_id\":\"100005\"},{\"customer_id\":\"797471\",\"order_id\":\"100006\"}]", "OutputDetails": { "Included": true }, "RedriveCount": 0, "RedriveStatus": "NOT_REDRIVABLE", "RedriveStatusReason": "Execution is SUCCEEDED and cannot be redriven", "StartDate": "2025-02-04T01:49:50.135Z", "StateMachineArn": "arn:aws:states:region:account-id:stateMachine:orderProcessing/getOrders", "Status": "SUCCEEDED", "StopDate": "2025-02-04T01:49:50.227Z" } ]
変換 COMPACT
これは、COMPACT変換を使用する場合に処理された結果の例です。これは、子ワークフロー実行と元の配列構造を組み合わせた出力であることに注意してください。
[ [ { "customer_id": "145538", "order_id": "100000" }, { "customer_id": "898037", "order_id": "100001" } ], ..., [ { "customer_id": "169881", "order_id": "100005" }, { "customer_id": "797471", "order_id": "100006" } ] ]
変換フラット化
これは、FLATTEN変換を使用する場合の処理結果の例です。これは、1 つの配列にフラット化された子ワークフロー実行配列の組み合わせ出力であることに注意してください。
[ { "customer_id": "145538", "order_id": "100000" }, { "customer_id": "898037", "order_id": "100001" }, ... { "customer_id": "169881", "order_id": "100005" }, { "customer_id": "797471", "order_id": "100006" } ]
Amazon S3 へのエクスポート
重要
Map Run の結果のエクスポートに使用する Amazon S3 バケットが、 AWS リージョン ステートマシンと同じ AWS アカウント および の下であることを確認します。それ以外の場合は、States.ResultWriterFailed エラーが発生してステートマシンの実行が失敗します。
Amazon S3 バケットに結果をエクスポートすると、出力ペイロードサイズが 256 KiB を超える場合に役立ちます。Step Functions は、実行の入出力、ARN、実行状態など、すべての子ワークフローの実行データを統合します。次に、指定した Amazon S3 の場所のそれぞれのファイルに、同じステータスの実行をエクスポートします。
次の例では、JSONPath を使用して、子ワークフロー実行結果をエクスポートParametersするための を持つ ResultWriterフィールドの構文を示しています。この例では、csvProcessJobs というプレフィックス内にある、amzn-s3-demo-destination-bucket という名前のバケットに結果を保存します。
{
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
}
JSONata の状態の場合、 は に置き換えParametersられますArguments。
{
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Arguments": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
}
ヒント
Workflow Studio では、[マップステートの結果を Amazon S3 にエクスポート] を選択すると、子ワークフローの実行結果をエクスポートできます。次に、結果をエクスポートする Amazon S3 バケットの名前とプレフィックスを入力します。
Step Functions には、結果をエクスポートするバケットとフォルダにアクセスするための適切な権限が必要です。必要な IAM ポリシーの詳細については、「ResultWriter の IAM ポリシー」を参照してください。
子ワークフローの実行結果をエクスポートすると、分散マップ状態実行により、マップ実行 ARN と、Amazon S3 のエクスポート場所に関するデータが次の形式で返されます。
{
"MapRunArn": "arn:aws:states:us-east-2:account-id:mapRun:csvProcess/Map:ad9b5f27-090b-3ac6-9beb-243cd77144a7",
"ResultWriterDetails": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Key": "csvProcessJobs/ad9b5f27-090b-3ac6-9beb-243cd77144a7/manifest.json"
}
}
Step Functions は、同じステータスの実行をそれぞれのファイルにエクスポートします。例えば、子ワークフローの実行で 500 件の成功、200 件の失敗の結果が得られた場合、Step Functions は指定された Amazon S3 の場所に成功と失敗の結果用の 2 つのファイルを作成します。この例では、成功結果ファイルには 500 件の成功結果が含まれ、失敗結果ファイルには 200 件の失敗結果が含まれています。
実行を試みると、Step Functions は実行出力に応じて、指定された Amazon S3 の場所に次のファイルを作成します。
-
manifest.json- エクスポート場所、マップ実行 ARN、結果ファイルに関する情報などのマップ実行メタデータが含まれます。マップ実行を redriven した場合、
manifest.jsonファイルには、マップ実行のすべての試行で正常に実行されたすべての子ワークフローへの参照が含まれます。ただし、このファイルには、特定の redrive の実行に失敗した実行と保留中の実行への参照が含まれています。 -
SUCCEEDED_n.json- 正常に実行されたすべての子ワークフローの統合データが含まれます。n はファイルのインデックス番号を表します。インデックス番号は 0 から始まります。例えば、SUCCEEDED_1.json。 -
FAILED_n.json- 失敗した、タイムアウトした、中止された子ワークフローのすべての実行に関する統合データが含まれます。このファイルを使用して、失敗した実行から回復します。n はファイルのインデックスを表します。インデックス番号は 0 から始まります。例えば、FAILED_1.json。 -
PENDING_n.json- マップ実行が失敗または中止されたために開始されなかったすべての子ワークフロー実行の統合データが含まれます。n はファイルのインデックスを表します。インデックス番号は 0 から始まります。例えば、PENDING_1.json。
Step Functions は、最大 5 GB の個別の結果ファイルをサポートします。ファイルサイズが 5 GB を超える場合、Step Functions は残りの実行結果を書き込む別のファイルを作成し、ファイル名にインデックス番号を追加します。例えば、SUCCEEDED_0.json ファイルのサイズが 5 GB を超える場合、Step Functions は残りの結果を記録する SUCCEEDED_1.json ファイルを作成します。
子ワークフロー実行結果をエクスポートするように指定しなかった場合、ステートマシン実行は次の例のように子ワークフロー実行結果の配列を返します。
[
{
"statusCode": 200,
"inputReceived": {
"show_id": "s1",
"release_year": "2020",
"rating": "PG-13",
"type": "Movie"
}
},
{
"statusCode": 200,
"inputReceived": {
"show_id": "s2",
"release_year": "2021",
"rating": "TV-MA",
"type": "TV Show"
}
},
...
]
注記
返される出力サイズが 256 KiB を超える場合、ステートマシンの実行は失敗し、States.DataLimitExceededエラーが返されます。
ResultWriter の IAM ポリシー
Step Functions コンソールでワークフローを作成すると、Step Functions はワークフロー定義内のリソースに基づいて IAM ポリシーを自動的に生成できます。生成されたポリシーには、ステートマシンロールが分散マップ状態の StartExecution API アクションを呼び出し、Amazon S3 バケットやオブジェクト、Lambda 関数などの AWS リソースにアクセスするために必要な最小限の権限が含まれます。
IAM ポリシーに必要な許可のみを含めることをお勧めします。たとえば、ワークフローに分散モードMapの状態が含まれている場合は、データを含む特定の Amazon S3 バケットとフォルダにポリシーの範囲を絞り込みます。
重要
分散マップ状態の入力で、既存のキーと値のペアへの参照パスとともに、Amazon S3 バケットやオブジェクト、またはプレフィックスを指定する場合は、ワークフローの IAM ポリシーを必ず更新してください。ポリシーの範囲は、ランタイムでパスから解釈されるバケット名とオブジェクト名に限定します。
次の IAM ポリシーの例では PutObject API アクションを使用して、Amazon S3 バケット内にある csvJobs という名前のフォルダに、子ワークフローの実行結果を書き込むために必要な最小特権を付与しています。
-
{ "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:ListMultipartUploadParts", "s3:AbortMultipartUpload" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-destination-bucket/csvJobs/*" ] } ] }
子ワークフロー実行結果を書き込む Amazon S3 バケットが AWS Key Management Service(AWS KMS)キーを使用して暗号化されている場合は、IAM ポリシーに必要な AWS KMS アクセス許可を含める必要があります。詳細については、「AWS KMS key 暗号化された Amazon S3 バケットの IAM アクセス許可」を参照してください。