本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
ItemReader
欄位是 JSON 物件,可指定資料集及其位置。分散式映射狀態使用此資料集做為其輸入。
下列範例顯示 JSONPath 型工作流程中ItemReader
欄位的語法,適用於存放在 Amazon S3 儲存貯體中的 CSV 檔案中的資料集。
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "FIRST_ROW"
},
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "myBucket
",
"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
"
}
}
提示
在 Workflow Studio 中,您可以在項目來源欄位中指定資料集及其位置。
ItemReader 欄位的內容
根據您的資料集, ItemReader
欄位的內容會有所不同。例如,如果您的資料集是從工作流程中上一個步驟傳遞的 JSON 陣列,則會省略 ItemReader
欄位。如果您的資料集是 Amazon S3 資料來源,此欄位會包含下列子欄位。
ReaderConfig
指定下列詳細資訊的 JSON 物件:
InputType
接受下列其中一個值:
CSV
、JSON
、MANIFEST
。指定 Amazon S3 資料來源的類型,例如 CSV 檔案、物件、JSON 檔案或 Amazon S3 清查清單。在 Workflow Studio 中,您可以從項目來源欄位下的 Amazon S3 項目來源下拉式清單中選取輸入類型。
CSVHeaderLocation
注意
只有在使用 CSV 檔案做為資料集時,才必須指定此欄位。
接受下列其中一個值來指定資料欄標頭的位置:
重要
目前,Step Functions 支援高達 10 KiB 的 CSV 標頭。
FIRST_ROW
– 如果檔案的第一行是 標頭,請使用此選項。GIVEN
– 使用此選項在狀態機器定義中指定標頭。例如,如果您的 CSV 檔案包含下列資料。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"
] } }
提示
在 Workflow Studio 中,您可以在項目來源欄位中的其他組態下找到此選項。
MaxItems
限制傳遞至
Map
狀態的資料項目數量。例如,假設您提供的 CSV 檔案包含 1000 個資料列,並指定限制為 100。然後,解譯器只會將 100 列傳遞至Map
狀態。Map
狀態會依序處理項目,從標頭列開始。根據預設,
Map
狀態會反覆運算指定資料集中的所有項目。注意
目前,您最多可以指定 100,000,000 個。分散式映射狀態會停止讀取超出此限制的項目。
提示
在 Workflow Studio 中,您可以在項目來源欄位中的其他組態下找到此選項。
或者,您可以在分散式映射狀態輸入中指定現有鍵值對的參考路徑。此路徑必須解析為正整數。您可以在
MaxItemsPath
子欄位中指定參考路徑。重要
您可以指定
MaxItems
或MaxItemsPath
子欄位,但不能同時指定兩者。
Resource
Step Functions 必須根據指定的資料集叫用 Amazon S3 API 動作。
Parameters
JSON 物件,指定資料集存放所在的 Amazon S3 儲存貯體名稱和物件金鑰。在此欄位中,如果儲存貯體已啟用版本控制,您也可以提供 Amazon S3 物件版本。
重要
請確定您的 Amazon S3 儲存貯體與您的狀態機器位於相同 AWS 帳戶 和 AWS 區域 之下。
資料集的範例
您可以指定下列其中一個選項做為資料集:
重要
Step Functions 需要適當的許可才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊,請參閱資料集的 IAM 政策。
分散式映射狀態可以接受從工作流程中上一個步驟傳遞的 JSON 輸入。此輸入必須是陣列,或在特定節點中包含陣列。若要選取包含陣列的節點,您可以使用 ItemsPath (JSONPath僅限地圖)
欄位。
若要處理陣列中的個別項目,分散式映射狀態會為每個陣列項目啟動子工作流程執行。下列索引標籤顯示傳遞至 Map
狀態的輸入範例,以及傳遞至子工作流程執行的對應輸入。
注意
當資料集是上一個步驟的 JSON 陣列時,Step Functions 會省略 ItemReader
欄位。
分散式映射狀態可以反覆運算存放在 Amazon S3 儲存貯體中的物件。當工作流程執行達到 Map
狀態時,Step Functions 會叫用 ListObjectsV2 API 動作,這會傳回 Amazon S3 物件中繼資料的陣列。在此陣列中,每個項目都包含儲存貯體中資料的資料,例如 ETag 和 Key。
若要處理陣列中的個別項目,分散式映射狀態會啟動子工作流程執行。例如,假設您的 Amazon S3 儲存貯體包含 100 個映像。然後,調用 ListObjectsV2
API 動作後傳回的陣列包含 100 個項目。分散式映射狀態接著會啟動 100 個子工作流程執行,以處理每個陣列項目。
注意
目前,Step Functions 也包含您使用 Amazon S3 主控台在特定 Amazon S3 儲存貯體中建立的每個資料夾的項目。這會導致由分散式映射狀態啟動的額外子工作流程執行。為了避免為資料夾建立額外的子工作流程執行,我們建議您使用 AWS CLI 來建立資料夾。如需詳細資訊,請參閱AWS Command Line Interface 《 使用者指南》中的高階 Amazon S3 命令。
Step Functions 需要適當的許可才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊,請參閱資料集的 IAM 政策。
下列索引標籤顯示 ItemReader
欄位語法的範例,以及傳遞給此資料集子工作流程執行的輸入。
分散式映射狀態可以接受存放在 Amazon S3 儲存貯體中的 JSON 檔案做為資料集。JSON 檔案必須包含陣列。
當工作流程執行達到 Map
狀態時,Step Functions 會叫用 GetObject API 動作來擷取指定的 JSON 檔案。接著Map
狀態會反覆運算陣列中的每個項目,並為每個項目啟動子工作流程執行。例如,如果您的 JSON 檔案包含 1000 個陣列項目,Map
狀態會啟動 1000 個子工作流程執行。
注意
用來啟動子工作流程執行的執行輸入不能超過 256 KiB。不過,如果您接著套用選用
ItemSelector
欄位來減少項目的大小,Step Functions 支援從 CSV 或 JSON 檔案讀取最多 8 MB 的項目。目前,Step Functions 支援 10 GB 作為 Amazon S3 中個別檔案的大小上限。
Step Functions 需要適當的許可才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊,請參閱資料集的 IAM 政策。
下列索引標籤顯示 ItemReader
欄位語法的範例,以及傳遞給此資料集子工作流程執行的輸入。
在此範例中,假設您有一個名為 的 JSON 檔案
。您已將此檔案存放在 Amazon S3 儲存貯體factcheck.json
中名為 的字首中。以下是 JSON 資料集的範例。jsonDataset
[
{
"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 儲存貯體中的 CSV 檔案做為資料集。如果您使用 CSV 檔案做為資料集,則需要指定 CSV 資料欄標頭。如需有關如何指定 CSV 標頭的資訊,請參閱 ItemReader 欄位的內容。
Step Functions 根據下列規則剖析 CSV 檔案:
-
逗號 (,) 是分隔欄位的分隔符號。
-
Newlines 是分隔記錄的分隔符號。
-
欄位視為字串。對於資料類型轉換,請使用 中的
States.StringToJson
內部 函數ItemSelector (地圖)。 -
不需要雙引號 (" ") 來括住字串。不過,以雙引號括住的字串可包含逗號和新行,而不做為記錄分隔符號。
-
您可以重複雙引號來保留雙引號。
-
如果資料列中的欄位數目少於標頭中的欄位數目,Step Functions 會提供缺少值的空白字串。
-
如果資料列中的欄位數目超過標頭中的欄位數目,Step Functions 會略過其他欄位。
如需 Step Functions 如何剖析 CSV 檔案的詳細資訊,請參閱 Example of parsing an input CSV file。
當工作流程執行達到 Map
狀態時,Step Functions 會叫用 GetObject API 動作來擷取指定的 CSV 檔案。接著Map
狀態會反覆運算 CSV 檔案中的每一列,並啟動子工作流程執行,以處理每一列中的項目。例如,假設您提供的 CSV 檔案包含 100 列做為輸入。然後,解譯器會將每一列傳遞至 Map
狀態。Map
狀態會以序列順序處理項目,從標頭列開始。
注意
用來啟動子工作流程執行的執行輸入不能超過 256 KiB。不過,如果您接著套用選用
ItemSelector
欄位來減少項目的大小,Step Functions 支援從 CSV 或 JSON 檔案讀取最多 8 MB 的項目。目前,Step Functions 支援 10 GB 作為 Amazon S3 中個別檔案的大小上限。
Step Functions 需要適當的許可,才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊,請參閱資料集的 IAM 政策。
下列索引標籤顯示 ItemReader
欄位語法的範例,以及傳遞給此資料集子工作流程執行的輸入。
分散式映射狀態可以接受存放在 Amazon S3 儲存貯體中的 Amazon S3 清查資訊清單檔案做為資料集。
當工作流程執行達到 Map
狀態時,Step Functions 會叫用 GetObject API 動作來擷取指定的 Amazon S3 清查清單檔案。接著Map
狀態會反覆運算庫存中的物件,以傳回 Amazon S3 庫存物件中繼資料的陣列。
注意
目前,Step Functions 支援 10 GB 作為解壓縮後 Amazon S3 清查報告中個別檔案的大小上限。不過,如果每個檔案小於 10 GB,Step Functions 可以處理超過 10 GB 的 。
Step Functions 需要適當的許可,才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊,請參閱資料集的 IAM 政策。
以下是 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 使用者指南》中的 Amazon S3 庫存。 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
欄位語法的範例,以及傳遞給此資料集子工作流程執行的輸入。
資料集的 IAM 政策
當您使用 Step Functions 主控台建立工作流程時,Step Functions 可以根據您工作流程定義中的資源自動產生 IAM 政策。這些政策包含允許狀態機器角色叫用分散式映射狀態 StartExecution
API 動作所需的最低權限。這些政策也包含存取 AWS 資源所需的最低權限 Step Functions,例如 Amazon S3 儲存貯體和物件,以及 Lambda 函數。強烈建議您只包含 IAM 政策中必要的許可。例如,如果您的工作流程包含分散式模式中Map
的狀態,請將您的政策範圍縮小到包含資料集的特定 Amazon S3 儲存貯體和資料夾。
重要
如果您指定 Amazon S3 儲存貯體和物件或字首,並在分散式映射狀態輸入中包含現有索引鍵/值對的參考路徑,請確定您更新工作流程的 IAM 政策。將政策範圍向下延伸至 儲存貯體,並在執行時間將路徑解析為 的物件名稱。
下列 IAM 政策範例授予使用 ListObjectsV2 和 GetObject API 動作存取 Amazon S3 資料集所需的最低權限。
範例 Amazon S3 物件的 IAM 政策做為資料集
下列範例顯示 IAM 政策,授予最低權限來存取名為 的 Amazon S3 儲存貯
體中在 中組織的物件processImages
。amzn-s3-demo-bucket
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket
"
],
"Condition": {
"StringLike": {
"s3:prefix": [
"processImages
"
]
}
}
}
]
}
範例 CSV 檔案的 IAM 政策做為資料集
下列範例顯示 IAM 政策,授予存取名為 之 CSV 檔案的最低權限
。ratings.csv
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket
/csvDataset
/ratings.csv
"
]
}
]
}
範例 Amazon S3 清查作為資料集的 IAM 政策
下列範例顯示 IAM 政策,授予存取 Amazon S3 清查報告的最低權限。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::destination-prefix
/amzn-s3-demo-bucket
/config-ID
/YYYY-MM-DDTHH-MMZ
/manifest.json",
"arn:aws:s3:::destination-prefix
/amzn-s3-demo-bucket
/config-ID
/data/*"
]
}
]
}