翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # ResultWriter (Map) **ステートの管理とデータの変換** [変数を使用したステート間のデータ受け渡し](workflow-variables.md)と [JSONata を使用したデータ変換](transforming-data.md)について説明します。 `ResultWriter` フィールドは、Distributed Map ステートによって開始された子ワークフロー実行の出力結果のオプションを設定するための JSON オブジェクトです。出力結果をエクスポートする場合、出力結果のフォーマットオプションおよび保存先となる Amazon S3 の場所を指定できます。Step Functions はこれらの結果をデフォルトではエクスポートしません。 **Topics** + [ResultWriter フィールドの内容](#input-output-resultwriter-field-contents) + [例](#input-output-resultwriter-examples) + [Amazon S3 へのエクスポート](#input-output-resultwriter-exporting-to-S3) + [ResultWriter の IAM ポリシー](#resultwriter-iam-policies) ## ResultWriter フィールドの内容 `ResultWriter` フィールドには、次のサブフィールドが含まれます。サブフィールドの選択により、出力のフォーマットおよび Amazon S3 へのエクスポート可否が決まります。 **`ResultWriter`** 以下の詳細を指定する JSON オブジェクト。 + `Resource` Step 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 Lines としてフォーマットします。 **必須フィールドの組み合わせ** `ResultWriter` フィールドは空にできません。これらのサブフィールドのセットのいずれかを指定する必要があります。 + `WriterConfig` – 結果を Amazon S3 に保存せずに、フォーマットされた出力をプレビューします。 + `Resource` および `Parameters` – 追加のフォーマットなしで結果を Amazon S3 に保存します。 + `WriterConfig`、`Resource`、`Parameters` の 3 つのフィールドすべて – 出力をフォーマットして Amazon S3 に保存します。 ## 設定と変換出力の例 以下のトピックでは、`ResultWriter` の可能な設定と、さまざまな変換オプションで処理された結果の例を示します。 + [ResultWriter の設定](#input-output-resultwriter-example-configurations) + [変換](#input-output-resultwriter-example-transformations) ### ResultWriter の設定例 次の例では、3 つのフィールド (`WriterConfig`、`Resources`、`Parameters`) の可能な組み合わせによる設定を示しています。 ***WriterConfig* のみ** この例では、`WriterConfig` フィールドに出力フォーマットと変換を指定して、ステートの出力のプレビュー表示方法を設定します。Amazon S3 バケット仕様を指定する `Resource` および `Parameters` フィールドがないため、*ステートの出力*リソースが暗黙的に使用されます。結果は次のステートに渡されます。 ``` "ResultWriter": { "WriterConfig": { "Transformation": "FLATTEN", "OutputType": "JSON" } } ``` ***Resources* と *Parameters* のみ** この例では、`WriterConfig` フィールドがないため、追加のフォーマットや変換なしで、ステートの出力を指定された Amazon S3 バケットにエクスポートします。 ``` "ResultWriter": { "Resource": "arn:aws:states:::s3:putObject", "Parameters": { "Bucket": "amzn-s3-demo-destination-bucket", "Prefix": "csvProcessJobs" } ``` ***WriterConfig*、*Resources*、*Parameters* の 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` が `JSON` の場合で、さまざまな `Transformation` 値によってフォーマットされた出力を示しています。 **変換: NONE** これは `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** これは `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` エラーが発生してステートマシンの実行が失敗します。 出力ペイロードサイズが 256 KiB を超える場合は、結果を Amazon S3 バケットにエクスポートすると便利です。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 ポリシー](#resultwriter-iam-policies)」を参照してください。 子ワークフローの実行結果をエクスポートすると、*分散マップ状態*実行により、マップ実行 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](redrive-map-run.md) した場合、`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](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)` API アクションを呼び出し、Amazon S3 バケットやオブジェクト、Lambda 関数などのAWSリソースにアクセスするために必要な最小限の権限が含まれます。 IAM ポリシーには必要最小限のアクセス許可のみを含めることをお勧めします。例えば、ワークフローに分散モードの `Map` ステートが含まれている場合、ポリシーの範囲を対象データが含まれる特定の Amazon S3 バケットおよびフォルダに絞り込みます。 **重要** *分散マップ状態*の入力で、既存のキーと値のペアへの[参照パス](amazon-states-language-paths.md#amazon-states-language-reference-paths)とともに、Amazon S3 バケットやオブジェクト、またはプレフィックスを指定する場合は、ワークフローの IAM ポリシーを必ず更新してください。ポリシーの範囲は、ランタイムでパスから解釈されるバケット名とオブジェクト名に限定します。 次の IAM ポリシーの例では `[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)` 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 アクセス許可](iam-policies-eg-dist-map.md#multiupload-dmap-result-policy)」を参照してください。