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

# ItemReader （地圖）
<a name="input-output-itemreader"></a>

`ItemReader` 欄位是 JSON 物件，可指定資料集及其位置。*分散式映射狀態*會使用此資料集做為其輸入。

下列範例顯示 **JSONPath 型**工作流程中`ItemReader`欄位的語法，適用於存放在 Amazon S3 儲存貯體的文字分隔檔案中的資料集。

```
"ItemReader": {
    "ReaderConfig": {
        "InputType": "CSV",
        "CSVHeaderLocation": "FIRST_ROW"
    },
    "Resource": "arn:aws:states:::s3:getObject",
    "Parameters": {
        "Bucket": "{{amzn-s3-demo-bucket}}",
        "Key": "{{csvDataset/ratings.csv}}",
        "VersionId": "BcK42coT2jE1234VHLUvBV1yLNod2OEt"
    }
}
```

在下列以 **JSONata 為基礎的**工作流程中，請注意 `Parameters` 會取代為**引數**。

```
"ItemReader": {
    "ReaderConfig": {
        "InputType": "CSV",
        "CSVHeaderLocation": "FIRST_ROW"
    },
    "Resource": "arn:aws:states:::s3:getObject",
    "Arguments": {
        "Bucket": "{{amzn-s3-demo-bucket}}",
        "Key": "{{csvDataset/ratings.csv}}"
        "VersionId": "BcK42coT2jE1234VHLUvBV1yLNod2OEt"
    }
}
```

## ItemReader 欄位的內容
<a name="itemreader-field-contents"></a>

根據您的資料集， `ItemReader` 欄位的內容會有所不同。例如，如果您的資料集是從工作流程中上一個步驟傳遞的 JSON 陣列，則會省略 `ItemReader` 欄位。如果您的資料集是 Amazon S3 資料來源，此欄位會包含下列子欄位。

**`Resource`**  
Step Functions 將使用的 Amazon S3 API 整合動作，例如 `arn:aws:states:::s3:getObject`

**`Arguments (JSONata) or Parameters (JSONPath)`**  
JSON 物件，指定存放資料集的 Amazon S3 儲存貯體名稱和物件金鑰。  
如果儲存貯體已啟用版本控制，您也可以提供 Amazon S3 物件版本。

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

  接受下列其中一個值：`CSV`、`JSON`、`JSONL`、`PARQUET`、`MANIFEST`。

  指定 Amazon S3 資料來源的類型，例如以文字分隔的檔案 (`CSV`)、物件、JSON 檔案、JSON Lines、Parquet 檔案、Athena 資訊清單或 Amazon S3 清查清單。在 Workflow Studio 中，您可以從 **S3 項目來源**選取輸入類型。

  大多數使用`S3GetObject`擷取的輸入類型也在其參數中支援 `ExpectedBucketOwner`和 `VersionId` 欄位。Parquet 檔案是不支援 的例外狀況`VersionId`。

  輸入檔案支援下列外部壓縮類型：GZIP、ZSTD。

  範例檔案名稱： `myObject.jsonl.gz`和 `myObject.csv.zstd`。

  注意：Parquet 檔案是內部壓縮的二進位檔案類型。支援 GZIP、ZSTD 和 Snappy 壓縮。
+ `Transformation`

  「選用」**。值將為 或 `NONE`或 `LOAD_AND_FLATTEN`。

  如果未指定，`NONE`則會假設 。設定為 時`LOAD_AND_FLATTEN`，您還必須設定 `InputType`。

  預設行為，映射會逐一查看從呼叫 傳回的**中繼資料物件**`S3:ListObjectsV2`。設定為 時`LOAD_AND_FLATTEN`，映射會讀取並處理結果清單中參考的實際**資料物件**。
+ `ManifestType`

  「選用」**。值將為 或 `ATHENA_DATA`或 `S3_INVENTORY`。

  注意：如果設定為 `S3_INVENTORY`，您也**不能**指定 ，`InputType`因為類型假設為 `CSV`。
+ `CSVDelimiter`

  當 `InputType`為 `CSV`或 時，您可以指定此欄位`MANIFEST`。

  接受下列其中一個值： `COMMA`（預設）`PIPE`、`SEMICOLON`、、`SPACE`、`TAB`。
