ItemReader (地圖) - AWS Step Functions
該 ItemReader 領域的內容資料集範例IAM資料集的政策

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

ItemReader (地圖)

該ItemReader字段是一個JSON對象，它指定了一個數據集和它的位置。「分散式地圖」狀態會使用此資料集做為其輸入。下列範例顯示如果您的資料集是存放在 Amazon S3 儲存貯體中的CSV檔案，則該ItemReader欄位的語法。

"ItemReader": {
    "ReaderConfig": {
        "InputType": "CSV",
        "CSVHeaderLocation": "FIRST_ROW"
    },
    "Resource": "arn:aws:states:::s3:getObject",
    "Parameters": {
        "Bucket": "myBucket",
        "Key": "csvDataset/ratings.csv"
    }
}
提示

在工作流程 Studio 中，您可以在 [項目來源] 欄位中指定資料集及其位置。

該 ItemReader 領域的內容

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

ReaderConfig

指定下列詳細資訊的JSON物件：

  • InputType

    指定 Amazon S3 資料來源的類型，例如CSV檔案、物件、JSON檔案或 Amazon S3 庫存清單。在工作流程 Studio 中，您可以從「項目來源」欄位下的 Amazon S3 項目來源下拉式清單中選取輸入類型。

  • CSVHeaderLocation

    注意

    只有在使用CSV檔案作為資料集時，才必須指定此欄位。

    接受下列其中一個值來指定欄標題的位置：

    重要

    目前，Step Functions 支援高達 10 KB 的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"
        ]
    }
}
    提示

    在工作流 Studio 中，您可以在 [項目來源] 欄位中的 [其他組態] 下找到此選項。

  • MaxItems

    限制傳遞至Map狀態的資料項目數。例如，假設您提供的CSV檔案包含 1000 個資料列，並指定限制為 100。然後，解釋器只傳遞 100 行的Map狀態。狀Map態會以連續順序處理項目，從標題列之後開始。

    根據預設，Mapstate 會重複執行指定資料集中的所有項目。

    注意

    目前，您可以指定最多 100 萬的限制。「分散式地圖」狀態會停止讀取超過此限制的項目。

    提示

    在工作流 Studio 中，您可以在 [項目來源] 欄位中的 [其他組態] 下找到此選項。

    或者，您可以指定分散式映射狀態輸入中現有鍵值對的參考路徑。此路徑必須解析為正整數。您可以在MaxItemsPath子欄位中指定參照路徑。

    重要

    您可以指定MaxItems或MaxItemsPath子欄位，但不能同時指定兩者。

Resource

Step Functions 必須根據指定的資料集叫用的 Amazon S3 API 動作。

Parameters

JSON物件，指定資料集所在的 Amazon S3 儲存貯體名稱和物件金鑰。

重要

確保您的 Amazon S3 儲存貯體與狀態機器位於相 AWS 區域 同 AWS 帳戶 的狀態機器之下。

資料集範例

您可以指定下列其中一個選項作為資料集：

重要

Step Functions 需要適當的許可才能存取您使用的 Amazon S3 資料集。如需資料集IAM原則的相關資訊，請參閱IAM資料集的政策。

「分散式貼圖」狀態可以接受從工作流程中先前步驟傳遞的JSON輸入。此輸入必須是陣列，或者必須包含特定節點內的陣列。若要選取包含陣列的節點，您可以使用ItemsPath (地圖)欄位。

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

注意

當您的資料集是上一個步驟的JSON陣列時，Step Functions 會省略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 儲存貯體中的物件。當工作流程執行到達Map狀態時，Step Functions 數會叫用 ListObjectsV2 API 動作，該動作會傳回 Amazon S3 物件中繼資料的陣列。在此陣列中，每個項目都包含儲存在值區中之資料的資料，例如ETag和 Key。

若要處理陣列中的個別項目，「分散式對應」狀態會啟動子工作流程執行。例如，假設您的 Amazon S3 儲存貯體包含 100 個映像檔。然後，調用ListObjectsV2API動作後返回的數組包含 100 個項目。然後，「分散式對應」狀態會啟動 100 個子工作流程執行，以處理每個陣列項目。

注意

  • 目前，Step Functions 還包括您使用 Amazon S3 主控台在特定 Amazon S3 儲存貯體中建立的每個資料夾的項目。這會導致由「分散式地圖」狀態啟動的額外子工作流程執行。若要避免為資料夾建立額外的子工作流程執行，建議您使 AWS CLI 用建立資料夾。如需詳細資訊，請參閱AWS Command Line Interface 使用者指南中的高階 Amazon S3 命令。

  • Step Functions 需要適當的許可才能存取您使用的 Amazon S3 資料集。如需資料集IAM原則的相關資訊，請參閱IAM資料集的政策。

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

