기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# ItemReader(맵)
`ItemReader` 필드는 데이터세트와 해당 위치를 지정하는 JSON 객체입니다. *Distributed Map 상태*는 이 데이터세트를 입력으로 사용합니다.
다음 예제는 Amazon S3 버킷에 저장된 텍스트로 구분된 파일의 데이터세트에 대한 **JSONPath 기반** 워크플로의 `ItemReader` 필드 구문을 보여줍니다.
```
"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 필드 콘텐츠
데이터세트에 따라 `ItemReader` 필드 콘텐츠가 달라집니다. 예를 들어 데이터세트가 워크플로의 이전 단계에서 전달된 JSON 배열이면 `ItemReader` 필드는 생략됩니다. 데이터세트가 Amazon S3 데이터 소스이면 이 필드에는 다음 하위 필드가 포함됩니다.
**`Resource`**
`arn:aws:states:::s3:getObject`와 같이 Step Functions에서 사용할 Amazon S3 API 통합 작업
**`Arguments (JSONata) or Parameters (JSONPath)`**
데이터세트가 저장되는 Amazon S3 버킷 이름과 객체 키를 지정하는 JSON 객체입니다.
버킷에 버전 관리가 활성화된 경우 Amazon S3 객체 버전을 제공할 수도 있습니다.
**`ReaderConfig`**
다음 세부 정보를 지정하는 JSON 객체:
+ `InputType`
`CSV`, `JSON`, `JSONL`, `PARQUET`, `MANIFEST` 값 중 하나를 허용합니다.
텍스트로 구분된 파일(`CSV`), 객체, JSON 파일, JSON 라인, Parquet 파일, Athena 매니페스트 또는 Amazon S3 inventory 목록과 같은 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`로 설정된 경우 유형이 `CSV`로 가정되므로 `InputType`도 지정해서는 **안 됩니다**.
+ `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는 텍스트로 구분된 파일에 대해 최대 10KiB의 헤더를 지원합니다.
+ `ItemsPointer`
*선택 사항*. 이 인 경우이 필드를 지정할 수 `InputType` 있습니다`JSON`.
`ItemsPointer`는 JSONPointer 구문을 사용하여 JSON 파일 내에 중첩된 특정 배열 또는 객체를 선택합니다. JSONPointer는 JSON 문서 내에서 위치를 탐색하고 참조하기 위해 독점적으로 설계된 표준화된 구문입니다.
JSONPointer 구문은 슬래시(/)를 사용하여 각 중첩 수준을 구분하며 배열 인덱스는 대괄호 없이 숫자로 표시됩니다. 예제:
+ `/Data/Contents` - 데이터 객체 내의 콘텐츠 배열을 참조합니다.
+ `/Data/Contents/0` - 콘텐츠 배열의 첫 번째 요소를 참조합니다.
대상 배열의 시작 위치는 JSON 파일의 처음 16MB 이내여야 하며, JSONPointer 경로의 길이는 2,000자 미만이어야 합니다.
예를 들어 JSON 파일에 다음이 포함된 경우:
```
{"data": {"items": [{"id": 1}, {"id": 2}]}}
```
항목 배열을 처리`"ItemsPointer": "/data/items"`하도록를 지정합니다.
+ `MaxItems`
기본적으로 `Map` 상태는 지정된 데이터세트의 모든 항목을 반복합니다. `MaxItems`를 설정하면 `Map` 상태로 전달되는 데이터 항목 수를 제한합니다. 예를 들어 1,000개의 행이 포함된 텍스트로 구분된 파일을 제공하고 제한을 100으로 설정하면 인터프리터는 100개의 행*만* *Distributed Map 상태*로 전달합니다. `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일 업데이트됨)
새 `Transformation` 파라미터를 사용하면 `LOAD_AND_FLATTEN` 값을 지정할 수 있으며 맵은 `S3:ListObjectsV2`에 대한 직접 호출의 결과 목록에서 참조된 **실제 **데이터 객체를 읽습니다.
이 릴리스 이전에는 메타데이터를 **검색**한 다음 실제 데이터를 **처리**하기 위해 중첩 Distributed Map을 생성해야 합니다. 첫 번째 맵은 `S3:ListObjectsV2`에서 반환된 **메타데이터**를 반복하고 하위 워크플로를 간접 호출합니다. 각 하위 상태 머신 내의 다른 맵은 개별 파일에서 **실제 데이터**를 읽습니다. 트랜스포메이션 옵션을 사용하면 두 단계를 한 번에 완료할 수 있습니다.
시스템에서 시간별로 생성하고 Amazon S3에 저장하는 지난 24개의 로그 파일에 대해 일일 감사를 실행하려고 한다고 가정해 보겠습니다. Distributed Map 상태는 `S3:ListObjectsV2`를 사용하여 로그 파일을 나열한 다음 각 객체의 *메타데이터*를 반복하거나 이제 Amazon S3 버킷에 저장된 **실제 데이터 **객체를 로드하고 분석할 수 있습니다.
`LOAD_AND_FLATTEN` 옵션을 사용하면 확장성을 높이고, 열린 맵 실행 수를 줄이고, 여러 객체를 동시에 처리할 수 있습니다. 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 %}"
}
},
...
}
}
```
## 데이터세트 예제
다음 옵션 중 하나를 데이터세트로 지정할 수 있습니다.
+ [이전 단계의 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 Inventory(여러 항목 처리)](#itemsource-example-s3-inventory)
**참고**
Step Functions에는 사용하는 Amazon S3 데이터세트에 액세스할 수 있는 적절한 권한이 필요합니다. 데이터세트에 대한 IAM 정책은 [데이터세트에 대한 IAM 정책 권장 사항](#itemreader-iam-policies) 섹션을 참조하세요.
### 이전 단계의 JSON 데이터
*Distributed Map 상태*는 워크플로의 이전 단계에서 전달된 JSON 입력을 허용할 수 있습니다.
입력은 JSON 배열, JSON 객체 또는 JSON 객체의 노드 내 배열일 수 있습니다.
Step Functions는 배열의 요소 또는 JSON 객체의 키-값 페어에 대해 직접 반복합니다.
입력에서 중첩된 JSON 배열 또는 객체가 포함된 특정 노드를 선택하려면 `ItemsPath(Map, JSONPath만 해당)`를 사용하거나 JSONata 상태의 `Items` 필드에 JSONata 표현식을 사용할 수 있습니다.
개별 항목을 처리하기 위해 *Distributed Map 상태*는 항목마다 하위 워크플로 실행을 시작합니다. 다음 탭에서는 `Map` 상태에 전달된 입력과 하위 워크플로 실행에 대한 해당 입력의 예제를 보여줍니다.
**참고**
데이터세트가 이전 단계의 JSON 데이터인 경우에는 `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"
}
```
------
### Amazon S3 객체 목록
*Distributed Map 상태*는 Amazon S3 버킷에 저장된 객체를 반복할 수 있습니다. 워크플로 실행이 `Map` 상태에 도달하면 Step Functions는 [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) API 작업을 간접적으로 호출하여 Amazon S3 **객체 메타데이터** 배열을 반환합니다. 이 배열의 각 항목에는 버킷에 저장된 실제 데이터의 데이터(예: **ETag** 및 **Key**)가 포함됩니다.
배열의 개별 항목을 처리하기 위해 *Distributed Map 상태*는 하위 워크플로 실행을 시작합니다. 예를 들어 Amazon S3 버킷에 이미지 100개가 포함되어 있다고 가정해보겠습니다. 그러면 `ListObjectsV2` API 작업을 간접적으로 호출한 후에 반환된 배열에는 메타데이터 항목 100개가 포함됩니다. 그런 다음 *Distributed Map 상태*는 하위 워크플로 실행 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 ]
이 예시에서는 `amzn-s3-demo-bucket`이라는 Amazon S3 버킷의 `processData`라는 접두사 내에 이미지, JSON 파일 및 객체가 포함된 데이터를 구성했습니다.
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:listObjectsV2",
"Parameters": {
"Bucket": "{{amzn-s3-demo-bucket}}",
"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"
}
```
------
### `LOAD_AND_FLATTEN`에서 트랜스포밍한 Amazon S3 객체
Distributed Map의 입력 소스로 S3 ListObjectsV2에 대한 향상된 지원을 통해 상태 머신은 Amazon S3 버킷에서 여러 **데이터 객체**를 직접 읽고 처리할 수 있으므로 중첩된 맵이 메타데이터를 처리할 필요가 없습니다\!
`LOAD_AND_FLATTEN` 옵션을 사용하면 상태 머신이 다음을 수행합니다.
+ Amazon S3 `ListObjectsV2` 직접 호출에 나열된 각 객체의 **실제 콘텐츠**를 읽습니다.
+ InputType(CSV, JSON, JSONL, Parquet)을 기반으로 콘텐츠를 구문 분석합니다.
+ 메타데이터가 아닌 파일 콘텐츠(행/레코드)에서 항목을 생성합니다.
트랜스포메이션 옵션을 사용하면 메타데이터를 처리하는 데 더 이상 중첩된 Distributed Map이 필요하지 않습니다. 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 파일
*Distributed Map 상태*는 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 파일에 배열 항목 1,000개가 포함된 경우 `Map` 상태는 하위 워크플로 실행 1,000개를 시작합니다.
**참고**
하위 워크플로 실행을 시작하는 데 사용되는 실행 입력은 256KiB를 초과할 수 없습니다. 하지만 항목 크기를 줄이기 위해 선택적 `ItemSelector` 필드를 적용한 경우 Step Functions는 텍스트로 구분되는 파일, JSON 또는 JSON Lines 파일에서 항목을 최대 8MB까지 읽을 수 있습니다.
Step Functions는 Amazon S3에서 개별 파일 최대 크기로 10GB를 지원합니다.
Step Functions에는 사용하는 Amazon S3 데이터세트에 액세스할 수 있는 적절한 권한이 필요합니다. 데이터세트에 대한 IAM 정책은 [데이터세트에 대한 IAM 정책 권장 사항](#itemreader-iam-policies) 섹션을 참조하세요.
다음 탭에서는 이 데이터세트의 하위 워크플로 실행에 전달된 `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": "{{amzn-s3-demo-bucket}}",
"Key": "{{jsonDataset/factcheck.json}}"
}
}
```
------
#### [ Input to a child workflow execution ]
*Distributed Map 상태*는 JSON 파일에 있는 배열 항목 수만큼 하위 워크플로 실행을 시작합니다. 다음 예제에서는 하위 워크플로 실행에서 수신한 입력을 보여줍니다.
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
------
### Amazon S3 버킷에 있는 JSON Lines 파일
*Distributed Map 상태*는 Amazon S3 버킷에 저장된 JSON Lines 파일을 데이터세트로 허용할 수 있습니다.
**참고**
하위 워크플로 실행을 시작하는 데 사용되는 실행 입력은 256KiB를 초과할 수 없습니다. 하지만 항목 크기를 줄이기 위해 선택적 `ItemSelector` 필드를 적용한 경우 Step Functions는 텍스트로 구분되는 파일, JSON 또는 JSON Lines 파일에서 항목을 최대 8MB까지 읽을 수 있습니다.
Step Functions는 Amazon S3에서 개별 파일 최대 크기로 10GB를 지원합니다.
Step Functions에는 사용하는 Amazon S3 데이터세트에 액세스할 수 있는 적절한 권한이 필요합니다. 데이터세트에 대한 IAM 정책은 [데이터세트에 대한 IAM 정책 권장 사항](#itemreader-iam-policies) 섹션을 참조하세요.
다음 탭에서는 이 데이터세트의 하위 워크플로 실행에 전달된 `ItemReader` 필드 구문과 입력의 예제를 보여줍니다.
이 예제의 경우 `{{factcheck.jsonl}}`이라는 JSON Lines 파일이 있다고 가정해보겠습니다. 이 파일은 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 ]
*Distributed Map 상태*는 JSONL 파일에 있는 라인 수만큼 하위 워크플로 실행을 시작합니다. 다음 예제에서는 하위 워크플로 실행에서 수신한 입력을 보여줍니다.
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
------
### Amazon S3 버킷에 있는 CSV 파일
**참고**
`CSVDelimiter` 필드를 사용하면 `ItemReader`가 쉼표 이외의 문자로 구분된 파일을 처리할 수 있습니다. ‘CSV 파일’에 대한 참조에는 `CSVDelimiter` 필드에 지정된 대체 구분 기호를 사용하는 파일도 포함됩니다.
*Distributed Map 상태*는 Amazon S3 버킷에 저장된 텍스트로 구분된 파일을 데이터세트로 허용할 수 있습니다. 텍스트로 구분된 파일을 데이터세트로 사용하는 경우에는 열 헤더를 지정해야 합니다. 헤더를 지정하는 방법은 [ItemReader 필드 콘텐츠](#itemreader-field-contents) 섹션을 참조하세요.
Step Functions는 다음 규칙을 기반으로 텍스트로 구분된 파일을 구문 분석합니다.
+ 필드를 구분하는 구분 기호는 *ReaderConfig*의 `CSVDelimiter`에서 지정합니다. 구분 기호의 기본값은 `COMMA`입니다.
+ 줄 바꿈은 **레코드**를 구분하는 구분 기호입니다.
+ 필드는 문자열로 취급됩니다. 데이터 유형 변환의 경우 [ItemSelector(맵)](input-output-itemselector.md)에서 `States.StringToJson` 내장 함수를 사용합니다.
+ 문자열을 묶을 때 큰따옴표(“ ”)는 필요하지 않습니다. 그러나 큰따옴표로 묶인 문자열에는 레코드 구분 기호 역할을 하지 않는 쉼표와 줄 바꿈이 포함될 수 있습니다.
+ 큰따옴표를 반복해서 사용하여 유지할 수 있습니다.
+ 백슬래시(\\)는 특수 문자를 이스케이프하는 또 다른 방법입니다. 백슬래시는 다른 백슬래시, 큰따옴표 및 쉼표나 파이프와 같이 구성된 필드 구분자에서만 작동합니다. 다른 문자 뒤에 오는 백슬래시는 자동으로 제거됩니다.
+ 백슬래시는 반복하여 보존할 수 있습니다. 예제:
```
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` 상태는 헤더 행 다음부터 순차적으로 항목을 처리합니다.
**참고**
하위 워크플로 실행을 시작하는 데 사용되는 실행 입력은 256KiB를 초과할 수 없습니다. 하지만 항목 크기를 줄이기 위해 선택적 `ItemSelector` 필드를 적용한 경우 Step Functions는 텍스트로 구분되는 파일, JSON 또는 JSON Lines 파일에서 항목을 최대 8MB까지 읽을 수 있습니다.
Step Functions는 Amazon S3에서 개별 파일 최대 크기로 10GB를 지원합니다.
Step Functions에는 사용하는 Amazon S3 데이터세트에 액세스할 수 있는 적절한 권한이 필요합니다. 데이터세트에 대한 IAM 정책은 [데이터세트에 대한 IAM 정책 권장 사항](#itemreader-iam-policies) 섹션을 참조하세요.
다음 탭에서는 이 데이터세트의 하위 워크플로 실행에 전달된 `ItemReader` 필드 구문과 입력의 예제를 보여줍니다.
------
#### [ ItemReader syntax ]
예를 들어 라는 `{{ratings.csv}}`라는 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 ]
*Distributed Map 상태*는 헤더 행을 제외하고(파일에 있는 경우) CSV 파일에 있는 행 수만큼 하위 워크플로 실행을 시작합니다. 다음 예제에서는 하위 워크플로 실행에서 수신한 입력을 보여줍니다.
```
{
"rating": "3.5",
"movieId": "307",
"userId": "1",
"timestamp": "1256677221"
}
```
------
### Amazon S3 버킷에 있는 Parquet 파일
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 매니페스트(여러 항목 처리)
`UNLOAD` 쿼리 결과에서 생성된 Athena 매니페스트 파일을 사용하여 Map 상태에 대한 데이터 파일의 **소스**를 지정할 수 있습니다. `ManifestType`을 `ATHENA_DATA`로, `InputType`을 `CSV`, `JSONL` 또는 `Parquet`으로 설정합니다.
`UNLOAD` 쿼리를 실행할 때 Athena는 실제 데이터 객체 외에도 데이터 매니페스트 파일을 생성합니다. 매니페스트 파일은 데이터 파일의 구조화된 CSV 목록을 제공합니다. 매니페스트 및 데이터 파일은 둘 모두 Amazon S3의 Athena 쿼리 결과 위치에 저장됩니다.
```
UNLOAD () 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`도 포함됩니다.
다음은 Athena 매니페스트를 사용하도록 구성된 `ItemReader`의 구성 예제입니다.
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"ManifestType": "ATHENA_DATA",
"InputType": "CSV | JSONL | PARQUET"
},
"Arguments": {
"Bucket": "",
"Key": "-manifest.csv"
}
}
```
**Workflow Studio에서 Athena 매니페스트 패턴 사용**
데이터 처리를 위한 일반적인 시나리오는 Athena UNLOAD 쿼리에서 가져온 데이터에 맵을 적용합니다. 맵은 Lambda 함수를 간접 호출하여 Athena 매니페스트에 설명된 각 항목을 처리합니다. Step Functions Workflow Studio는 이러한 모든 구성 요소를 결합하여 상태 머신 캔버스로 드래그하는 것을 차단하는 미리 만들어진 패턴을 제공합니다.
### S3 Inventory(여러 항목 처리)
*Distributed Map 상태*는 Amazon S3 버킷에 저장된 Amazon S3 Inventory 매니페스트 파일을 데이터세트로 허용할 수 있습니다.
워크플로 실행이 `Map` 상태에 도달하면 Step Functions는 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 작업을 간접적으로 호출하여 지정된 Amazon S3 인벤토리 매니페스트 파일을 가져옵니다.
기본적으로 `Map` 상태는 인벤토리의 **객체**를 반복하여 Amazon S3 Inventory 객체 메타데이터 배열을 반환합니다.
ManifestType을 S3\_INVENTORY로 지정하면 InputType을 지정할 수 없습니다.
**참고**
Step Functions는 압축 해제 후 Amazon S3 Inventory 보고서에서 개별 파일 최대 크기로 10GB를 지원합니다. 하지만 Step Functions는 각 개별 파일이 10GB 미만이면 10GB 넘게 처리할 수 있습니다.
Step Functions에는 사용하는 Amazon S3 데이터세트에 액세스할 수 있는 적절한 권한이 필요합니다. 데이터세트에 대한 IAM 정책은 [데이터세트에 대한 IAM 정책 권장 사항](#itemreader-iam-policies) 섹션을 참조하세요.
다음은 CSV 형식의 인벤토리 파일에 대한 예제입니다. 이 파일에는 `amzn-s3-demo-source-bucket`이라는 Amazon S3 버킷에 저장되어 있는 `csvDataset` 및 `imageDataset` 객체가 포함되어 있습니다.
```
"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 Inventory 보고서의 출력 형식은 반드시 CSV여야 합니다.
Amazon S3의 인벤토리 및 설정 방법에 대한 자세한 내용은 [Amazon S3 Inventory](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-inventory.html)를 참조하세요.
다음 Amazon S3 Inventory 매니페스트 파일 예제에서는 인벤토리 객체 메타데이터의 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 Inventory 보고서를 구성하는 동안에 선택한 필드에 따라 `manifest.json` 파일 콘텐츠는 예제와 다를 수 있습니다.
------
## 데이터세트에 대한 IAM 정책 권장 사항
Step Functions 콘솔을 사용하여 워크플로를 만들면 Step Functions에서 워크플로 정의의 리소스를 기반으로 IAM 정책을 자동으로 생성할 수 있습니다. 생성된 정책에는 상태 시스템 역할이 *Distributed Map 상태에* 대한 `[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)` API 작업을 호출하고 Amazon S3 버킷 및 객체, Lambda 함수와 같은 AWS 리소스에 액세스하는 데 필요한 최소 권한이 포함됩니다.
IAM 정책에 필요한 권한만 포함시키는 것이 좋습니다. 예를 들어 워크플로에 분산 모드의 `Map` 상태가 포함된 경우 정책 범위를 데이터가 포함된 특정 Amazon S3 버킷과 폴더로 좁힙니다.
**중요**
*Distributed Map 상태* 입력에 있는 기존 키-값 페어에 대한 [참조 경로](amazon-states-language-paths.md#amazon-states-language-reference-paths)를 사용하여 Amazon S3 버킷과 객체 또는 접두사를 지정하는 경우 워크플로에 대한 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 파일을 데이터세트로 사용**
다음 예제에서는 `{{ratings.csv}}`라는 CSV 파일에 액세스하는 데 필요한 작업을 보여줍니다.
```
"Action": [ "s3:GetObject" ],
"Resource": [
"arn:aws:s3:::{{amzn-s3-demo-bucket}}/{{csvDataset}}/{{ratings.csv}}"
]
```
**Example Amazon S3 Inventory를 데이터세트로 사용**
다음은 Amazon S3 Inventory 매니페스트 및 데이터 파일에 대한 리소스의 예입니다.
```
"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)를 사용하는 경우 2개의 정책이 생성됩니다. 하나는 버킷의 콘텐츠를 **나열**(`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`는 범위가 지정되지 않으며 객체에 와일드카드(`*`)를 사용합니다.