**注意**  
使用 `CSVDelimiter` 欄位， `ItemReader`可以處理以逗號以外的字元分隔的檔案。參考「CSV 檔案」也包含使用 `CSVDelimiter` 欄位指定之替代分隔符號的檔案。
+ `CSVHeaderLocation`

  當 `InputType`為 `CSV`或 時，您可以指定此欄位`MANIFEST`。

  接受下列其中一個值來指定資料欄標頭的位置：
  + `FIRST_ROW` – 如果檔案的第一行是 標頭，請使用此選項。
  + `GIVEN` – 使用此選項在狀態機器定義中指定 標頭。

    例如，如果您的檔案包含下列資料。

    ```
    1,307,3.5,1256677221
    1,481,3.5,1256677456
    1,1091,1.5,1256677471
    ...
    ```

    您可以提供下列 JSON 陣列做為 CSV 標頭：

    ```
    "ItemReader": {
        "ReaderConfig": {
            "InputType": "CSV",
            "CSVHeaderLocation": "GIVEN",
            "CSVHeaders": [
                "userId",
                "movieId",
                "rating",
                "timestamp"
            ]
        }
    }
    ```
**CSV 標頭大小**  
Step Functions 針對以文字分隔的檔案支援高達 10 KiB 的標頭。
+ `ItemsPointer`

  「選用」**。當 `InputType`為 時，您可以指定此欄位`JSON`。

  `ItemsPointer` 使用 JSONPointer 語法來選取 JSON 檔案中巢狀的特定陣列或物件。JSONPointer 是一種標準化語法，專門用於導覽和參考 JSON 文件中的位置。

  JSONPointer 語法使用正斜線 (/) 來分隔每個巢狀層級，陣列索引表示為不含括號的數字。例如：
  + `/Data/Contents` - 參考資料物件中的內容陣列
  + `/Data/Contents/0` - 參考內容陣列的第一個元素

  目標陣列的起始位置必須在 JSON 檔案的前 16MB 內，而且 JSONPointer 路徑長度必須少於 2000 個字元。

  例如，如果您的 JSON 檔案包含：

  ```
  {"data": {"items": [{"id": 1}, {"id": 2}]}}
  ```

  您可以指定 `"ItemsPointer": "/data/items"`來處理項目陣列。
+ `MaxItems`

  根據預設，`Map`狀態會反覆查看指定資料集中的所有項目。透過設定 `MaxItems`，您可以限制傳遞至 `Map` 狀態的資料項目數量。例如，如果您提供包含 1，000 個資料列的文字分隔檔案，且您設定限制為 100，則解譯器*只會*將 100 個資料列傳遞至*分散式地圖狀態*。`Map` 狀態會依序處理項目，從標頭列開始。

  對於 **JSONPath** 工作流程，您可以在解析為整數的狀態輸入中使用 `MaxItemsPath`和索引鍵/值對的*參考路徑*。請注意，您可以指定 `MaxItems`或 `MaxItemsPath`，但不能同時指定**兩者**。
**注意**  
您可以指定最多 100，000，000 個的限制，之後 會`Distributed Map`停止讀取項目。

**帳戶和區域的需求**  
您的 Amazon S3 儲存貯體必須與狀態機器位於相同的 AWS 帳戶 和 AWS 區域 。  
請注意，即使您的狀態機器可以跨相同 中的不同 存取儲存貯 AWS 帳戶 體中的檔案 AWS 區域，Step Functions 僅支援在*與* AWS 區域 狀態機器相同 AWS 帳戶 和相同的 Amazon S3 儲存貯體中列出物件。

## 處理巢狀資料集 (2025 年 9 月 11 日更新）
<a name="itemreader-flatten"></a>

使用新`Transformation`參數，您可以指定 的值，`LOAD_AND_FLATTEN`而且映射會從呼叫 的結果清單中讀取參考**的實際**資料物件`S3:ListObjectsV2`。

在此版本之前，您需要建立巢狀分散式地圖來**擷取**中繼資料，然後**處理**實際資料。第一個映射會逐一查看 傳回的**中繼資料**`S3:ListObjectsV2`，並叫用子工作流程。每個子狀態機器中的另一個映射會從個別檔案讀取**實際資料**。使用轉換選項，您可以一次完成這兩個步驟。

假設您想要對系統每小時產生的過去 24 個日誌檔案執行每日稽核，並存放在 Amazon S3 中。您的分散式映射狀態可以使用 列出日誌檔案`S3:ListObjectsV2`，然後逐一查看每個物件的*中繼資料*，或者它現在可以載入和分析存放在 Amazon S3 儲存貯體中的**實際資料**物件。

使用 `LOAD_AND_FLATTEN`選項可以提高可擴展性、減少開放的 Map Run 計數，以及同時處理多個物件。Athena 和 Amazon EMR 任務通常會產生可使用新組態處理的輸出。

