ItemReader - AWS Step Functions
ItemReader 필드 콘텐츠데이터 세트 예제데이터 세트에 대한 IAM 정책

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

ItemReader

ItemReader 필드는 데이터 세트와 해당 위치를 지정하는 JSON 객체입니다. Distributed Map 상태는 이 데이터 세트를 입력으로 사용합니다. 다음 예제에서는 데이터 세트가 Amazon S3 버킷에 저장된 CSV 파일인 경우의 ItemReader 필드 구문을 보여줍니다.

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

Workflow Studio의 항목 소스 필드에 데이터 세트와 해당 위치를 지정합니다.

ItemReader 필드 콘텐츠

데이터 세트에 따라 ItemReader 필드 콘텐츠가 달라집니다. 예를 들어 데이터 세트가 워크플로의 이전 단계에서 전달된 JSON 배열이면 ItemReader 필드는 생략됩니다. 데이터 세트가 Amazon S3 데이터 소스이면 이 필드에는 다음 하위 필드가 포함됩니다.

ReaderConfig

다음 세부 정보를 지정하는 JSON 객체:

  • InputType

    CSV 파일, 객체, JSON 파일 또는 Amazon S3 인벤토리 목록과 같은 Amazon S3 데이터 소스 유형을 지정합니다. Workflow Studio의 항목 소스 필드 아래에 있는 Amazon S3 항목 소스 드롭다운 목록에서 입력 유형을 선택할 수 있습니다.

  • CSVHeaderLocation

    참고

    CSV 파일을 데이터 세트로 사용하는 경우에만 이 필드를 지정해야 합니다.

    다음 값 중 하나를 수락하여 열 헤더 위치를 지정합니다.

    중요

    현재 Step Functions는 CSV 헤더를 최대 10KB까지 지원합니다.

    • 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 상태로 전달되는 데이터 항목 수를 제한합니다. 예를 들어 행 1,000개가 포함된 CSV 파일을 제공하고 한도를 100개로 지정한다고 가정해보겠습니다. 그러면 인터프리터는 행 100개만 Map 상태에 전달합니다. Map 상태는 헤더 행 다음부터 순차적으로 항목을 처리합니다.

    기본적으로 Map 상태는 지정된 데이터 세트의 모든 항목을 반복합니다.

    참고

    현재는 한도를 최대 100,000,000개까지 지정할 수 있습니다. Distributed Map 상태는 이 한도를 초과하는 항목을 읽지 않습니다.

    작은 정보

    Workflow Studio의 항목 소스 필드에 있는 추가 구성에서 이 옵션을 찾을 수 있습니다.

    또는 Distributed Map 상태 입력에서 기존 키-값 페어의 참조 경로를 지정할 수 있습니다. 이 경로는 양의 정수로 확인되어야 합니다. MaxItemsPath 하위 필드에 참조 경로를 지정합니다.

    중요

    MaxItems 또는 MaxItemsPath 하위 필드를 지정할 수 있지만 둘 다 함께 지정할 수는 없습니다.

Resource

지정된 데이터 세트에 따라 Step Functions에서 간접적으로 호출해야 하는 Amazon S3 API 작업입니다.

Parameters

데이터 세트가 저장되는 Amazon S3 버킷 이름과 객체 키를 지정하는 JSON 객체입니다.

중요

Amazon S3 버킷이 상태 시스템과 동일한 AWS 계정 및 AWS 리전에 있는지 확인하세요.

데이터 세트 예제

다음 옵션 중 하나를 데이터 세트로 지정할 수 있습니다.

중요

Step Functions에는 사용하는 Amazon S3 데이터 세트에 액세스할 수 있는 적절한 권한이 필요합니다. 데이터 세트에 대한 IAM 정책은 데이터 세트에 대한 IAM 정책을 참조하세요.

Distributed Map 상태는 워크플로의 이전 단계에서 전달된 JSON 입력을 허용할 수 있습니다. 이 입력은 배열이거나 특정 노드 내의 배열을 포함해야 합니다. 배열이 포함된 노드를 선택하려면 ItemsPath 필드를 사용하면 됩니다.

