기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Step Functions의 맵 상태 입력 및 출력 필드
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
Map 상태는 데이터세트의 항목 모음을 반복합니다. 데이터세트의 예는 다음과 같습니다.
+ 이전 상태의 JSON 배열 및 객체입니다.
+ Amazon S3에 JSON, JSONL, CSV, Parquet 파일과 같은 형식으로 저장된 개별 데이터 파일.
+ Athena 매니페스트 및 Amazon S3 Inventory 파일과 같은 여러 객체에 대한 참조
맵은 데이터세트의 각 항목에 대해 일련의 단계를 반복합니다. 다양한 구성 옵션을 사용하여 `Map state`에서 수신하는 입력과 맵이 생성하는 출력을 구성할 수 있습니다. Step Functions는 *Distributed Map 상태*의 각 옵션을 다음 목록에 표시된 순서대로 적용합니다. 사용 사례에 따라 필드를 모두 적용하지 않아도 됩니다.
1. [ItemReader(맵)](input-output-itemreader.md) - 데이터 항목을 읽는 데 사용
1. [ItemsPath(Map, JSONPath만 해당)](input-output-itemspath.md) 또는 **항목(JSONata)** - 선택 사항, 데이터세트의 항목을 지정하는 데 사용
1. [ItemSelector(맵)](input-output-itemselector.md) - 선택 사항, 데이터세트에서 항목을 선택하고 수정하는 데 사용
1. [ItemBatcher(맵)](input-output-itembatcher.md) - 대규모 항목 세트를 처리할 때 항목 그룹을 처리하는 데 사용
1. [ResultWriter(맵)](input-output-resultwriter.md) - 하위 워크플로의 출력 결과에 대한 옵션 제공
# 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\$1AND\$1FLATTEN에서 트랜스포밍한 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\$1AND\$1FLATTEN 트랜스포메이션 옵션을 선택하여 항목을 **직접** 처리할 수 있습니다.
**참고**
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 버킷에서 여러 **데이터 객체**를 직접 읽고 처리할 수 있으므로 중첩된 맵이 메타데이터를 처리할 필요가 없습니다\$1
`LOAD_AND_FLATTEN` 옵션을 사용하면 상태 머신이 다음을 수행합니다.
+ Amazon S3 `ListObjectsV2` 직접 호출에 나열된 각 객체의 **실제 콘텐츠**를 읽습니다.
+ InputType(CSV, JSON, JSONL, Parquet)을 기반으로 콘텐츠를 구문 분석합니다.
+ 메타데이터가 아닌 파일 콘텐츠(행/레코드)에서 항목을 생성합니다.
트랜스포메이션 옵션을 사용하면 메타데이터를 처리하는 데 더 이상 중첩된 Distributed Map이 필요하지 않습니다. LOAD\$1AND\$1FLATTEN 옵션을 사용하면 확장성이 향상되고 활성 맵 실행 수가 줄어들며 여러 객체를 동시에 처리합니다.
다음 예에서는 구성은 `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` 내장 함수를 사용합니다.
+ 문자열을 묶을 때 큰따옴표(“ ”)는 필요하지 않습니다. 그러나 큰따옴표로 묶인 문자열에는 레코드 구분 기호 역할을 하지 않는 쉼표와 줄 바꿈이 포함될 수 있습니다.
+ 큰따옴표를 반복해서 사용하여 유지할 수 있습니다.
+ 백슬래시(\$1)는 특수 문자를 이스케이프하는 또 다른 방법입니다. 백슬래시는 다른 백슬래시, 큰따옴표 및 쉼표나 파이프와 같이 구성된 필드 구분자에서만 작동합니다. 다른 문자 뒤에 오는 백슬래시는 자동으로 제거됩니다.
+ 백슬래시는 반복하여 보존할 수 있습니다. 예제:
```
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\$1INVENTORY로 지정하면 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`는 범위가 지정되지 않으며 객체에 와일드카드(`*`)를 사용합니다.
# ItemsPath(Map, JSONPath만 해당)
**상태 관리 및 데이터 트랜스포밍**
이 페이지에서는 JSONPath를 참조합니다. Step Functions는 최근에 상태를 관리하고 데이터를 트랜스포밍하기 위해 변수와 JSONata를 추가했습니다.
[변수를 사용하여 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
JSONPath 기반 상태에서 `ItemsPath` 필드를 사용하여 `Map` 상태에 제공된 JSON 입력 내에서 배열 또는 객체를 선택합니다. 기본적으로 `Map` 상태는 `ItemsPath`를 전체 입력을 선택하는 `$`로 설정합니다.
+ `Map` 상태에 대한 입력이 JSON 배열인 경우 배열의 각 항목에 대해 반복을 실행하여 해당 항목을 반복에 입력으로 전달합니다.
+ `Map` 상태에 대한 입력이 JSON 객체인 경우 객체의 각 키-값 페어에 대해 반복을 실행하여 해당 페어를 반복에 입력으로 전달합니다.
**참고**
워크플로의 이전 상태에서 전달된 JSON 입력을 사용하는 경우에만 *Distributed Map 상태*에서 `ItemsPath`를 사용할 수 있습니다.
의 값은 [참조 경로](amazon-states-language-paths.md#amazon-states-language-reference-paths)`ItemsPath`여야 하며 해당 경로는 JSON 배열 또는 객체로 평가되어야 합니다. 예를 들어 다음과 같은 두 개의 배열이 포함된 `Map` 상태를 가정해 보겠습니다.
```
{
"ThingsPiratesSay": [
{
"say": "Avast!"
},
{
"say": "Yar!"
},
{
"say": "Walk the Plank!"
}
],
"ThingsGiantsSay": [
{
"say": "Fee!"
},
{
"say": "Fi!"
},
{
"say": "Fo!"
},
{
"say": "Fum!"
}
]
}
```
이 경우 `ItemsPath`로 배열을 선택하여 `Map` 상태 반복에 사용할 배열을 지정할 수 있습니다. 다음 상태 머신 정의에서는 `ItemsPath`를 사용하여 입력에서 `ThingsPiratesSay` 배열을 지정합니다. 그런 다음 `ThingsPiratesSay` 배열의 항목마다 `SayWord` Pass 상태 반복을 실행합니다.
```
{
"StartAt": "PiratesSay",
"States": {
"PiratesSay": {
"Type": "Map",
"ItemsPath": "$.ThingsPiratesSay",
"ItemProcessor": {
"StartAt": "SayWord",
"States": {
"SayWord": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
중첩된 JSON 객체의 경우 `ItemsPath`를 사용하여 입력 내에서 특정 객체를 선택할 수 있습니다. 중첩된 구성 데이터가 있는 다음 입력을 고려하세요.
```
{
"environment": "production",
"servers": {
"web": {
"server1": {"port": 80, "status": "active"},
"server2": {"port": 8080, "status": "inactive"}
},
"database": {
"primary": {"host": "db1.example.com", "port": 5432},
"replica": {"host": "db2.example.com", "port": 5432}
}
}
}
```
웹 서버 객체를 반복하려면 `$.servers.web`를 `ItemsPath`로 설정합니다.
```
{
"StartAt": "ProcessWebServers",
"States": {
"ProcessWebServers": {
"Type": "Map",
"ItemsPath": "$.servers.web",
"ItemProcessor": {
"StartAt": "CheckServer",
"States": {
"CheckServer": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
입력을 처리할 때는 `Map` 상태는 [`InputPath`](input-output-inputpath-params.md#input-output-inputpath) 다음에 `ItemsPath`를 적용합니다. `InputPath`에서 입력을 필터링한 후에 상태에 유효한 입력에서 작동합니다.
`Map` 상태에 대한 자세한 내용은 다음을 참조하십시오.
+ [Map 상태](state-map.md)
+ [Map 상태 처리 모드](state-map.md#concepts-map-process-modes)
+ [Inline Map으로 작업 반복](tutorial-map-inline.md)
+ [Inline `Map` 상태 입력 및 출력 처리](state-map-inline.md#inline-map-state-output)
# ItemSelector(맵)
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
기본적으로 `Map` 상태의 유효 입력은 원시 상태 입력에 있는 개별 데이터 항목 집합입니다. 이 `ItemSelector` 필드를 사용하면 데이터 항목 값이 `Map` 상태로 전달되기 전에 이 값을 재정의할 수 있습니다.
값을 재정의하려면 키-값 페어 컬렉션이 포함된 유효한 JSON 입력을 지정합니다. 이 페어는 상태 머신 정의에 제공된 정적 값, [경로](amazon-states-language-paths.md)를 사용하여 상태 입력에서 선택한 값 또는 [컨텍스트 객체](input-output-contextobject.md)에서 액세스한 값일 수 있습니다.
경로나 컨텍스트 객체를 사용하여 키-값 페어를 지정하는 경우 키 이름은 `.$`로 끝나야 합니다.
**참고**
`ItemSelector` 필드는 `Map` 상태 내에서 `Parameters` 필드를 대체합니다. `Map` 상태 정의의 `Parameters` 필드를 사용하여 사용자 지정 입력을 만드는 경우 `ItemSelector`로 바꾸는 것이 좋습니다.
*Inline Map 상태*와 *Distributed Map 상태* 모두에서 `ItemSelector` 필드를 지정할 수 있습니다.
예를 들어 `imageData` 노드 내에 항목 3개로 구성된 배열을 포함하는 다음 JSON 입력을 고려해보세요. *`Map` 상태 반복*마다 배열 항목이 입력으로 반복에 전달됩니다.
```
[
{
"resize": "true",
"format": "jpg"
},
{
"resize": "false",
"format": "png"
},
{
"resize": "true",
"format": "jpg"
}
]
```
다음 예제와 같이 `ItemSelector` 필드를 사용하여 사용자 지정 JSON 입력을 정의하여 원래 입력을 재정의할 수 있습니다. 그러면 Step Functions에서 이 사용자 지정 입력을 각 *`Map` 상태 반복*에 전달합니다. 사용자 지정 입력에는 `size` 정적 값과 `Map` 상태에 대한 컨텍스트 객체 데이터 값이 포함됩니다. `$$.Map.Item.Value` 컨텍스트 객체에는 각 개별 데이터 항목 값이 포함됩니다.
```
{
"ItemSelector": {
"size": 10,
"value.$": "$$.Map.Item.Value"
}
}
```
다음 예제에서는 *Inline Map 상태*를 한 번 반복하면 수신되는 입력을 보여줍니다.
```
{
"size": 10,
"value": {
"resize": "true",
"format": "jpg"
}
}
```
**작은 정보**
`ItemSelector` 필드를 사용하는 *Distributed Map 상태*의 전체 예제는 [Distributed Map을 사용하여 대규모 CSV 복사](tutorial-map-distributed.md) 섹션을 참조하세요.
# ItemBatcher(맵)
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
`ItemBatcher` 필드는 단일 하위 워크플로 실행에서 항목 그룹을 처리하도록 지정하는 JSON 개체입니다. 대용량 CSV 파일이나 JSON 배열 또는 대규모 Amazon S3 객체 집합을 처리할 때 일괄 처리를 사용합니다.
다음 예제에서는 `ItemBatcher` 필드 구문을 보여줍니다. 다음 구문에서 각 하위 워크플로 실행에서 처리해야 하는 최대 항목 수는 100으로 설정됩니다.
```
{
"ItemBatcher": {
"MaxItemsPerBatch": 100
}
}
```
기본적으로 데이터세트의 각 항목은 입력으로 개별 하위 워크플로 실행에 전달됩니다. 예를 들어 다음 배열이 포함된 JSON 파일을 입력으로 지정한다고 가정해보겠습니다.
```
[
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
{
"verdict": "true",
"statement_date": "5/18/2016",
"statement_source": "news"
},
...
]
```
지정된 입력의 경우 각 하위 워크플로 실행은 배열 항목을 입력으로 수신합니다. 다음은 하위 워크플로 실행 입력을 보여주는 예제입니다.
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
처리 작업의 성능과 비용을 최적화하려면 항목 수와 항목 처리 시간의 균형을 맞추는 배치 크기를 선택합니다. 일괄 처리를 사용하면 Step Functions에서 항목을 **항목** 배열에 추가합니다. 그런 다음 배열을 입력으로 각 하위 워크플로 실행에 전달합니다. 다음은 하위 워크플로 실행에 입력으로 전달된 두 항목의 배치를 보여주는 예제입니다.
```
{
"Items": [
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
}
]
}
```
**작은 정보**
워크플로에서 `ItemBatcher` 필드를 사용하는 방법에 대해 자세히 알아보려면 다음 자습서와 워크숍을 사용해보세요.
[Lambda 함수 내에서 전체 데이터 배치 처리](tutorial-itembatcher-param-task.md)
[하위 워크플로 실행 내에서 일괄적으로 항목 반복](tutorial-itembatcher-single-item-process.md)
*AWS Step Functions 워크숍*의 [Distributed Map 및 관련 리소스](https://catalog.workshops.aws/stepfunctions/use-cases/distributed-map)
**Contents**
+ [항목 일괄 처리를 지정하는 필드](#input-output-itembatcher-subfields)
## 항목 일괄 처리를 지정하는 필드
항목을 일괄 처리하려면 일괄 처리할 최대 항목 수, 최대 배치 크기 또는 둘 다를 지정합니다. 항목을 일괄 처리하려면 다음 값 중 하나를 지정해야 합니다.
**배치당 최대 항목 수**
각 하위 워크플로 실행에서 처리하는 최대 항목 수를 지정합니다. 인터프리터는 `Items` 배열에서 일괄 처리되는 항목 수를 이 값으로 제한합니다. 배치 번호와 크기 모두 지정하면 인터프리터는 지정된 배치 크기 한도가 초과되지 않도록 배치의 항목 수를 줄입니다.
이 값을 지정하지 않고 최대 배치 크기 값을 제공하면 Step Functions는 최대 배치 크기(바이트 단위)를 초과하지 않고 각 하위 워크플로 실행에서 최대한 많은 항목을 처리합니다.
예를 들어 노드 1130개가 포함된 입력 JSON 파일을 사용하여 실행을 실행한다고 가정해보겠습니다. 각 배치의 최대 항목 값을 100으로 지정하면 Step Functions에서 배치 12개를 만듭니다. 이 중 배치 11개 각각에는 항목 100개가 포함되고 12번째 배치에는 잔여 항목 30개가 포함됩니다.
또는 *Distributed Map 상태* 입력의 기존 키-값 페어에 대한 [참조 경로](amazon-states-language-paths.md#amazon-states-language-reference-paths)로 각 배치의 최대 항목 수를 지정할 수 있습니다. 이 경로는 양의 정수로 확인되어야 합니다.
다음 입력을 예로 들어보겠습니다.
```
{
"maxBatchItems": 500
}
```
다음과 같이 참조 경로(**JSONPath만 해당**)를 사용하여 일괄 처리할 최대 항목 수를 지정할 수 있습니다.
```
{
...
"Map": {
"Type": "Map",
"MaxConcurrency": 2000,
"ItemBatcher": {
"MaxItemsPerBatchPath": "$.maxBatchItems"
}
...
...
}
}
```
**JSONata 기반** 상태의 경우 양의 정수로 평가되는 JSONata 표현식을 제공할 수도 있습니다.
`MaxItemsPerBatch` 또는 `MaxItemsPerBatchPath (JSONPath only)` 하위 필드를 지정할 수 있지만 둘 다 함께 지정할 수는 없습니다.
**일괄 처리당 최대 KiB**
최대 일괄 처리 크기(바이트 단위)를 최대 256KiB까지 지정합니다. 최대 배치 수와 크기 모두 지정하면 Step Functions는 지정된 배치 크기 한도가 초과되지 않도록 배치의 항목 수를 줄입니다.
또는 *Distributed Map 상태* 입력의 기존 키-값 페어에 대한 [참조 경로](amazon-states-language-paths.md#amazon-states-language-reference-paths)로 최대 배치 크기를 지정할 수 있습니다. 이 경로는 양의 정수로 확인되어야 합니다.
일괄 처리를 사용하지만 최대 배치 크기를 지정하지 않으면 인터프리터는 각 하위 워크플로 실행에서 최대 256KiB까지 처리할 수 있는 항목 수를 모두 처리합니다.
다음 입력을 예로 들어보겠습니다.
```
{
"batchSize": 131072
}
```
다음과 같이 참조 경로를 사용하여 최대 배치 크기를 지정할 수 있습니다.
```
{
...
"Map": {
"Type": "Map",
"MaxConcurrency": 2000,
"ItemBatcher": {
"MaxInputBytesPerBatchPath": "$.batchSize"
}
...
...
}
}
```
**JSONata 기반** 상태의 경우 양의 정수로 평가되는 JSONata 표현식을 제공할 수도 있습니다.
`MaxInputBytesPerBatch` 또는 `MaxInputBytesPerBatchPath`(JSONPath만 해당) 하위 필드를 지정할 수 있지만 둘 다 함께 지정할 수는 없습니다.
**배치 입력**
필요한 경우 각 하위 워크플로 실행에 전달되는 각 배치에 포함할 고정 JSON 입력을 지정할 수도 있습니다. Step Functions는 이 입력을 각 개별 하위 워크플로 실행의 입력과 병합합니다. 항목 배열의 사실 확인 날짜 고정 입력을 예로 들어 보겠습니다.
```
"ItemBatcher": {
"BatchInput": {
"factCheck": "December 2022"
}
}
```
각 하위 워크플로 실행에서 입력으로 다음을 수신합니다.
```
{
"BatchInput": {
"factCheck": "December 2022"
},
"Items": [
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
...
]
}
```
**JSONata 기반** 상태의 경우 JSONata 표현식을 BatchInput에 직접 제공하거나 JSON 객체 또는 배열 내에서 JSONata 표현식을 사용할 수 있습니다.
# ResultWriter(맵)
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
`ResultWriter` 필드는 Distributed Map 상태로 시작된 하위 워크플로 실행의 출력 결과에 대한 옵션을 제공하는 JSON 객체입니다. 출력 결과를 내보내도록 선택한 경우 저장할 Amazon S3 위치와 함께 출력 결과에 대해 다양한 형식 지정 옵션을 지정할 수 있습니다. Step Functions는 이러한 결과를 기본적으로 내보내지 않습니다.
**Topics**
+ [ResultWriter 필드의 내용](#input-output-resultwriter-field-contents)
+ [예제](#input-output-resultwriter-examples)
+ [Amazon S3로 내보내기](#input-output-resultwriter-exporting-to-S3)
+ [ResultWriter에 대한 IAM 정책](#resultwriter-iam-policies)
## ResultWriter 필드의 내용
`ResultWriter` 필드에는 다음과 같은 하위 필드가 포함되어 있습니다. 필드 선택에 따라 출력 형식 지정 방법과 Amazon S3로 내보낼지 여부가 결정됩니다.
**`ResultWriter`**
다음 세부 정보를 지정하는 JSON 객체:
+ `Resource`
Step Functions가 실행 결과를 내보내기 위해 간접 호출하는 Amazon S3 API 작업입니다.
+ `Parameters`
실행 출력을 저장하는 Amazon S3 버킷 이름과 접두사를 지정하는 JSON 객체입니다.
+ `WriterConfig`
이 필드를 사용하면 다음 옵션을 구성할 수 있습니다.
+ `Transformation`
+ `NONE` - 워크플로 메타데이터 외에 하위 워크플로 실행의 출력을 변경하지 않고 반환합니다. 하위 워크플로 실행 결과를 내보낼 때 Amazon S3 및 `WriterConfig`는 지정되지 않습니다.
+ `COMPACT` - 하위 워크플로 실행의 출력을 반환합니다. `ResultWriter`가 지정되지 않은 경우 기본값입니다.
+ `FLATTEN` - 하위 워크플로 실행의 출력을 반환합니다. 하위 워크플로 실행이 배열을 반환하는 경우 이 옵션은 결과를 상태 출력으로 반환하거나 Amazon S3 객체에 결과를 쓰기 전에 배열을 평면화합니다.
**참고**
하위 워크플로 실행이 실패하면 Step Functions는 실행 결과를 변경 없이 반환합니다. 결과는 `Transformation`을 `NONE`으로 설정한 것과 같습니다.
+ `OutputType`
+ `JSON` - 결과를 JSON 배열 형식으로 지정합니다.
+ `JSONL` - 결과를 JSON Lines 형식으로 지정합니다.
**필수 필드 조합**
`ResultWriter` 필드는 비워둘 수 없습니다. 이러한 하위 필드 세트 중 하나를 지정해야 합니다.
+ `WriterConfig` - 결과를 Amazon S3에 저장하지 않고 형식이 지정된 출력을 미리 봅니다.
+ `Resource` 및 `Parameters` - 추가 형식 지정 없이 결과를 Amazon S3에 저장합니다.
+ 출력 형식을 지정하고 Amazon S3에 저장하려면 `WriterConfig`, `Resource` 및 `Parameters`의 세 필드를 모두 입력합니다.
## 예제 구성 및 트랜스포메이션 출력
다음 주제에서는 `ResultWriter`에 대해 가능한 구성 설정과 다양한 트랜스포메이션 옵션에서 처리된 결과의 예를 보여줍니다.
+ [ResultWriter 구성](#input-output-resultwriter-example-configurations)
+ [변환](#input-output-resultwriter-example-transformations)
### ResultWriter 구성의 예
다음 예제에서는 3개 필드인 `WriterConfig`, `Resources` 및 `Parameters`의 가능한 조합이 있는 구성을 보여줍니다.
***WriterConfig*만**
이 예제에서는 `WriterConfig` 필드에 지정된 출력 형식 및 트랜스포메이션을 사용하여 상태 출력이 미리 보기에 표시되는 방법을 구성합니다. Amazon S3 버킷 사양을 제공했을 존재하지 않는 `Resource` 및 `Parameters` 필드는 *상태 출력* 리소스를 의미합니다. 결과는 다음 상태로 전달됩니다.
```
"ResultWriter": {
"WriterConfig": {
"Transformation": "FLATTEN",
"OutputType": "JSON"
}
}
```
***Resources* 및 *Parameters*만**
이 예제에서는 존재하지 않는 `WriterConfig` 필드가 지정했을 추가 형식 지정 및 트랜스포메이션 없이 상태 출력을 지정된 Amazon S3 버킷으로 내보냅니다.
```
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
```
**3개 필드 모두: *WriterConfig*, *Resources* 및 *Parameters***
이 예제에서는 `WriterConfig` 필드의 사양에 따라 상태 출력의 형식을 지정합니다. 또한 `Resource` 및 `Parameters` 필드의 사양에 따라 Amazon S3 버킷으로 내보냅니다.
```
"ResultWriter": {
"WriterConfig": {
"Transformation": "FLATTEN",
"OutputType": "JSON"
},
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
```
### 트랜스포메이션의 예
이 예제에서는 각 하위 워크플로 실행이 객체 배열인 출력을 반환한다고 가정합니다.
```
[
{
"customer_id": "145538",
"order_id": "100000"
},
{
"customer_id": "898037",
"order_id": "100001"
}
]
```
이 예제에서는 `JSON`의 `OutputType`을 사용하여 다양한 `Transformation` 값에 대한 형식이 지정된 출력을 보여줍니다.
**트랜스포메이션 없음**
`NONE` 트랜스포메이션을 사용할 때 처리된 결과의 예입니다. 출력은 변경되지 않으며 워크플로 메타데이터가 포함됩니다.
```
[
{
"ExecutionArn": "arn:aws:states:region:account-id:execution:orderProcessing/getOrders:da4e9fc7-abab-3b27-9a77-a277e463b709",
"Input": ...,
"InputDetails": {
"Included": true
},
"Name": "da4e9fc7-abab-3b27-9a77-a277e463b709",
"Output": "[{\"customer_id\":\"145538\",\"order_id\":\"100000\"},{\"customer_id\":\"898037\",\"order_id\":\"100001\"}]",
"OutputDetails": {
"Included": true
},
"RedriveCount": 0,
"RedriveStatus": "NOT_REDRIVABLE",
"RedriveStatusReason": "Execution is SUCCEEDED and cannot be redriven",
"StartDate": "2025-02-04T01:49:50.099Z",
"StateMachineArn": "arn:aws:states:region:account-id:stateMachine:orderProcessing/getOrders",
"Status": "SUCCEEDED",
"StopDate": "2025-02-04T01:49:50.163Z"
},
...
{
"ExecutionArn": "arn:aws:states:region:account-id:execution:orderProcessing/getOrders:f43a56f7-d21e-3fe9-a40c-9b9b8d0adf5a",
"Input": ...,
"InputDetails": {
"Included": true
},
"Name": "f43a56f7-d21e-3fe9-a40c-9b9b8d0adf5a",
"Output": "[{\"customer_id\":\"169881\",\"order_id\":\"100005\"},{\"customer_id\":\"797471\",\"order_id\":\"100006\"}]",
"OutputDetails": {
"Included": true
},
"RedriveCount": 0,
"RedriveStatus": "NOT_REDRIVABLE",
"RedriveStatusReason": "Execution is SUCCEEDED and cannot be redriven",
"StartDate": "2025-02-04T01:49:50.135Z",
"StateMachineArn": "arn:aws:states:region:account-id:stateMachine:orderProcessing/getOrders",
"Status": "SUCCEEDED",
"StopDate": "2025-02-04T01:49:50.227Z"
}
]
```
**트랜스포메이션 COMPACT**
`COMPACT` 트랜스포메이션을 사용할 때 처리된 결과의 예입니다. 이는 원본 배열 구조와 하위 워크플로 실행의 결합된 출력입니다.
```
[
[
{
"customer_id": "145538",
"order_id": "100000"
},
{
"customer_id": "898037",
"order_id": "100001"
}
],
...,
[
{
"customer_id": "169881",
"order_id": "100005"
},
{
"customer_id": "797471",
"order_id": "100006"
}
]
]
```
**트랜스포메이션 FLATTEN**
`FLATTEN` 트랜스포메이션을 사용할 때 처리된 결과의 예입니다. 하위 워크플로 실행 배열의 결합된 출력이 하나의 배열로 평면화됩니다.
```
[
{
"customer_id": "145538",
"order_id": "100000"
},
{
"customer_id": "898037",
"order_id": "100001"
},
...
{
"customer_id": "169881",
"order_id": "100005"
},
{
"customer_id": "797471",
"order_id": "100006"
}
]
```
## Amazon S3로 내보내기
**중요**
맵 실행의 결과를 내보내는 데 사용하는 Amazon S3 버킷이 AWS 리전상태 시스템과 동일한 AWS 계정및 아래에 있는지 확인합니다. 그렇지 않으면 상태 머신 실행이 실패하고 `States.ResultWriterFailed` 오류가 표시됩니다.
출력 페이로드 크기가 256KiB를 초과하는 경우 Amazon S3 버킷에 결과를 내보내는 것이 도움이 됩니다. Step Functions는 실행 입력 및 출력, ARN, 실행 상태와 같은 모든 하위 워크플로 실행 데이터를 통합합니다. 그런 다음 같은 상태의 실행을 지정된 Amazon S3 위치에 있는 각 파일로 내보냅니다.
다음 예제에서는 **JSONPath**를 사용하여 하위 워크플로 실행 결과를 내보내는 경우 `Parameters`의 `ResultWriter` 필드 구문을 보여줍니다. 이 예제에서는 `csvProcessJobs` 접두사 내 `amzn-s3-demo-destination-bucket`이라는 버킷에 결과를 저장합니다.
```
{
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
}
```
**JSONata** 상태의 경우 `Parameters`가 `Arguments`로 대체됩니다.
```
{
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Arguments": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
}
```
**작은 정보**
Workflow Studio에서 **Amazon S3로 Map 상태 결과 내보내기**를 선택하여 하위 워크플로 실행 결과를 내보낼 수 있습니다. 그런 다음 결과를 내보내려는 Amazon S3 버킷의 이름과 접두사를 입력합니다.
Step Functions에는 결과를 내보내려는 버킷과 폴더에 액세스할 수 있는 적절한 권한이 필요합니다. 필요한 IAM 정책에 대한 자세한 내용은 [ResultWriter에 대한 IAM 정책](#resultwriter-iam-policies) 섹션을 참조하세요.
하위 워크플로 실행 결과를 내보내면 *Distributed Map 상태* 실행에서 맵 실행 ARN과 Amazon S3 내보내기 위치에 대한 데이터를 다음 형식으로 반환합니다.
```
{
"MapRunArn": "arn:aws:states:us-east-2:account-id:mapRun:csvProcess/Map:ad9b5f27-090b-3ac6-9beb-243cd77144a7",
"ResultWriterDetails": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Key": "csvProcessJobs/ad9b5f27-090b-3ac6-9beb-243cd77144a7/manifest.json"
}
}
```
Step Functions는 동일한 상태의 실행을 해당 파일로 각각 내보냅니다. 예를 들어 하위 워크플로 실행 실행에서 성공이 500개, 실패가 200개인 경우 Step Functions는 지정된 Amazon S3 위치에 성공 및 실패 결과에 대한 파일 2개를 만듭니다. 이 예제에서 성공 결과 파일에는 성공 결과 500개가 포함되고 실패 결과 파일에는 실패 결과 200개가 포함됩니다.
지정된 실행 시도의 경우 Step Functions는 실행 출력에 따라 지정된 Amazon S3 위치에 다음 파일을 만듭니다.
+ `manifest.json` - 내보내기 위치, 맵 실행 ARN, 결과 파일에 대한 정보와 같은 맵 실행 메타데이터를 포함합니다.
맵 실행을 [redriven](redrive-map-run.md)한 경우 `manifest.json` 파일에는 맵 실행의 모든 시도에서 성공한 모든 하위 워크플로 실행에 대한 참조가 포함됩니다. 하지만 이 파일에는 특정 redrive의 실패 및 보류 중인 실행에 대한 참조가 포함됩니다.
+ `SUCCEEDED_n.json` - 모든 성공적인 하위 워크플로 실행에 대한 통합 데이터를 포함합니다. *n*은 파일의 인덱스 번호를 나타냅니다. 인덱스 번호는 0부터 시작합니다. 예를 들어 `SUCCEEDED_1.json`입니다.
+ `FAILED_n.json` - 모든 실패, 제한 시간 및 중단된 하위 워크플로 실행에 대한 통합 데이터를 포함합니다. 실패한 실행을 복구하려면 이 파일을 사용합니다. *n*은 파일 인덱스를 나타냅니다. 인덱스 번호는 0부터 시작합니다. 예를 들어 `FAILED_1.json`입니다.
+ `PENDING_n.json` - 맵 실행이 실패하거나 중단되어 시작되지 않은 모든 하위 워크플로 실행에 대한 통합 데이터를 포함합니다. *n*은 파일 인덱스를 나타냅니다. 인덱스 번호는 0부터 시작합니다. 예를 들어 `PENDING_1.json`입니다.
Step Functions는 개별 결과 파일을 최대 5GB까지 지원합니다. 파일 크기가 5GB를 초과하면 Step Functions에서 나머지 실행 결과를 기록할 다른 파일을 만들고 파일 이름에 인덱스 번호를 추가합니다. 예를 들어 `SUCCEEDED_0.json` 파일 크기가 5GB를 초과하면 Step Functions에서 `SUCCEEDED_1.json` 파일을 만들어 나머지 결과를 기록합니다.
하위 워크플로 실행 결과를 내보내도록 지정하지 않은 경우 상태 머신 실행은 다음 예제와 같이 하위 워크플로 실행 결과 배열을 반환합니다.
```
[
{
"statusCode": 200,
"inputReceived": {
"show_id": "s1",
"release_year": "2020",
"rating": "PG-13",
"type": "Movie"
}
},
{
"statusCode": 200,
"inputReceived": {
"show_id": "s2",
"release_year": "2021",
"rating": "TV-MA",
"type": "TV Show"
}
},
...
]
```
**참고**
반환된 출력 크기가 256KiB를 초과하면 상태 머신 실행이 실패하고 `States.DataLimitExceeded` 오류가 반환됩니다.
## ResultWriter에 대한 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 정책을 업데이트해야 합니다. 정책 범위를 런타임 시 경로에서 확인하는 버킷과 객체 이름으로 좁히세요.
다음 IAM 정책 예제에서는 `[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)` API 작업을 사용하여 하위 워크플로 실행 결과를 Amazon S3 버킷의 *csvJobs* 폴더에 쓰는 데 필요한 최소 권한을 부여합니다.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListMultipartUploadParts",
"s3:AbortMultipartUpload"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-destination-bucket/csvJobs/*"
]
}
]
}
```
하위 워크플로 실행 결과를 작성하는 Amazon S3 버킷이 AWS Key Management Service (AWS KMS) 키를 사용하여 암호화된 경우 IAM 정책에 필요한 AWS KMS권한을 포함해야 합니다. 자세한 내용은 [AWS KMS key 암호화된 Amazon S3 버킷에 대한 IAM 권한](iam-policies-eg-dist-map.md#multiupload-dmap-result-policy) 단원을 참조하십시오.
# Step Functions가 입력 CSV 파일을 구문 분석하는 방법
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
Step Functions는 다음 규칙을 기반으로 텍스트로 구분된 파일을 구문 분석합니다.
+ 필드를 구분하는 구분 기호는 *ReaderConfig*의 `CSVDelimiter`에서 지정합니다. 구분 기호의 기본값은 `COMMA`입니다.
+ 줄 바꿈은 **레코드**를 구분하는 구분 기호입니다.
+ 필드는 문자열로 취급됩니다. 데이터 유형 변환의 경우 [ItemSelector(맵)](input-output-itemselector.md)에서 `States.StringToJson` 내장 함수를 사용합니다.
+ 문자열을 묶을 때 큰따옴표(“ ”)는 필요하지 않습니다. 그러나 큰따옴표로 묶인 문자열에는 레코드 구분 기호 역할을 하지 않는 쉼표와 줄 바꿈이 포함될 수 있습니다.
+ 큰따옴표를 반복해서 사용하여 유지할 수 있습니다.
+ 백슬래시(\$1)는 특수 문자를 이스케이프하는 또 다른 방법입니다. 백슬래시는 다른 백슬래시, 큰따옴표 및 쉼표나 파이프와 같이 구성된 필드 구분자에서만 작동합니다. 다른 문자 뒤에 오는 백슬래시는 자동으로 제거됩니다.
+ 백슬래시는 반복하여 보존할 수 있습니다. 예제:
```
path,size
C:\\Program Files\\MyApp.exe,6534512
```
+ 큰따옴표(`\"`)를 이스케이프하는 백슬래시는 쌍에 포함된 경우에만 작동하므로 큰따옴표를 반복하여(`""`) 이스케이프하는 것이 좋습니다.
+ 행의 필드 수가 헤더의 필드 수보다 **적으면** Step Functions에서 누락된 값에 **빈 문자열**을 제공합니다.
+ 행의 필드 수가 헤더의 필드 수보다 **많으면** Step Functions는 추가 필드를 **건너뜁니다**.
**입력 CSV 파일 구문 분석 예시**
행 하나를 입력으로 포함하는 `myCSVInput.csv`라는 CSV 파일을 제공했다고 가정해보겠습니다. 그런 다음 `amzn-s3-demo-bucket`이라는 Amazon S3 버킷에 이 파일을 저장했습니다. CSV 파일은 다음과 같습니다.
```
abc,123,"This string contains commas, a double quotation marks (""), and a newline (
)",{""MyKey"":""MyValue""},"[1,2,3]"
```
다음 상태 머신에서 이 CSV 파일을 읽고 [ItemSelector(맵)](input-output-itemselector.md)를 사용하여 일부 필드의 데이터 유형을 변환합니다.
```
{
"StartAt": "Map",
"States": {
"Map": {
"Type": "Map",
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "DISTRIBUTED",
"ExecutionType": "STANDARD"
},
"StartAt": "Pass",
"States": {
"Pass": {
"Type": "Pass",
"End": true
}
}
},
"End": true,
"Label": "Map",
"MaxConcurrency": 1000,
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "GIVEN",
"CSVHeaders": [
"MyLetters",
"MyNumbers",
"MyString",
"MyObject",
"MyArray"
]
},
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "myCSVInput.csv"
}
},
"ItemSelector": {
"MyLetters.$": "$$.Map.Item.Value.MyLetters",
"MyNumbers.$": "States.StringToJson($$.Map.Item.Value.MyNumbers)",
"MyString.$": "$$.Map.Item.Value.MyString",
"MyObject.$": "States.StringToJson($$.Map.Item.Value.MyObject)",
"MyArray.$": "States.StringToJson($$.Map.Item.Value.MyArray)"
}
}
}
}
```
이 상태 머신을 실행하면 다음 출력이 생성됩니다.
```
[
{
"MyNumbers": 123,
"MyObject": {
"MyKey": "MyValue"
},
"MyString": "This string contains commas, a double quote (\"), and a newline (\n)",
"MyLetters": "abc",
"MyArray": [
1,
2,
3
]
}
]
```