以下是 `ItemReader`定義中參數的範例：

```
{
  "QueryLanguage": "JSONata",
  "States": {
    ...
    "Map": {
        ...
        "ItemReader": {
            "Resource": "arn:aws:states:::s3:listObjectsV2",
            "ReaderConfig": {
                // InputType is required if Transformation is LOAD_AND_FLATTEN.
                "InputType": "CSV | JSON | JSONL | PARQUET",

                // Transformation is OPTIONAL and defaults to NONE if not present
                "Transformation": "NONE | LOAD_AND_FLATTEN" 
            },
            "Arguments": {
                "Bucket": "amzn-s3-demo-bucket1",
                "Prefix": "{% $states.input.PrefixKey %}"
            }
        },
        ...
    }
}
```

## 資料集的範例
<a name="itemreader-examples-map"></a>

您可以指定下列其中一個選項做為資料集：
+ [上一個步驟的 JSON 資料](#itemsource-json-array)
+ [Amazon S3 物件的清單](#itemsource-example-s3-object-data)
+ [由 LOAD\_AND\_FLATTEN 轉換的 Amazon S3 物件](#itemsource-example-s3-object-data-flatten)
+ [Amazon S3 儲存貯體中的 JSON 檔案](#itemsource-example-json-data)
+ [Amazon S3 儲存貯體中的 JSON Lines 檔案](#itemsource-example-json-lines-data)
+ [Amazon S3 儲存貯體中的 CSV 檔案](#itemsource-example-csv-data)
+ [Amazon S3 儲存貯體中的 Parquet 檔案](#itemsource-example-parquet-data)
+ [Athena 資訊清單 （處理多個項目）](#itemsource-example-athena-manifest-data)
+ [Amazon S3 清查 （處理多個項目）](#itemsource-example-s3-inventory)

**注意**  
Step Functions 需要適當的許可才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。

### 上一個步驟的 JSON 資料
<a name="itemsource-json-array"></a>

*分散式映射狀態*可以接受從工作流程中上一個步驟傳遞的 JSON 輸入。

輸入可以是 JSON 陣列、JSON 物件或 JSON 物件節點內的陣列。

Step Functions 會直接反覆運算陣列的元素，或 JSON 物件的鍵值對。

若要從輸入中選取包含巢狀 JSON 陣列或物件的特定節點，您可以使用 `ItemsPath （地圖，僅限 JSONPath)`，或在 JSONata 狀態的 `Items` 欄位中使用 JSONata 表達式。

若要處理個別項目，*分散式映射狀態*會為每個項目啟動子工作流程執行。下列索引標籤顯示傳遞至 `Map` 狀態的輸入範例，以及傳遞至子工作流程執行的對應輸入。

**注意**  
當您的資料集是上一個步驟的 JSON 資料時，則不需要 `ItemReader` 欄位。

------
#### [ Input passed to the Map state ]

請考慮以下三個項目的 JSON 陣列。

```
"facts": [
    {
        "verdict": "true",
        "statement_date": "6/11/2008",
        "statement_source": "speech"
    },
    {
        "verdict": "false",
        "statement_date": "6/7/2022",
        "statement_source": "television"
    },
    {
        "verdict": "mostly-true",
        "statement_date": "5/18/2016",
        "statement_source": "news"
    }
]
```

------
#### [ Input passed to a child workflow execution ]

*分散式映射狀態*會啟動三個子工作流程執行。每個執行都會收到陣列項目做為輸入。下列範例顯示子工作流程執行收到的輸入。

```
{
  "verdict": "true",
  "statement_date": "6/11/2008",
  "statement_source": "speech"
}
```

------

### Amazon S3 物件的清單
<a name="itemsource-example-s3-object-data"></a>

*分散式映射狀態*可以反覆查看存放在 Amazon S3 儲存貯體中的物件。當工作流程執行達到 `Map` 狀態時，Step Functions 會叫用 [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) API 動作，這會傳回 Amazon S3 **物件中繼資料**的陣列。在此陣列中，每個項目都包含儲存貯體中實際資料的資料，例如 **ETag** 和 **Key**。

若要處理陣列中的個別項目，*分散式映射狀態*會啟動子工作流程執行。例如，假設您的 Amazon S3 儲存貯體包含 100 個映像。然後，調用 `ListObjectsV2` API 動作後傳回的陣列包含 100 個中繼資料項目。*然後，分散式映射狀態*會啟動 100 個子工作流程執行來處理每個項目。

若要在沒有巢狀工作流程的情況下直接處理資料物件，您可以選擇 LOAD\_AND\_FLATTEN 轉換選項，以**直接**處理項目。

**注意**  
Step Functions 也會包含使用 Amazon S3 **主控台**在 Amazon S3 儲存貯體中建立的每個**資料夾**的項目。資料夾項目會導致啟動額外的子工作流程執行。  
為了避免為每個資料夾建立額外的子工作流程執行，建議您使用 AWS CLI 來建立資料夾。如需詳細資訊，請參閱*AWS Command Line Interface 《 使用者指南*》中的[高階 Amazon S3 命令](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-buckets-creating)。
Step Functions 需要適當的許可，才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。

下列索引標籤顯示 `ItemReader` 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。

------
#### [ ItemReader syntax ]

在此範例中，您已在名為 的 Amazon S3 儲存貯體`processData`中名為 的字首內整理資料，其中包含影像、JSON 檔案和物件`amzn-s3-demo-bucket`。

```
"ItemReader": {
    "Resource": "arn:aws:states:::s3:listObjectsV2",
    "Parameters": {
        "Bucket": "{{amzn-s3-demo-bucket}}",
        "Prefix": "{{processData}}"
    }
}
```

------
#### [ Input passed to a child workflow execution ]

*分散式映射狀態*啟動的子工作流程執行數量與 Amazon S3 儲存貯體中存在的中繼資料項目數量相同。下列範例顯示子工作流程執行收到的輸入。

```
{
  "Etag": "\"05704fbdccb224cb01c59005bebbad28\"",
  "Key": "{{processData}}/{{images}}/{{n02085620_1073.jpg}}",
  "LastModified": 1668699881,
  "Size": 34910,
  "StorageClass": "STANDARD"
}
```

------

### 由 轉換的 Amazon S3 物件 `LOAD_AND_FLATTEN`
<a name="itemsource-example-s3-object-data-flatten"></a>

透過增強對 S3 ListObjectsV2 的支援作為分散式地圖中的輸入來源，您的狀態機器可以直接從 Amazon S3 儲存貯體讀取和處理多個**資料物件**，無需巢狀地圖來處理中繼資料！

使用 `LOAD_AND_FLATTEN`選項，您的狀態機器會執行下列動作：
+ 讀取 Amazon S3 `ListObjectsV2`呼叫列出的每個物件**的實際內容**。
+ 根據 InputType (CSV、JSON、JSONL、Parquet) 剖析內容。
+ 從檔案內容 （資料列/記錄） 而非中繼資料建立項目。

使用轉換選項，您不再需要巢狀分散式地圖來處理中繼資料。使用 LOAD\_AND\_FLATTEN 選項可提高可擴展性、減少作用中的映射執行計數，並同時處理多個物件。

下列組態顯示 的設定`ItemReader`：

```
"ItemReader": {
   "Resource": "arn:aws:states:::s3:listObjectsV2",
   "ReaderConfig": {
      "InputType": "JSON",
      "Transformation": "LOAD_AND_FLATTEN"
   },
   "Arguments": {
      "Bucket": "{{S3_BUCKET_NAME}}",
      "Prefix": "{{S3_BUCKET_PREFIX}}"
   }
}
```

**儲存貯體字首建議**  
我們建議您在字首上包含結尾斜線。例如，如果您選取字首為 的資料`folder1`，您的狀態機器將同時處理 `folder1/myData.csv`和 `folder10/myData.csv`。使用 `folder1/` 只會嚴格處理一個資料夾。

### Amazon S3 儲存貯體中的 JSON 檔案
<a name="itemsource-example-json-data"></a>

*分散式映射狀態*可以接受存放在 Amazon S3 儲存貯體中的 JSON 檔案做為資料集。JSON 檔案必須包含陣列或 JSON 物件。

當工作流程執行達到 `Map` 狀態時，Step Functions 會叫用 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 動作來擷取指定的 JSON 檔案。

如果 JSON 檔案包含巢狀物件結構，您可以使用 來選取具有資料集的特定節點`ItemsPointer`。例如，下列組態會擷取*庫存*中*特色產品的*巢狀清單。

```
"ItemReader": {
   "Resource": "arn:aws:states:::s3:getObject",
   "ReaderConfig": {
      "InputType": "JSON",
      "ItemsPointer": "{{/inventory/products/featured}}"
   },
   "Arguments": {
      "Bucket": "amzn-s3-demo-bucket",
      "Key": "nested-data-file.json"
   }
}
```

接著`Map`狀態會反覆查看陣列中的每個項目，並為每個項目啟動子工作流程執行。例如，如果您的 JSON 檔案包含 1000 個陣列項目，`Map`狀態會啟動 1000 個子工作流程執行。

**注意**  
用來啟動子工作流程執行的執行輸入不能超過 256 KiB。不過，如果您接著套用選用`ItemSelector`欄位來減少項目的大小，Step Functions 支援從文字分隔檔案、JSON 或 JSON Lines 檔案讀取最多 8 MB 的項目。
Step Functions 支援 10 GB 作為 Amazon S3 中個別檔案的大小上限。
Step Functions 需要適當的許可，才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。

下列索引標籤顯示 `ItemReader` 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。

在此範例中，假設您有一個名為 的 JSON 檔案`{{factcheck.json}}`。您已將此檔案存放在 Amazon S3 儲存貯體`{{jsonDataset}}`中名為 的字首中。以下是 JSON 資料集的範例。

```
[
  {
    "verdict": "true",
    "statement_date": "6/11/2008",
    "statement_source": "speech"
  },
  {
    "verdict": "false",
    "statement_date": "6/7/2022",
    "statement_source": "television"
  },
  {
    "verdict": "mostly-true",
    "statement_date": "5/18/2016",
    "statement_source": "news"
  },
  ...
]
```

------
#### [ ItemReader syntax ]

```
"ItemReader": {
   "Resource": "arn:aws:states:::s3:getObject",
   "ReaderConfig": {
      "InputType": "JSON"
   },
   "Parameters": {
      "Bucket": "{{amzn-s3-demo-bucket}}",
      "Key": "{{jsonDataset/factcheck.json}}"
   }
}
```

------
#### [ Input to a child workflow execution ]

*分散式映射狀態*啟動的子工作流程執行數量與 JSON 檔案中存在的陣列項目數量相同。下列範例顯示子工作流程執行收到的輸入。

```
{
  "verdict": "true",
  "statement_date": "6/11/2008",
  "statement_source": "speech"
}
```

------

### Amazon S3 儲存貯體中的 JSON Lines 檔案
<a name="itemsource-example-json-lines-data"></a>

*分散式映射狀態*可以接受存放在 Amazon S3 儲存貯體中的 JSON Lines 檔案做為資料集。

**注意**  
用來啟動子工作流程執行的執行輸入不能超過 256 KiB。不過，如果您接著套用選用`ItemSelector`欄位來減少項目的大小，Step Functions 支援從文字分隔檔案、JSON 或 JSON Lines 檔案讀取最多 8 MB 的項目。
Step Functions 支援 10 GB 作為 Amazon S3 中個別檔案的大小上限。
Step Functions 需要適當的許可，才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。

下列索引標籤顯示 `ItemReader` 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。

在此範例中，假設您有一個名為 的 JSON Lines 檔案`{{factcheck.jsonl}}`。您已將此檔案存放在 Amazon S3 儲存貯`{{jsonlDataset}}`體中名為 的字首中。以下是檔案內容的範例。

```
{"verdict": "true", "statement_date": "6/11/2008", "statement_source": "speech"} 
{"verdict": "false", "statement_date": "6/7/2022", "statement_source": "television"}
{"verdict": "mostly-true", "statement_date": "5/18/2016", "statement_source": "news"}
```

------
#### [ ItemReader syntax ]

```
"ItemReader": {
   "Resource": "arn:aws:states:::s3:getObject",
   "ReaderConfig": {
      "InputType": "JSONL"
   },
   "Parameters": {
      "Bucket": "{{amzn-s3-demo-bucket}}",
      "Key": "{{jsonlDataset/factcheck.jsonl}}"
   }
}
```

------
#### [ Input to a child workflow execution ]

*分散式映射狀態*會啟動與 JSONL 檔案中存在的行數一樣多的子工作流程執行。下列範例顯示子工作流程執行收到的輸入。

```
{
  "verdict": "true",
  "statement_date": "6/11/2008",
  "statement_source": "speech"
}
```

------

### Amazon S3 儲存貯體中的 CSV 檔案
<a name="itemsource-example-csv-data"></a>

**注意**  
使用 `CSVDelimiter` 欄位， `ItemReader`可以處理以逗號以外的字元分隔的檔案。參考「CSV 檔案」也包含使用 `CSVDelimiter` 欄位指定之替代分隔符號的檔案。

*分散式映射狀態*可以接受以文字分隔的檔案，該檔案存放在 Amazon S3 儲存貯體中做為資料集。如果您使用以文字分隔的檔案做為資料集，則需要指定資料欄標頭。如需如何指定標頭的資訊，請參閱 [ItemReader 欄位的內容](#itemreader-field-contents)。

Step Functions 會根據下列規則剖析以文字分隔的檔案：
+ 分隔欄位的分隔符號由 *ReaderConfig* `CSVDelimiter`中的 指定。分隔符號預設為 `COMMA`。
+ Newlines 是分隔**記錄**的分隔符號。
+ 欄位視為字串。對於資料類型轉換，請使用 中的`States.StringToJson`內部 函數[ItemSelector （地圖）](input-output-itemselector.md)。
+ 不需要雙引號 (" ") 來括住字串。不過，以雙引號括住的字串可包含逗號和換行，而不做為記錄分隔符號。
+ 您可以重複雙引號來保留雙引號。
+ 反斜線 (\\) 是逸出特殊字元的另一種方式。反斜線僅適用於其他反斜線、雙引號和設定的欄位分隔符號，例如逗號或縱線。反斜線後面接著任何其他字元會被無提示移除。
+ 您可以重複斜線來保留斜線。例如：

  ```
  path,size
  C:\\Program Files\\MyApp.exe,6534512
  ```
+ 逸出雙引號的反斜線 (`\"`) 只有在包含在組內時才有效，因此我們建議重複逸出雙引號：`""`。
+ 如果資料列中的欄位數目**小於** 標頭中的欄位數目，Step Functions 會提供缺少值**的空字串**。
+ 如果資料列中的欄位數目**超過**標頭中的欄位數目，Step Functions **會略過**其他欄位。

如需 Step Functions 如何剖析以文字分隔檔案的詳細資訊，請參閱 [Example of parsing an input CSV file](example-csv-parse-dist-map.md#example-csv-parse)。

當工作流程執行達到 `Map` 狀態時，Step Functions 會叫用 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 動作來擷取指定的檔案。接著`Map`狀態會逐一查看 檔案中的每一列，並啟動子工作流程執行，以處理每一列中的項目。例如，假設您提供以文字分隔的檔案，其中包含 100 列做為輸入。然後，解譯器會將每一列傳遞至 `Map` 狀態。`Map` 狀態會以序列順序處理項目，從標頭列開始。

**注意**  
用來啟動子工作流程執行的執行輸入不能超過 256 KiB。不過，如果您接著套用選用`ItemSelector`欄位來減少項目的大小，Step Functions 支援從文字分隔檔案、JSON 或 JSON Lines 檔案讀取最多 8 MB 的項目。
Step Functions 支援 10 GB 作為 Amazon S3 中個別檔案的大小上限。
Step Functions 需要適當的許可，才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。

下列索引標籤顯示 `ItemReader` 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。

------
#### [ ItemReader syntax ]

例如，假設您有一個名為 的 CSV 檔案`{{ratings.csv}}`。然後，您已將此檔案存放在 Amazon S3 儲存貯體`{{csvDataset}}`中名為 的字首中。

```
"ItemReader": {
   "ReaderConfig": {
      "InputType": "CSV",
      "CSVHeaderLocation": "FIRST_ROW",
      "CSVDelimiter": "PIPE"
   },
   "Resource": "arn:aws:states:::s3:getObject",
   "Parameters": {
      "Bucket": "{{amzn-s3-demo-bucket}}",
      "Key": "{{csvDataset/ratings.csv}}"
   }
}
```

------
#### [ Input to a child workflow execution ]

*分散式映射狀態*啟動的子工作流程執行數目與 CSV 檔案中存在的資料列數目相同，如果在檔案中，則不含標頭列。下列範例顯示子工作流程執行收到的輸入。

```
{
  "rating": "3.5",
  "movieId": "307",
  "userId": "1",
  "timestamp": "1256677221"
}
```

------

### Amazon S3 儲存貯體中的 Parquet 檔案
<a name="itemsource-example-parquet-data"></a>

Parquet 檔案可以用作輸入來源。存放在 Amazon S3 中的 Apache Parquet 檔案可大規模提供高效率的單欄式資料處理。

使用 Parquet 檔案時，適用下列條件：
+ 256MB 是資料列群組大小上限，而 5MB 是頁尾大小上限。如果您提供的輸入檔案超過任一限制，狀態機器將傳回執行時間錯誤。
+ **不支援** `VersionId` 欄位`InputType=Parquet`。
+ 原生支援內部 GZIP、ZSTD 和 Snappy 資料壓縮。不需要副檔名。

以下顯示 `InputType` 設定為 Parquet 的範例 ASL 組態：

```
"ItemReader": {
   "Resource": "arn:aws:states:::s3:getObject",
   "ReaderConfig": {
      "InputType": "PARQUET"
   },
   "Arguments": {
      "Bucket": "amzn-s3-demo-bucket",
      "Key": "my-parquet-data-file-1.parquet"
   }
}
```

**大規模任務處理**  
對於非常大規模的任務，Step Functions 將使用許多輸入讀取器。讀者交錯處理，這可能會導致某些讀者暫停，而其他讀者則進行。間歇性進度是大規模的預期行為。

### Athena 資訊清單 （處理多個項目）
<a name="itemsource-example-athena-manifest-data"></a>

您可以使用從`UNLOAD`查詢結果產生的 Athena 資訊清單檔案，來指定映射狀態的資料檔案**來源**。您可以將 `ManifestType`設定為 `ATHENA_DATA`，並將 `InputType`設定為 `CSV`、 `JSONL`或 `Parquet`。

執行`UNLOAD`查詢時，除了實際的資料物件之外，Athena 還會產生資料資訊清單檔案。資訊清單檔案提供資料檔案的結構化 CSV 清單。資訊清單和資料檔案都會儲存至 Amazon S3 中的 Athena 查詢結果位置。

```
UNLOAD (<YOUR_SELECT_QUERY>) TO 'S3_URI_FOR_STORING_DATA_OBJECT' WITH (format = 'JSON')
```

程序的概念概觀，簡要來說：

1. 使用 Athena 中的`UNLOAD`查詢從資料表中選取您的資料。

1. Athena 會在 Amazon S3 中產生資訊清單檔案 (CSV) 和資料物件。

1. 設定 Step Functions 以讀取資訊清單檔案並處理輸入。

此功能可以處理來自 Athena 的 CSV、JSONL 和 Parquet 輸出格式。單一資訊清單檔案中參考的所有物件都必須是相同的 InputType 格式。請注意，`UNLOAD`查詢匯出的 CSV 物件**不包含**第一行中的標頭。了解`CSVHeaderLocation`您是否需要提供資料欄標頭。

地圖內容也會包含 `$states.context.Map.Item.Source`，讓您可以根據資料來源自訂處理。

以下是`ItemReader`設定為使用 Athena 資訊清單之 的範例組態：

```
"ItemReader": {
   "Resource": "arn:aws:states:::s3:getObject",
   "ReaderConfig": {
      "ManifestType": "ATHENA_DATA",
      "InputType": "CSV | JSONL | PARQUET"
   },
   "Arguments": {
      "Bucket": "<S3_BUCKET_NAME>",
      "Key": "<S3_KEY_PREFIX><QUERY_ID>-manifest.csv"
   }
}
```

**在 Workflow Studio 中使用 Athena 資訊清單模式**  
資料處理的常見案例會將映射套用至來自 Athena UNLOAD 查詢的資料來源。映射會叫用 Lambda 函數來處理 Athena 資訊清單中描述的每個項目。Step Functions Workflow Studio 提供現成模式，將所有這些元件結合成封鎖您拖曳到狀態機器畫布上。

### S3 清查 （處理多個項目）
<a name="itemsource-example-s3-inventory"></a>

*分散式映射狀態*可以接受存放在 Amazon S3 儲存貯體中的 Amazon S3 清查清單檔案做為資料集。

當工作流程執行達到 `Map` 狀態時，Step Functions 會叫用 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 動作來擷取指定的 Amazon S3 清查清單檔案。

根據預設，`Map`狀態接著會反覆查看清查中的**物件**，以傳回 Amazon S3 清查物件中繼資料的陣列。

如果您指定 ManifestType 為 S3\_INVENTORY，則無法指定 InputType。



**注意**  
Step Functions 支援 10 GB 做為解壓縮後 Amazon S3 清查報告中個別檔案的大小上限。不過，如果每個檔案小於 10 GB，Step Functions 可以處理超過 10 GB。
Step Functions 需要適當的許可，才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。

以下是 CSV 格式的庫存檔案範例。此檔案包含名為 `csvDataset`和 的物件`imageDataset`，這些物件存放在名為 的 Amazon S3 儲存貯體中`amzn-s3-demo-source-bucket`。

```
"amzn-s3-demo-source-bucket","csvDataset/","0","2022-11-16T00:27:19.000Z"
"amzn-s3-demo-source-bucket","csvDataset/titles.csv","3399671","2022-11-16T00:29:32.000Z"
"amzn-s3-demo-source-bucket","imageDataset/","0","2022-11-15T20:00:44.000Z"
"amzn-s3-demo-source-bucket","imageDataset/n02085620_10074.jpg","27034","2022-11-15T20:02:16.000Z"
...
```

**重要**  
Step Functions 不支援使用者定義的 Amazon S3 清查報告做為資料集。  
Amazon S3 清查報告的輸出格式必須為 CSV。  
如需 Amazon S3 清查以及如何設定它們的詳細資訊，請參閱 [Amazon S3 清查](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-inventory.html)。

下列 Amazon S3 清查資訊清單檔案範例顯示清查物件中繼資料的 CSV 標頭。

```
{
  "sourceBucket" : "{{amzn-s3-demo-source-bucket}}",
  "destinationBucket" : "arn:aws:s3:::{{amzn-s3-demo-inventory}}",
  "version" : "2016-11-30",
  "creationTimestamp" : "1668560400000",
  "fileFormat" : "CSV",
  "fileSchema" : "Bucket, Key, Size, LastModifiedDate",
  "files" : [ {
    "key" : "{{amzn-s3-demo-bucket}}/{{destination-prefix}}/data/{{20e55de8-9c21-45d4-99b9-46c732000228.csv.gz}}",
    "size" : 7300,
    "MD5checksum" : "a7ff4a1d4164c3cd55851055ec8f6b20"
  } ]
}
```

下列索引標籤顯示 `ItemReader` 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。

------
#### [ ItemReader syntax ]

```
"ItemReader": {
   "ReaderConfig": {
      "InputType": "MANIFEST"
   },
   "Resource": "arn:aws:states:::s3:getObject",
   "Parameters": {
      "Bucket": "{{amzn-s3-demo-destination-bucket}}",
      "Key": "{{destination-prefix}}/{{amzn-s3-demo-bucket}}/{{config-id}}/{{YYYY-MM-DDTHH-MMZ}}/manifest.json"
   }
}
```

------
#### [ Input to a child workflow execution ]

```
{
  "LastModifiedDate": "2022-11-16T00:29:32.000Z",
  "Bucket": "amzn-s3-demo-source-bucket",
  "Size": "3399671",
  "Key": "csvDataset/titles.csv"
}
```

根據您在設定 Amazon S3 清查報告時選取的欄位，`manifest.json`檔案的內容可能與範例不同。

------

## 資料集的 IAM 政策建議
<a name="itemreader-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 政策。將政策範圍縮小至路徑在執行時間解析的儲存貯體和物件名稱。

下列範例顯示使用 [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) 和 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 動作授予存取 Amazon S3 資料集所需最低權限的技術。

**Example 使用 Amazon S3 物件做為資料集的條件**  
下列條件授予存取 Amazon S3 儲存貯體`{{processImages}}`資料夾中物件的最低權限。  

```
"Resource": [ "arn:aws:s3:::{{amzn-s3-demo-bucket}}" ],
"Condition": {
   "StringLike": { 
      "s3:prefix": [ "{{processImages}}" ]
   }
}
```

**Example 使用 CSV 檔案做為資料集**  
下列範例顯示存取名為 的 CSV 檔案所需的動作`{{ratings.csv}}`。  

```
"Action": [ "s3:GetObject" ],
"Resource": [
   "arn:aws:s3:::{{amzn-s3-demo-bucket}}/{{csvDataset}}/{{ratings.csv}}"
   ]
```

**Example 使用 Amazon S3 清查做為資料集**  
以下顯示 Amazon S3 清查清單檔案和資料檔案的範例資源。  

```
"Resource": [
   "arn:aws:s3:::myPrefix/{{amzn-s3-demo-bucket}}/myConfig-id/{{YYYY-MM-DDTHH-MMZ}}/manifest.json",
   "arn:aws:s3:::myPrefix/{{amzn-s3-demo-bucket}}/myConfig-id/data/*"
   ]
```

**Example 使用 ListObjectsV2 限制為資料夾字首**  
使用 [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) 時，會產生兩個政策。需要一個允許**列出**儲存貯體 (`ListBucket`) 的內容，另一個政策將允許**擷取儲存貯體 () 中的物件**`GetObject`。  
以下顯示動作、資源和條件的範例：  

```
"Action": [ "s3:ListBucket" ],
"Resource": [ "arn:aws:s3:::{{amzn-s3-demo-bucket}}" ],
"Condition": {
   "StringLike": {
      "s3:prefix": [ "/path/to/your/json/" ]
   }
}
```

```
"Action": [ "s3:GetObject" ],
"Resource": [ "arn:aws:s3:::{{amzn-s3-demo-bucket}}/path/to/your/json/*" ]
```
請注意， `GetObject`不會設定範圍，而您將針對物件使用萬用字元 (`*`)。