배열의 개별 항목을 처리하기 위해 Distributed Map 상태는 배열 항목마다 하위 워크플로 실행을 시작합니다. 다음 탭에서는 Map 상태에 전달된 입력과 하위 워크플로 실행에 대한 해당 입력의 예제를 보여줍니다.

참고

데이터 세트가 이전 단계의 JSON 배열이면 Step Functions에서 ItemReader 필드를 생략합니다.

Input passed to the Map state

항목 3개로 구성된 다음 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

Distributed Map 상태는 하위 워크플로 실행 3개를 시작합니다. 각 실행은 배열 항목을 입력으로 수신합니다. 다음 예제에서는 하위 워크플로 실행에서 수신한 입력을 보여줍니다.

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

Distributed Map 상태는 Amazon S3 버킷에 저장된 객체를 반복할 수 있습니다. 워크플로 실행이 Map 상태에 도달하면 Step Functions는 ListObjectsV2 API 작업을 간접적으로 호출하여 Amazon S3 객체 메타데이터 배열을 반환합니다. 이 배열의 각 항목에는 버킷에 저장된 데이터의 데이터(예: ETag 및 Key)가 포함됩니다.

배열의 개별 항목을 처리하기 위해 Distributed Map 상태는 하위 워크플로 실행을 시작합니다. 예를 들어 Amazon S3 버킷에 이미지 100개가 포함되어 있다고 가정해보겠습니다. 그러면 ListObjectsV2 API 작업을 간접적으로 호출한 후에 반환된 배열에는 항목 100개가 포함됩니다. 그런 다음 Distributed Map 상태는 하위 워크플로 실행 100개를 시작하여 각 배열 항목을 처리합니다.

참고

  • 현재 Step Functions에는 Amazon S3 콘솔을 사용하여 특정 Amazon S3 버킷에 만든 각 폴더에 대한 항목도 포함되어 있습니다. 이로 인해 Distributed Map 상태에서 추가 하위 워크플로 실행을 시작합니다. 폴더에 추가 하위 워크플로 실행을 만들지 않으려면 AWS CLI를 사용하여 폴더를 만드는 것이 좋습니다. 자세한 내용은 AWS Command Line Interface 사용 설명서의 Amazon S3 상위 수준 명령을 참조하세요.

  • Step Functions에는 사용하는 Amazon S3 데이터 세트에 액세스할 수 있는 적절한 권한이 필요합니다. 데이터 세트에 대한 IAM 정책은 데이터 세트에 대한 IAM 정책을 참조하세요.

다음 탭에서는 이 데이터 세트의 하위 워크플로 실행에 전달된 ItemReader 필드 구문과 입력의 예제를 보여줍니다.

ItemReader syntax

이 예시에서는 myBucket이라는 Amazon S3 버킷의 processData라는 접두사 내에 이미지, JSON 파일 및 객체가 포함된 데이터를 구성했습니다.

"ItemReader": {
    "Resource": "arn:aws:states:::s3:listObjectsV2",
    "Parameters": {
        "Bucket": "myBucket",
        "Prefix": "processData"
    }
}
Input passed to a child workflow execution

Distributed Map 상태는 Amazon S3 버킷에 있는 항목 수만큼 하위 워크플로 실행을 시작합니다. 다음 예제에서는 하위 워크플로 실행에서 수신한 입력을 보여줍니다.

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

Distributed Map 상태는 Amazon S3 버킷에 저장된 JSON 파일을 데이터 세트로 허용할 수 있습니다. JSON 파일에는 배열이 포함되어야 합니다.

워크플로 실행이 Map 상태에 도달하면 Step Functions는 GetObject API 작업을 간접적으로 호출하여 지정된 JSON 파일을 가져옵니다. 그러면 Map 상태가 배열의 각 항목을 반복하고 항목마다 하위 워크플로 실행을 시작합니다. 예를 들어 JSON 파일에 배열 항목 1,000개가 포함된 경우 Map 상태는 하위 워크플로 실행 1,000개를 시작합니다.