ItemReader syntax

在此範例中，您已將資料 (包括映像、JSON檔案和物件) 組織在名為的 Amazon S3 儲存貯體processData中命名的前綴內myBucket。

"ItemReader": {
    "Resource": "arn:aws:states:::s3:listObjectsV2",
    "Parameters": {
        "Bucket": "myBucket",
        "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 儲存貯體中的JSON檔案做為資料集。該JSON文件必須包含一個數組。

當工作流程執行到達狀Map態時，「Step Functions」會叫用GetObjectAPI動作來擷取指定的JSON檔案。然後，Map狀態會重複執行陣列中的每個項目，並針對每個項目啟動子工作流程執行。例如，如果您的JSON檔案包含 1000 個陣列項目，則Map狀態會啟動 1000 個子工作流程執行。

注意

  • 用於啟動子工作流程執行的執行輸入不能超過 256 KB。但是，如果您接著套用選擇性ItemSelector欄位以減少項目大小，則 Step Functions 支援從CSV或JSON檔案讀取最多 8 MB 的項目。

  • 目前，Step Functions 支援 10 GB 作為 Amazon S3 庫存報告中個別檔案的大小上限。不過，如果每個個別檔案小於 10 GB，則 Step Functions 可以處理超過 10 GB。

  • Step Functions 需要適當的許可才能存取您使用的 Amazon S3 資料集。如需資料集IAM原則的相關資訊，請參閱IAM資料集的政策。

下列索引標籤顯示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": "myBucket",
        "Key": "jsonDataset/factcheck.json"
    }
}
Input to a child workflow execution

「分散式地圖」狀態會啟動與JSON檔案中存在的陣列項目數目相同的子工作流程執行次數。下列範例顯示子工作流程執行所接收的輸入。

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

分散式地圖狀態可以接受存放在 Amazon S3 儲存貯體中的CSV檔案做為資料集。如果您使用CSV檔案做為資料集，則必須指定資料CSV欄標題。若要取得有關如何指定CSV標頭的資訊，請參閱〈〉該 ItemReader 領域的內容。

因為沒有標準化的格式來建立和維護CSV檔案中的資料，因此 Step Functions 會根據下列規則剖析CSV檔案：

  • 逗號 (,) 是用來分隔個別欄位的分隔符號。

  • 換行符是分隔各個記錄的分隔符。

  • 欄位會被視為字串。對於資料類型轉換，請使用中的States.StringToJson內建函數。ItemSelector (地圖)

  • 括住字串時不需要雙引號 (」「)。但是，以雙引號括住的字串可以包含逗號和換行符，而不會用作分隔符號。

  • 通過重複它們來逃避雙引號。

  • 如果資料列中的欄位數目小於標頭中的欄位數目，Step Functions 會為遺漏值提供空字串。

  • 如果列中的欄位數目大於標題中的欄位數目，則「Step Functions 數」會略過其他欄位。

如需「Step Functions」如何剖析CSV檔案的詳細資訊，請參閱Example of parsing an input CSV file。

當工作流程執行到達狀Map態時，「Step Functions」會叫用GetObjectAPI動作來擷取指定的CSV檔案。然後，Map狀態會重複執行CSV檔案中的每一列，並啟動子工作流程執行，以處理每一列中的項目。例如，假設您提供的CSV檔案包含 100 列作為輸入。然後，解釋器將每一行傳遞給Map狀態。狀Map態會以序列順序處理項目，從標題列之後開始。

注意

  • 用於啟動子工作流程執行的執行輸入不能超過 256 KB。但是，如果您接著套用選擇性ItemSelector欄位以減少項目大小，則 Step Functions 支援從CSV或JSON檔案讀取最多 8 MB 的項目。

  • 目前，Step Functions 支援 10 GB 作為 Amazon S3 庫存報告中個別檔案的大小上限。不過，如果每個個別檔案小於 10 GB，則 Step Functions 可以處理超過 10 GB。

  • Step Functions 需要適當的許可才能存取您使用的 Amazon S3 資料集。如需資料集IAM原則的相關資訊，請參閱IAM資料集的政策。

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

ItemReader syntax

例如，假設您有一個CSV名為ratings.csv. 然後，您已將此檔案存放在 Amazon S3 儲存貯體csvDataset中命名的前置詞中。

