本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# ResultWriter （地圖）
<a name="input-output-resultwriter"></a>

**管理狀態和轉換資料**  
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)

`ResultWriter` 欄位是 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 欄位的內容
<a name="input-output-resultwriter-field-contents"></a>

`ResultWriter` 欄位包含下列子欄位。欄位的選擇會決定輸出的格式，以及輸出是否匯出至 Amazon S3。

**`ResultWriter`**  
指定下列詳細資訊的 JSON 物件：  
+ `Resource`

  Step Functions 調用以匯出執行結果的 Amazon S3 API 動作。
+ `Parameters`

  JSON 物件，指定存放執行輸出的 Amazon S3 儲存貯體名稱和字首。
+ `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` - 以格式化輸出並將其儲存至 Amazon S3。

## 範例組態和轉換輸出
<a name="input-output-resultwriter-examples"></a>

下列主題示範不同轉換選項中處理結果的可能組態設定`ResultWriter`和範例。
+ [ResultWriter 組態](#input-output-resultwriter-example-configurations)
+ [轉換](#input-output-resultwriter-example-transformations)

### ResultWriter 組態的範例
<a name="input-output-resultwriter-example-configurations"></a>

下列範例示範具有三個欄位可能組合的組態：`WriterConfig`、 `Resources`和 `Parameters`。

**僅限 *WriterConfig***  
此範例會設定狀態輸出在預覽中呈現的方式，並在 `WriterConfig` 欄位中指定輸出格式和轉換。不存在`Resource`並提供 Amazon S3 儲存貯體規格`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*、*資源*和*參數***  
此範例會根據 `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"
    }
}
```

### 轉換的範例
<a name="input-output-resultwriter-example-transformations"></a>

對於這些範例，假設每個子工作流程執行都會傳回輸出，這是物件陣列。

```
[
  {
    "customer_id": "145538",
    "order_id": "100000"
  },
  {
    "customer_id": "898037",
    "order_id": "100001"
  }
]
```

這些範例示範不同`Transformation`值的格式化輸出，使用 `OutputType`的 `JSON`。

**轉換 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`轉換時已處理結果的範例。請注意，它是將子工作流程執行陣列的組合輸出扁平化為一個陣列。

```
[
    {
        "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
<a name="input-output-resultwriter-exporting-to-S3"></a>

**重要**  
請確定您用來匯出 Map Run 結果的 Amazon S3 儲存貯體與您的狀態機器位於相同 AWS 帳戶和 AWS 區域。否則，您的狀態機器執行會失敗並顯示`States.ResultWriterFailed`錯誤。

如果您的輸出承載大小超過 256 KiB，將結果匯出至 Amazon S3 儲存貯體會很有幫助。Step Functions 會合併所有子工作流程執行資料，例如執行輸入和輸出、ARN 和執行狀態。然後，它會將狀態相同的執行匯出至指定 Amazon S3 位置中的個別檔案。

以下範例使用 **JSONPath**，顯示 `ResultWriter` 欄位的語法`Parameters`與 匯出子工作流程執行結果。在此範例中，您將結果存放在名為 的儲存貯`amzn-s3-demo-destination-bucket`體中，前綴稱為 `csvProcessJobs`。

```
{
  "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 位置建立兩個檔案，以取得成功和失敗結果。在此範例中，成功結果檔案包含 500 個成功結果，而失敗結果檔案包含 200 個失敗結果。

對於指定的執行嘗試，Step Functions 會根據您的執行輸出，在指定的 Amazon S3 位置建立下列檔案：
+ `manifest.json` – 包含 Map Run 中繼資料，例如匯出位置、Map Run ARN，以及結果檔案的相關資訊。

  如果您有 [redriven](redrive-map-run.md) Map Run， `manifest.json` 檔案會包含所有 Map Run 嘗試之所有成功子工作流程執行的參考。不過，此檔案包含對特定 的失敗和待定執行的參考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 政策
<a name="resultwriter-iam-policies"></a>

當您使用 Step Functions 主控台建立工作流程時，Step Functions 可以根據您工作流程定義中的資源自動產生 IAM 政策。產生的政策包含允許狀態機器角色叫用*分散式映射狀態*的 `[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)` API 動作和存取AWS資源所需的最低權限，例如 Amazon S3 儲存貯體和物件，以及 Lambda 函數。

我們建議您在 IAM 政策中只包含必要的許可。例如，如果您的工作流程包含分散式模式中`Map`的狀態，請將您的政策範圍縮小到包含您的資料的特定 Amazon S3 儲存貯體和資料夾。

**重要**  
如果您指定 Amazon S3 儲存貯體和物件或字首，以及*分散式映射狀態*輸入中現有鍵值對的[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，請務必更新工作流程的 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)。