ItemReader （地圖）

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

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

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

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

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

分散式地圖狀態可以反覆查看存放在 Amazon S3 儲存貯體中的物件。當工作流程執行達到 Map 狀態時，Step Functions 會叫用 ListObjectsV2 API 動作，這會傳回 Amazon S3 物件中繼資料的陣列。在此陣列中，每個項目都包含儲存貯體中實際資料的資料，例如 ETag 和 Key。

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

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

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

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

使用 LOAD_AND_FLATTEN選項，您的狀態機器會執行下列動作：

使用轉換選項，您不再需要巢狀分散式地圖來處理中繼資料。使用 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"
   }
}

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

當工作流程執行達到 Map 狀態時，Step Functions 會叫用 GetObject 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 個子工作流程執行。

下列索引標籤顯示 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"
  },
  ...
]

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

下列索引標籤顯示 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"}

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

Step Functions 會根據下列規則剖析以文字分隔的檔案：

如需 Step Functions 如何剖析以文字分隔檔案的詳細資訊，請參閱 Example of parsing an input CSV file。

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

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

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

使用 Parquet 檔案時，適用下列條件：

以下顯示將 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"
   }
}

您可以使用從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')

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

此功能可以處理來自 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"
   }
}

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

當工作流程執行達到 Map 狀態時，Step Functions 會叫用 GetObject API 動作來擷取指定的 Amazon S3 清查清單檔案。

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

如果您指定 ManifestType 為 S3_INVENTORY，則無法指定 InputType。

以下是 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"
...

下列 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 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。