{
  "ItemReader": {
    "ReaderConfig": {
      "InputType": "CSV",
      "CSVHeaderLocation": "FIRST_ROW"
    },
    "Resource": "arn:aws:states:::s3:getObject",
    "Parameters": {
      "Bucket": "myBucket",
      "Key": "csvDataset/ratings.csv"
    }
  }
}
Input to a child workflow execution

「分散式地圖」狀態開始的子工作流程執行次數與CSV檔案中存在的列數相同，但不包括標題列 (如果在檔案中)。下列範例顯示子工作流程執行所接收的輸入。

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

分散式地圖狀態可以接受以資料集形式存放在 Amazon S3 儲存貯體中的 Amazon S3 庫存資訊清單檔案。

當工作流程執行到達狀Map態時，Step Functions 會叫用GetObjectAPI動作以擷取指定的 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 儲存貯體中sourceBucket。

"sourceBucket","csvDataset/","0","2022-11-16T00:27:19.000Z"
"sourceBucket","csvDataset/titles.csv","3399671","2022-11-16T00:29:32.000Z"
"sourceBucket","imageDataset/","0","2022-11-15T20:00:44.000Z"
"sourceBucket","imageDataset/n02085620_10074.jpg","27034","2022-11-15T20:02:16.000Z"
...
重要

目前，Step Functions 不支援使用者定義的 Amazon S3 庫存報告作為資料集。您還必須確保 Amazon S3 庫存報告的輸出格式為CSV。如需 Amazon S3 庫存以及如何設定的詳細資訊，請參閱 Amazon S3 使用者指南中的 Amazon S3 庫存。

下列詳細目錄資訊清單檔案範例顯示詳細目錄物件中繼資料的CSV標頭。

{
  "sourceBucket" : "sourceBucket",
  "destinationBucket" : "arn:aws:s3:::inventory",
  "version" : "2016-11-30",
  "creationTimestamp" : "1668560400000",
  "fileFormat" : "CSV",
  "fileSchema" : "Bucket, Key, Size, LastModifiedDate",
  "files" : [ {
    "key" : "source-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": "destinationBucket",
      "Key": "destination-prefix/source-bucket/config-ID/YYYY-MM-DDTHH-MMZ/manifest.json"
    }
  }
}
Input to a child workflow execution
{
  "LastModifiedDate": "2022-11-16T00:29:32.000Z",
  "Bucket": "sourceBucket",
  "Size": "3399671",
  "Key": "csvDataset/titles.csv"
}

根據您在設定 Amazon S3 庫存報告時選取的欄位，manifest.json檔案內容可能與顯示的範例有所不同。

IAM資料集的政策

當您使用 Step Functions 主控台建立工作流程時，Step Functions 可以根據工作流程定義中的資源自動產生IAM原則。這些原則包括允許狀態機器角色呼叫分散式對應狀態StartExecutionAPI動作所需的最低權限。這些政策還包括存取 AWS 資源所需的最低權限 Step Functions，例如 Amazon S3 儲存貯體和物件以及 Lambda 函數。我們強烈建議您僅在IAM原則中加入必要的權限。例如，如果您的工作流程包含分散式模式的Map狀態，請將您的政策範圍縮減到包含資料集的特定 Amazon S3 儲存貯體和資料夾。

重要

如果您指定 Amazon S3 儲存貯體和物件或前綴，其中包含指向分散式地圖狀態輸入中現有鍵值組的參考路徑，請確定您已更新工作流程的IAM政策。將政策範圍縮小到值區和路徑在執行時期解析為的物件名稱。

下列IAM政策範例授與使用 ListObjectsV2 和GetObjectAPI動作存取 Amazon S3 資料集所需的最低權限。

範例 IAM將 Amazon S3 物件做為資料集的政策

下列範例顯示一項IAM政策，該政策授與存取名為的 Amazon S3 儲存貯體processImages中組織的物件的最低權限myBucket。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::myBucket"
            ],
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "processImages"
                    ]
                }
            }
        }
    ]
}
範例 IAM將CSV檔案作為資料集的政策

下列範例顯示的IAM原則會授與存取名為之CSV檔案的最少權限ratings.csv。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::myBucket/csvDataset/ratings.csv"
            ]
        }
    ]
}
範例 IAM將 Amazon S3 庫存作為資料集的政策

下列範例顯示授與存取 Amazon S3 庫存報告之最少權限的IAM政策。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::destination-prefix/source-bucket/config-ID/YYYY-MM-DDTHH-MMZ/manifest.json",
                "arn:aws:s3:::destination-prefix/source-bucket/config-ID/data/*"
            ]
        }
    ]
}