참고

  • 하위 워크플로 실행을 시작하는 데 사용되는 실행 입력은 256KB를 초과할 수 없습니다. 하지만 항목 크기를 줄이기 위해 선택적 ItemSelector 필드를 적용한 경우 Step Functions는 CSV 또는 JSON 파일에서 항목을 최대 8MB까지 읽을 수 있습니다.

  • 현재 Step Functions는 Amazon S3 인벤토리 보고서에서 개별 파일 최대 크기로 10GB를 지원합니다. 하지만 Step Functions는 각 개별 파일이 10GB 미만이면 10GB 넘게 처리할 수 있습니다.

  • Step Functions에는 사용하는 Amazon S3 데이터 세트에 액세스할 수 있는 적절한 권한이 필요합니다. 데이터 세트에 대한 IAM 정책은 데이터 세트에 대한 IAM 정책을 참조하세요.

다음 탭에서는 이 데이터 세트의 하위 워크플로 실행에 전달된 ItemReader 필드 구문과 입력의 예제를 보여줍니다.

이 예제의 경우 factcheck.json이라는 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

Distributed Map 상태는 JSON 파일에 있는 배열 항목 수만큼 하위 워크플로 실행을 시작합니다. 다음 예제에서는 하위 워크플로 실행에서 수신한 입력을 보여줍니다.

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

Distributed Map 상태는 Amazon S3 버킷에 저장된 CSV 파일을 데이터 세트로 허용할 수 있습니다. CSV 파일을 데이터 세트로 사용하는 경우에는 CSV 열 헤더를 지정해야 합니다. CSV 헤더를 지정하는 방법은 ItemReader 필드 콘텐츠를 참조하세요.

CSV 파일에서 데이터를 만들고 유지하기 위한 표준화된 형식이 없으므로 Step Functions는 다음 규칙에 따라 CSV 파일을 파싱합니다.

  • 쉼표(,)는 개별 필드를 구분하는 구분 기호입니다.

  • 줄 바꿈은 개별 레코드를 구분하는 구분 기호입니다.

  • 필드는 문자열로 취급됩니다. 데이터 유형 변환의 경우 ItemSelector에서 States.StringToJson 내장 함수를 사용합니다.

  • 문자열을 묶을 때 큰따옴표(“ ”)는 필요하지 않습니다. 그러나 큰따옴표로 묶인 문자열에는 구분 기호로 작동하지 않는 쉼표와 줄 바꿈이 포함될 수 있습니다.

  • 큰따옴표를 반복해서 사용하지 마세요.

  • 행의 필드 수가 헤더의 필드 수보다 적으면 Step Functions에서 누락된 값에 빈 문자열을 제공합니다.

  • 행의 필드 수가 헤더의 필드 수보다 많으면 Step Functions는 추가 필드를 건너뜁니다.

Step Functions에서 CSV 파일을 파싱하는 방법에 대한 자세한 내용은 Example of parsing an input CSV file를 참조하세요.

워크플로 실행이 Map 상태에 도달하면 Step Functions는 GetObject API 작업을 간접적으로 호출하여 지정된 CSV 파일을 가져옵니다. 그러면 Map 상태가 CSV 파일의 각 행을 반복하고 하위 워크플로 실행을 시작하여 각 행의 항목을 처리합니다. 예를 들어 입력으로 행 100개가 포함된 CSV 파일을 제공한다고 가정해보겠습니다. 그러면 인터프리터에서 각 행을 Map 상태에 전달합니다. Map 상태는 헤더 행 다음부터 순차적으로 항목을 처리합니다.

참고

  • 하위 워크플로 실행을 시작하는 데 사용되는 실행 입력은 256KB를 초과할 수 없습니다. 하지만 항목 크기를 줄이기 위해 선택적 ItemSelector 필드를 적용한 경우 Step Functions는 CSV 또는 JSON 파일에서 항목을 최대 8MB까지 읽을 수 있습니다.

  • 현재 Step Functions는 Amazon S3 인벤토리 보고서에서 개별 파일 최대 크기로 10GB를 지원합니다. 하지만 Step Functions는 각 개별 파일이 10GB 미만이면 10GB 넘게 처리할 수 있습니다.

  • Step Functions에는 사용하는 Amazon S3 데이터 세트에 액세스할 수 있는 적절한 권한이 필요합니다. 데이터 세트에 대한 IAM 정책은 데이터 세트에 대한 IAM 정책을 참조하세요.

다음 탭에서는 이 데이터 세트의 하위 워크플로 실행에 전달된 ItemReader 필드 구문과 입력의 예제를 보여줍니다.

ItemReader syntax

예를 들어 라는 ratings.csv라는 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

Distributed Map 상태는 헤더 행을 제외하고(파일에 있는 경우) CSV 파일에 있는 행 수만큼 하위 워크플로 실행을 시작합니다. 다음 예제에서는 하위 워크플로 실행에서 수신한 입력을 보여줍니다.

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

Distributed Map 상태는 Amazon S3 버킷에 저장된Amazon S3 인벤토리 매니페스트 파일을 데이터 세트로 허용할 수 있습니다.

워크플로 실행이 Map 상태에 도달하면 Step Functions는 GetObject API 작업을 간접적으로 호출하여 지정된 Amazon S3 인벤토리 매니페스트 파일을 가져옵니다. 그런 다음 Map 상태는 인벤토리의 객체를 반복하여 Amazon S3 인벤토리 객체 메타데이터 배열을 반환합니다.

참고

  • 현재 Step Functions는 Amazon S3 인벤토리 보고서에서 개별 파일 최대 크기로 10GB를 지원합니다. 하지만 Step Functions는 각 개별 파일이 10GB 미만이면 10GB 넘게 처리할 수 있습니다.

  • Step Functions에는 사용하는 Amazon S3 데이터 세트에 액세스할 수 있는 적절한 권한이 필요합니다. 데이터 세트에 대한 IAM 정책은 데이터 세트에 대한 IAM 정책을 참조하세요.

다음은 CSV 형식의 인벤토리 파일에 대한 예제입니다. 이 파일에는 sourceBucket이라는 Amazon S3 버킷에 저장되어 있는 csvDataset 및 imageDataset 객체가 포함되어 있습니다.

"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 정책을 자동으로 생성할 수 있습니다. 이러한 정책에는 상태 시스템 역할에서 Distributed Map 상태에 대한 StartExecution API 작업을 간접적으로 호출하도록 허용하는 데 필요한 최소 권한이 포함되어 있습니다. 또한 이러한 정책에는 Step Functions에서 Amazon S3 버킷과 객체, Lambda 함수와 같은 AWS 리소스에 액세스하는 데 필요한 최소 권한이 포함되어 있습니다. IAM 정책에 필요한 권한만 포함하는 것이 좋습니다. 예를 들어 워크플로에 분산 모드의 Map 상태가 포함된 경우 정책 범위를 데이터 세트가 포함된 특정 Amazon S3 버킷과 폴더로 좁힙니다.

중요

Distributed Map 상태 입력에 있는 기존 키-값 페어에 대한 참조 경로를 사용하여 Amazon S3 버킷과 객체 또는 접두사를 지정하는 경우 워크플로에 대한 IAM 정책을 업데이트해야 합니다. 정책 범위를 런타임 시 경로에서 확인하는 버킷과 객체 이름으로 좁히세요.

다음 IAM 정책 예제에서는 ListObjectsV2 및 GetObject API 작업을 사용하여 Amazon S3 데이터 세트에 액세스하는 데 필요한 최소 권한을 부여합니다.

예 Amazon S3 객체를 데이터 세트로 사용하는 IAM 정책

다음 예제에서는 myBucket이라는 Amazon S3 버킷의 processImages 내에 구성된 객체에 액세스할 수 있는 최소 권한을 부여하는 IAM 정책을 보여줍니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::myBucket"
            ],
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "processImages"
                    ]
                }
            }
        }
    ]
}
예 CSV 파일을 데이터 세트로 사용하는 IAM 정책

다음 예제에서는 ratings.csv라는 CSV 파일에 액세스할 수 있는 최소 권한을 부여하는 IAM 정책을 보여줍니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::myBucket/csvDataset/ratings.csv"
            ]
        }
    ]
}
예 Amazon S3 인벤토리를 데이터 세트로 사용하는 IAM 정책

다음 예제에서는 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/*"
            ]
        }
    ]
}