기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Step Functions에서 입력 및 출력 처리
**변수 및 JSONata를 사용하여 상태 관리**
Step Functions는 최근에 상태를 관리하고 데이터를 트랜스포밍하기 위해 변수와 JSONata를 추가했습니다.
블로그 게시물 [의 변수 및 JSONata로 개발자 경험 간소화에서AWS Step Functions](https://aws.amazon.com/blogs/compute/simplifying-developer-experience-with-variables-and-jsonata-in-aws-step-functions/) 자세히 알아보기
Step Functions 실행에서 JSON 텍스트를 입력으로 수신할 때 해당 데이터를 워크플로의 첫 번째 상태에 입력으로 전달합니다.
JSONata를 사용하면 `$states.input`에서 상태 입력을 검색할 수 있습니다. 상태 머신 실행은 [컨텍스트 객체](input-output-contextobject.md)에서 초기 입력 데이터도 제공합니다. `$states.context.Execution.Input`에서 워크플로의 어떤 지점에서든 원래 상태 머신 입력을 검색할 수 있습니다.
상태가 종료되면 상태 머신의 *바로* 다음 상태로 출력을 사용할 수 있습니다. 상태 출력을 **수정**하지 않는 한 상태 입력은 기본적으로 상태 출력으로 전달됩니다. 이후 단계에서 필요할 수 있는 데이터의 경우 변수에 저장하는 것이 좋습니다. 자세한 내용은 [변수를 사용하여 상태 간에 데이터 전달](workflow-variables.md) 섹션을 참조하세요.
**QueryLanguage 권장 사항**
새 상태 머신의 경우 JSONata 쿼리 언어를 사용하는 것이 좋습니다. 쿼리 언어를 지정하지 않는 상태 머신에서 상태 머신은 역호환성을 위해 기본적으로 JSONPath로 설정됩니다. 상태 머신 또는 개별 상태에 JSONata를 사용하려면 옵트인해야 합니다.
**JSONata를 사용하여 입력 및 출력 처리**
JSONata 표현식을 사용하면 데이터를 선택하고 트랜스포밍할 수 있습니다. `Arguments` 필드에서 작업에 전송된 데이터를 사용자 지정할 수 있습니다. 결과는 `Output` 필드에서 사용자 지정 상태 출력으로 트랜스포밍할 수 있습니다. `Assign` 필드의 변수에 데이터를 저장할 수도 있습니다. 자세한 내용은 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md) 섹션을 참조하세요.
다음 다이어그램은 JSON 정보가 JSONata 태스크 상태를 통과하는 방법을 보여줍니다.
![\[Diagram showing JSONata task state flow with input, arguments, output, and action components.\]](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/vars-jsonata.png)
**JSONPath를 사용하여 입력 및 출력 처리**
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
JSONPath를 사용하는 상태 머신의 경우 `InputPath`, `Parameters`, `ResultSelector`, `ResultPath` 및 `OutputPath` 필드는 상태에서 상태로의 데이터 흐름을 제어합니다. 각 JSONPath 필드는 워크플로의 각 상태를 이동할 때 JSON을 조작합니다.
JSONPath 필드는 [경로](amazon-states-language-paths.md)를 사용하여 입력 또는 결과에서 JSON 부분을 선택할 수 있습니다. 경로는 JSON 텍스트 내의 노드를 식별하는 `$`로 시작하는 문자열입니다. Step Functions 경로는 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) 구문을 사용합니다.
다음 다이어그램은 JSON 정보가 JSONPath 태스크 상태를 통과하는 방법을 보여줍니다. 는 JSON 입력의 일부를 `InputPath` 선택하여 `Task` 상태의 작업(예: AWS Lambda함수)에 전달합니다. `Parameters` 필드에서 작업에 전송되는 데이터를 조정할 수 있습니다. 그런 다음 `ResultSelector`를 사용하면 이월할 작업 결과의 일부를 선택할 수 있습니다. 그런 다음 `ResultPath`는 출력에 전달할 상태 입력 및 작업 결과의 조합을 선택합니다. `OutputPath`는 JSON 출력을 필터링하여 출력에 전달되는 정보를 추가로 제한할 수 있습니다.
![\[필터 순서: InputPath, Parameters, ResultSelector, ResultPath, OutputPath.\]](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/vars-jsonpath.png)
**Topics**
+ [
# 변수를 사용하여 상태 간에 데이터 전달
](workflow-variables.md)
+ [
# Step Functions에서 JSONata로 데이터 트랜스포밍
](transforming-data.md)
+ [
# Step Functions의 컨텍스트 객체에서 실행 데이터 액세스
](input-output-contextobject.md)
+ [
# JSONPath 경로 사용
](amazon-states-language-paths.md)
+ [
# Step Functions 워크플로의 파라미터를 사용하여 파라미터 조작
](input-output-inputpath-params.md)
+ [
# 예: Step Functions 워크플로에서 경로를 통해 상태 데이터 조작
](input-output-example.md)
+ [
# Step Functions에서 ResultPath를 사용하여 상태 출력 지정
](input-output-resultpath.md)
+ [
# Step Functions의 맵 상태 입력 및 출력 필드
](input-output-fields-dist-map.md)
# 변수를 사용하여 상태 간에 데이터 전달
**변수 및 JSONata를 사용하여 상태 관리**
Step Functions는 최근에 상태를 관리하고 데이터를 트랜스포밍하기 위해 변수와 JSONata를 추가했습니다.
블로그 게시물 [AWS Step Functions의 변수 및 JSONata로 개발자 경험 간소화](https://aws.amazon.com/blogs/compute/simplifying-developer-experience-with-variables-and-jsonata-in-aws-step-functions/)에서 자세히 알아보기
다음 동영상에서는 DynamoDB 예를 사용하여 Step Functions의 변수 및 JSONata를 설명합니다.
변수 및 상태 출력을 사용하면 워크플로의 단계 간에 데이터를 전달할 수 있습니다.
워크플로 변수를 사용하면 단계에서 데이터를 저장하고 향후 단계에서 해당 데이터를 검색할 수 있습니다. 예를 들어 나중에 필요할 수 있는 데이터가 포함된 API 응답을 저장할 수 있습니다. 반대로 상태 출력은 다음 단계의 입력으로만 사용할 수 있습니다.
## 변수의 개념적 개요
워크플로 변수를 사용하면 나중에 참조할 데이터를 저장할 수 있습니다. 예를 들어 1단계는 API 요청의 결과를 저장하여 5단계의 뒷부분에서 해당 요청의 일부를 재사용할 수 있습니다.
다음 시나리오에서는 상태 머신이 API에서 데이터를 1번 가져옵니다. 1단계에서 워크플로는 반환된 API 데이터(상태당 최대 256KiB)를 변수 'x'에 저장하여 이후 단계에서 사용합니다.
변수가 없으면 5단계에서 사용하려면 1단계에서 2단계, 3단계, 4단계의 출력을 통해 데이터를 전달해야 합니다. 이러한 중간 단계에 데이터가 필요하지 않으면 어떻게 해야 하나요? 출력 및 입력을 통해 상태에서 상태로 데이터를 전달하는 것은 불필요한 작업입니다.
변수를 사용하면 데이터를 저장하고 향후 단계에서 사용할 수 있습니다. 데이터 흐름을 방해하지 않고 단계를 수정, 재배열 또는 추가할 수도 있습니다. 변수의 유연성을 고려할 때 Parallel 및 Map 하위 워크플로와 상태 머신 실행이 끝날 때 데이터를 반환하는 데만 **Output**을 사용해야 할 수 있습니다.
![\[Diagram showing step 1 assigning a value to $x, used in step 5.\]](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/vars-diag-opt1.png)
**변수를 지원하는 상태 **
*Pass, Task, Map, Parallel, Choice, Wait* 상태 유형은 `Assign`이 변수를 선언하고 값을 할당하도록 지원합니다.
변수를 설정하려면 변수 이름과 값이 포함된 JSON 객체를 제공합니다.
```
"Assign": {
"productName": "product1",
"count" : 42,
"available" : true
}
```
변수를 참조하려면 이름 앞에 달러 기호(`$`)를 추가합니다. 예: `$productName`.
## 예약 변수: \$1states
Step Functions는 **`$states`**라는 단일 예약 변수를 정의합니다. JSONata 상태에서는 JSONata 표현식에 사용할 수 있도록 다음 구조가 `$states`에 할당됩니다.
```
# Reserved $states variable in JSONata states
$states = {
"input": // Original input to the state
"result": // API or sub-workflow's result (if successful)
"errorOutput": // Error Output (only available in a Catch)
"context": // Context object
}
```
상태 입력 시 Step Functions는 상태 입력을 **`$states.input`**에 할당합니다. `$states.input`의 값은 JSONata 표현식을 허용하는 모든 필드에서 사용할 수 있습니다. `$states.input`은 항상 원래 상태 입력을 참조합니다.
`Task`, `Parallel` 및 `Map` 상태:
+ **`$states.result`**는 성공할 경우 API 또는 하위 워크플로의 원시 결과를 참조합니다.
+ **`$states.errorOutput`**는 API 또는 하위 워크플로가 실패한 경우 오류 출력을 참조합니다.
`$states.errorOutput`은 `Catch` 필드의 `Assign` 또는 `Output`에서 사용할 수 있습니다.
액세스할 수 없는 필드 및 상태에서 `$states.result` 또는 `$states.errorOutput`에 액세스하려는 시도는 상태 머신의 생성, 업데이트 또는 검증 시 포착됩니다.
`$states.context` 객체는 `StartTime`, 작업 토큰 및 초기 워크플로 입력과 같은 특정 실행에 대한 워크플로 정보를 제공합니다. 자세한 내용은 [Step Functions의 컨텍스트 객체에서 실행 데이터 액세스](input-output-contextobject.md)를 참조하세요.
## 변수 이름 구문
변수 이름은 [Unicode® Standard Annex \$131](https://unicode.org/reports/tr31/)에 설명된 유니코드 식별자 규칙을 따릅니다. 변수 이름의 첫 번째 문자는 Unicode ID\$1Start 문자여야 하며, 두 번째 및 후속 문자는 Unicode ID\$1Continue 문자여야 합니다. 변수 이름의 최대 길이는 80입니다.
변수 이름 규칙은 JavaScript 및 기타 프로그래밍 언어에 대한 규칙과 유사합니다.
## 변수 범위
Step Functions 워크플로는 *workflow-local* 범위를 사용하여 변수와의 경합 상태를 방지합니다.
워크플로-로컬 범위에는 상태 머신의 **Status** 필드 내의 모든 상태가 포함되지만 Parallel 또는 Map 상태 내의 상태는 포함되지 않습니다. Parallel 또는 Map 상태 내의 상태는 외부 범위 변수를 참조할 수 있지만 별도의 워크플로-로컬 변수 및 값을 생성하고 유지합니다.
`Parallel` 브랜치 및 `Map` 반복에서는 **외부 범위**의 변수 값에 액세스할 수 있습니다. 하지만 다른 동시 브랜치 또는 반복의 변수 값에 액세스할 수 없습니다. 오류를 처리할 때 `Catch`의 `Assign` 필드는 외부 범위, 즉 Parallel/Map 상태가 존재하는 범위의 변수에 값을 할당할 수 있습니다.
예외: **Distributed Map 상태**에서는 외부 범위의 변수를 참조할 수 없습니다.
범위 내 어떤 상태에서든 변수에 값을 할당하는 경우 해당 변수는 범위 내에 존재합니다. 일반적인 오류를 방지하기 위해 내부 범위에 할당된 변수는 외부 범위에 할당된 변수와 동일한 이름을 가질 수 없습니다. 예를 들어 최상위 범위가 `myVariable`이라는 변수에 값을 할당하는 경우 다른 범위(`Map`, `Parallel` 내부)도 `myVariable`에 할당할 수 없습니다.
변수에 대한 액세스는 현재 범위에 따라 달라집니다. Parallel 또는 Map 상태는 자체 범위가 있지만 외부 범위의 변수에 액세스할 수 있습니다.
Parallel 또는 Map 상태가 완료되면 모든 변수가 범위를 벗어나 액세스가 중지됩니다. **Output 필드**를 사용하여 Parallel 브랜치 및 Map 반복에서 데이터를 전달합니다.
## ASL에서 필드 할당
ASL의 `Assign` 필드는 하나 이상의 변수에 값을 할당하는 데 사용됩니다. `Assign` 필드는 각 상태의 최상위 수준(`Succeed` 및 `Fail` 제외), `Choice` 상태 규칙 내부 및 `Catch` 필드 내부에서 사용할 수 있습니다. 예:
```
# Example of Assign with JSONata
"Store inputs": {
"Type": "Pass",
"Next": "Get Current Price",
"Comment": "Store the input desired price into a variable: $desiredPrice",
"Assign": {
"desiredPrice": "{% $states.input.desired_price %}",
"maximumWait": "{% $states.input.max_days %}"
}
},
```
`Assign` 필드는 JSON 객체를 사용합니다. 각 최상위 필드는 할당할 변수의 이름을 지정합니다. 이전 예에서 변수 이름은 `desiredPrice` 및 `maximumWait`입니다. JSONata를 사용할 때 `{% ... %}`는 변수 또는 더 복잡한 표현식을 포함할 수 있는 JSONata 표현식을 나타냅니다. JSONata 표현식에 대한 자세한 내용은 [JSONata.org 설명서](https://docs.jsonata.org/overview.html)를 참조하세요.
쿼리 언어로 **JSONata**를 사용하는 경우 다음 다이어그램은 **Assign** 및 **Output** 필드를 병렬로 처리하는 방법을 보여줍니다. 영향 참고: *변수 값을 할당해도 Output 출력에는 영향을 주지 않습니다. *
![\[Diagram showing a comparison of JSONPath and JSONata flow.\]](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/vars-jsonata.png)
다음 JSONata 예는 상태 입력에서 `order.product`를 검색합니다. 변수 `currentPrice`는 작업 결과의 값으로 설정됩니다.
```
# Example of Task with JSONata assignment from result
{
"Type": "Task",
...
"Assign": {
"product": "{% $states.input.order.product %}",
"currentPrice": "{% $states.result.Payload.current_price %}"
},
"Next": "the next state"
}
```
참고: 변수의 일부에는 값을 할당할 수 **없습니다**. 예를 들어 `"Assign":{"x":42}`는 할 수 있지만 `"Assign":{"x.y":42}` 또는 `"Assign":{"x[2]":42}`는 할 수 없습니다.
## 할당 필드의 평가 순서
Step Functions 상태의 모든 변수 참조는 **상태 항목**에 있는 것처럼 값을 사용합니다.
앞의 사실은 `Assign` 필드가 하나 이상의 변수에 값을 할당하는 방법을 이해하는 데 중요합니다. 먼저 새 값이 계산되고 Step Functions는 변수에 새 값을 할당합니다. 새 변수 값은 **다음 **상태부터 사용할 수 있습니다. 예를 들어 다음 `Assign` 필드를 고려합니다.
```
# Starting values: $x=3, $a=6
"Assign": {
"x": "{% $a %}",
"nextX": "{% $x %}"
}
# Ending values: $x=6, $nextX=3
```
앞의 예에서 변수 `x`는 모두 할당되고 참조됩니다.
모든 표현식이 ***먼저 평가***되고 할당이 이루어집니다. 그리고 새로 할당된 값은 **다음** 상태에서 사용할 수 있습니다.
예를 자세히 살펴보겠습니다. 이전 상태에서 `$x`에 값 삼(3)이 할당되었고 `$a`에 값 육(6)이 할당되었다고 가정합니다. 다음 단계에서는 프로세스에 대해 설명합니다.
1. 모든 표현식은 모든 변수의 **현재** 값을 사용하여 평가됩니다.
`"{% $a %}"` 표현식은 6으로 평가되고 `"{% $x %}"` 표현식은 3으로 평가됩니다.
1. 다음으로 할당이 이루어집니다.
`$x`에는 값 육(6)이 할당됩니다.
`$nextX`에는 값 삼(3)이 할당됩니다.
참고: `$x`가 이전에 할당되지 않은 경우 `$x`가 *정의되지* 않았기 때문에 예가 **실패**합니다.
요약하면 Step Functions는 **모든** 표현식을 평가한 다음 할당합니다. `Assign` 필드에서 변수가 발생하는 순서는 중요하지 **않습니다**.
## Limits
단일 변수의 최대 크기는 표준 및 Express 워크플로 모두에 대해 256Kib입니다.
단일 `Assign` 필드의 모든 변수에 대한 최대 결합 크기도 256Kib입니다. 예를 들어 X와 Y를 128KiB에 할당할 수 있지만 동일한 `Assign` 필드에서 X와 Y를 모두 256KiB에 할당할 수는 없습니다.
저장된 모든 변수의 총 크기는 실행당 10MiB를 초과할 수 없습니다.
## JSONPath 상태에서 변수 사용
변수는 쿼리 언어에 JSONPath를 사용하는 상태에서도 사용할 수 있습니다.
JSONpath 표현식(`$.` 또는 `$$.` 구문)을 수락하는 모든 필드에서 변수를 참조할 수 있습니다. 단, 상태 입력에서 상태 결과를 주입할 위치를 지정하는 `ResultPath`는 예외입니다. 변수는 `ResultPath`에서 사용할 수 없습니다.
JSONPath에서 `$` 기호는 '현재' 값을 나타내며 `$$`는 컨텍스트 객체 상태를 나타냅니다. JSONPath 표현식은 `$.customer.name`에서와 같이 `$.`로 시작할 수 있습니다. `$$.Execution.Id`에서처럼 `$$.`를 사용하여 컨텍스트에 액세스할 수 있습니다.
변수를 참조하려면 `$x` 또는 `$order.numItems`와 같은 변수 이름 앞에 `$` 기호를 사용합니다.
내장 함수를 허용하는** JSONPath** 필드에서는 `States.Format('The order number is {}', $order.number)`와 같은 인수에 변수를 사용할 수 있습니다.
다음 다이어그램은 **JSONPath** 작업의 할당 단계가 동시에 ResultSelector에서 어떻게 발생하는지 보여줍니다.
![\[Logical diagram of a state that uses JSONPath query language.\]](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/vars-jsonpath.png)
**JSONPath에서 변수 할당**
JSONPath 변수 할당은 페이로드 템플릿과 유사하게 동작합니다. `.$`로 끝나는 필드는 Step Functions가 상태 머신 실행 중에 값으로 평가하는 JSONPath 표현식입니다(예: `$.order..product` 및 `$.order.total`).
```
# Example of Assign with JSONPath
{
"Type": "Task",
...
"Assign": {
"products.$": "$.order..product",
"orderTotal.$": "$.order.total"
},
"Next": "the next state"
}
```
JSONPath 상태의 경우 `Assign` 필드의 `$` 값은 상태 유형에 따라 다릅니다. `Task,` `Map`에서 `Parallel` 상태 `$`는 API/하위 워크플로 결과를 나타냅니다. `Choice` 및 `Wait` 상태에서 `$`는 `InputPath`가 상태 입력에 적용된 후의 값인 *유효 입력*을 나타냅니다. `Pass`의 경우 `$`는 `Result` 필드에 의해 생성되었든 `InputPath`/`Parameters` 필드에 의해 생성되었든 상관없이 결과를 나타냅니다.
다음 JSONPath 예에서는 `details` 변수에 JSON 객체, `resultCode`에 JSONPath 표현식의 결과 `$.result.code`, `message`에 JSONPath 표현식의 결과 `States.Format('Hello {}', $customer.name)`을 할당합니다. 이것이 `Task` 상태인 경우 `$.order.items` 및 `$.result.code`의 `$`에서 API 결과를 참조합니다. `startTime` 변수는 컨텍스트 객체 `$$.Execution.StartTime`의 값과 함께 할당됩니다.
```
"Assign": {
"details": {
"status": "SUCCESS",
"lineItems.$": "$.order.items"
},
"resultCode.$": "$.result.code",
"message.$": "States.Format('Hello {}', $customer.name)",
"startTime.$": "$$.Execution.StartTime"
}
```
# Step Functions에서 JSONata로 데이터 트랜스포밍
JSONata를 사용하면 워크플로에서 데이터를 **선택**하고 **트랜스포밍**할 수 있는 강력한 오픈 소스 쿼리 및 표현식 언어를 얻을 수 있습니다. 간략한 소개와 전체 JSONata 참조는 [JSONata.org 설명서](https://docs.jsonata.org/overview.html)를 참조하세요.
**지원되는 JSONata 버전**
Step Functions는 JSONata 버전 2.0.6을 지원합니다.
다음 동영상에서는 DynamoDB 예를 사용하여 Step Functions의 변수 및 JSONata를 설명합니다.
기존 워크플로에 JSONata 쿼리 및 트랜스포메이션 언어를 사용하려면 옵트인해야 합니다. 콘솔에서 워크플로를 생성할 때는 최상위 상태 머신 `QueryLanguage`에 대해 JSONata를 선택하는 것이 좋습니다. JSONPath를 사용하는 기존 또는 새 워크플로의 경우 콘솔은 개별 상태를 JSONata로 변환하는 옵션을 제공합니다.
JSONata를 선택하면 워크플로 필드가 5개의 JSONPath 필드(`InputPath`, `Parameters`, `ResultSelector`, `ResultPath` 및 `OutputPath`)에서 `Arguments` 및 `Output` 필드 2개로만 축소됩니다. 또한 JSON 객체 키 이름에는 `.$`를 사용하지 **않습니다**.
Step Functions를 처음 사용하는 경우 JSONata 표현식이 다음 구문을 사용함을 알기만 하면 됩니다.
**JSONata 구문:** `"{% %}"`
다음 코드 샘플은 JSONPath에서 JSONata로의 변환을 보여줍니다.
```
# Original sample using JSONPath
{
"QueryLanguage": "JSONPath", // Set explicitly; could be set and inherited from top-level
"Type": "Task",
...
"Parameters": {
"static": "Hello",
"title.$": "$.title",
"name.$": "$customerName", // With $customerName declared as a variable
"not-evaluated": "$customerName"
}
}
```
```
# Sample after conversion to JSONata
{
"QueryLanguage": "JSONata", // Set explicitly; could be set and inherited from top-level
"Type": "Task",
...
"Arguments": { // JSONata states do not have Parameters
"static": "Hello",
"title": "{% $states.input.title %}",
"name": "{% $customerName %}", // With $customerName declared as a variable
"not-evaluated": "$customerName"
}
}
```
`"María"`에 할당된 입력 `{ "title" : "Doctor" }` 및 `customerName` 변수가 주어지면 두 상태 머신 모두 다음과 같은 JSON 결과를 생성합니다.
```
{
"static": "Hello",
"title": "Doctor",
"name": "María",
"not-evaluated": "$customerName"
}
```
다음 다이어그램에서는 JSONPath(왼쪽)를 JSONata(오른쪽)로 변환하여 상태 머신의 단계 복잡성을 줄이는 방법을 보여주는 그래픽 표현을 볼 수 있습니다.
![\[JSONPath 및 JSONata 상태의 필드를 비교하는 다이어그램입니다.\]](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/compare-jsonpath-jsonata.png)
상태 입력에서 **Arguments**로 데이터를 선택하고 트랜스포밍하여 통합 작업으로 전송할 수 있습니다(선택 사항). JSONata를 사용하면 변수에 할당하고 상태 **Output**에 대해 작업의 **결과**를 선택하고 트랜스포밍할 수 있습니다(선택 사항).
참고: **Assign** 및 **Output** 단계는 **병렬**로 발생합니다. 변수 할당 중에 데이터를 트랜스포밍하도록 선택하면 출력 단계에서 트랜스포밍된 데이터를 사용할 수 **없습니다**. 출력 단계에서 JSONata 트랜스포메이션을 다시 적용해야 합니다.
![\[JSONata 쿼리 언어를 사용하는 상태의 논리적 다이어그램입니다.\]](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/vars-jsonata.png)
## QueryLanguage 필드
워크플로 ASL 정의에는 상태 머신 정의의 최상위 수준과 개별 상태에 `QueryLanguage` 필드가 있습니다. 개별 상태 내에서 `QueryLanguage`를 설정하면 상태 머신을 한 번에 모두 업그레이드하는 대신 기존 상태 머신에서 JSONata를 점진적으로 채택할 수 있습니다.
`QueryLanguage` 필드는 `"JSONPath"` 또는 `"JSONata"`로 설정할 수도 있습니다. 최상위 `QueryLanguage` 필드를 생략하면 기본적으로 `"JSONPath"`로 설정됩니다. 상태에 상태 수준 `QueryLanguage` 필드가 포함된 경우 Step Functions는 해당 상태에 지정된 쿼리 언어를 사용합니다. 상태에 `QueryLanguage` 필드가 포함되지 않은 경우 최상위 `QueryLanguage` 필드에 지정된 쿼리 언어를 사용합니다.
## JSON 문자열로 JSONata 표현식 작성
ASL 필드 값의 문자열, JSON 객체 필드 또는 JSON 배열 요소가 `{% %}` 문자로 묶이면 해당 문자열은 JSONata로 평가됩니다. 참고로 문자열은 선행 공백 없이 `{%`로 시작하고 후행 공백 없이 `%}`로 끝나야 합니다. 표현식을 잘못 열거나 닫으면 검증 오류가 발생합니다.
다음은 몇 가지 예제입니다.
+ `"TimeoutSeconds" : "{% $timeout %}"`
+ `Task` 상태의 `"Arguments" : {"field1" : "{% $name %}"}`
+ `Map` 상태의 `"Items": [1, "{% $two %}", 3]`
모든 ASL 필드가 JSONata를 허용하는 것은 아닙니다. 예를 들어 각 상태의 `Type` 필드는 상수 문자열로 설정해야 합니다. 마찬가지로 `Task` 상태 `Resource` 필드는 상수 문자열이어야 합니다. `Map` 상태 `Items` 필드는 배열 또는 객체로 평가되어야 하는 JSON 배열, JSON 객체 또는 JSONata 표현식을 수락합니다.
## 예약 변수: \$1states
Step Functions는 ** `$states` **라는 단일 예약 변수를 정의합니다. JSONata 상태에서는 JSONata 표현식에 사용할 수 있도록 다음 구조가 `$states`에 할당됩니다.
```
# Reserved $states variable in JSONata states
$states = {
"input": // Original input to the state
"result": // API or sub-workflow's result (if successful)
"errorOutput": // Error Output (only available in a Catch)
"context": // Context object
}
```
상태 입력 시 Step Functions는 상태 입력을 ** `$states.input` **에 할당합니다. `$states.input`의 값은 JSONata 표현식을 허용하는 모든 필드에서 사용할 수 있습니다. `$states.input`은 항상 원래 상태 입력을 참조합니다.
`Task`, `Parallel` 및 `Map` 상태:
+ ** `$states.result` **는 성공할 경우 API 또는 하위 워크플로의 원시 결과를 나타냅니다.
+ ** `$states.errorOutput` **는 API 또는 하위 워크플로가 실패한 경우 오류 출력을 참조합니다.
`$states.errorOutput`은 `Catch` 필드의 `Assign` 또는 `Output`에서 사용할 수 있습니다.
액세스할 수 없는 필드 및 상태에서 `$states.result` 또는 `$states.errorOutput`에 액세스하려는 시도는 상태 머신의 생성, 업데이트 또는 검증 시 포착됩니다.
`$states.context` 객체는 `StartTime`, 작업 토큰 및 초기 워크플로 입력과 같은 특정 실행에 대한 워크플로 정보를 제공합니다. 자세한 내용은 [Step Functions의 컨텍스트 객체에서 실행 데이터 액세스](input-output-contextobject.md) 단원을 참조하십시오.
## 표현식 오류 처리
런타임 시 JSONata 표현식 평가는 다음과 같은 다양한 이유로 실패할 수 있습니다.
+ **유형 오류** - `$x` 또는 `$y`가 숫자가 아니면 `{% $x + $y %}`와 같은 표현식이 실패합니다.
+ **유형 비호환성** - 표현식은 필드가 허용하지 않는 유형으로 평가될 수 있습니다. 예를 들어 `TimeoutSeconds` 필드에는 숫자 입력이 필요하므로 `$timeout`가 문자열을 반환하면 `{% $timeout %}` 표현식이 실패합니다.
+ **범위를 벗어난 값** - 필드의 허용 범위를 벗어난 값을 생성하는 표현식은 실패합니다. 예를 들어 `{% $evaluatesToNegativeNumber %}`와 같은 표현식은 `TimeoutSeconds` 필드에서 실패합니다.
+ **결과 반환 실패** - JSON은 정의되지 않은 값 표현식을 나타낼 수 없으므로 표현식 `{% $data.thisFieldDoesNotExist %}`에 오류가 발생합니다.
각 경우 인터프리터에서 `States.QueryEvaluationError` 오류가 발생합니다. Task, Map 및 Parallel 상태는 오류를 포착하는 `Catch` 필드와 오류에 대해 재시도하는 `Retry` 필드를 제공할 수 있습니다.
## JSONPath에서 JSONata로 변환
다음 섹션에서는 JSONPath와 JSONata로 작성된 코드의 차이점을 비교하고 설명합니다.
### 더 이상 경로 필드 없음
ASL을 사용하려면 개발자가 에서 `TimeoutSecondsPath`와 같이 필드의 `Path` 버전을 사용하여 JSONPath를 사용할 때 상태 데이터에서 값을 선택해야 합니다. JSONata를 사용하는 경우 ASL은 `TimeoutSeconds`와 같은 경로가 아닌 `Path` 필드에서 `{% %}`에 포함된 JSONata 표현식을 자동으로 해석하므로 더 이상 필드를 사용하지 않습니다.
+ JSONPath 레거시 예: `"TimeoutSecondsPath": "$timeout"`
+ JSONata: `"TimeoutSeconds": "{% $timeout %}"`
마찬가지로 `Map` 상태는 JSON 배열, JSON 객체 또는 배열 또는 객체로 평가되어야 하는 JSONata 표현식을 허용하는 `Items` 필드로 대체`ItemsPath`되었습니다.
### JSON 객체
ASL은 *페이로드 템플릿*이라는 용어를 사용하여 `Parameters` 및 `ResultSelector` 필드 값에 대한 JSONPath 표현식을 포함할 수 있는 JSON 객체를 설명합니다. JSONata 평가는 자체적으로 또는 JSON 객체나 JSON 배열 내에서 발생하는 모든 문자열에 대해 수행되므로 ASL은 JSONata에 대해 페이로드 템플릿이라는 용어를 사용하지 않습니다.
### 더 이상 .\$1 없음
ASL에서는 JSONPath 및 내장 함수를 사용하려면 페이로드 템플릿의 필드 이름에 '`.$`'를 추가해야 합니다. `"QueryLanguage":"JSONata"`를 지정할 때 JSON 객체 필드 이름에 '`.$`' 규칙을 더 이상 사용하지 않습니다. 대신 JSONata 표현식을 `{% %}` 문자로 묶습니다. 객체가 다른 배열 또는 객체 내에 얼마나 깊이 중첩되는지에 관계없이 모든 문자열 값 필드에 동일한 규칙을 사용합니다.
### Arguments 및 Output 필드
`QueryLanguage`를 `JSONata`로 설정하면 이전 I/O 처리 필드(`InputPath`, `Parameters`, `ResultSelector`, `ResultPath` 및 `OutputPath`)가 비활성화되고 대부분의 상태는 `Arguments` 및 `Output`이라는 2개의 새 필드를 가져옵니다.
JSONata는 JSONPath에 사용되는 필드에 비해 I/O 트랜스포메이션을 수행하는 더 간단한 방법을 제공합니다. JSONata의 기능은 JSONPath를 사용하는 이전 5개 필드보다 `Arguments` 및 `Output`을 더 효과적으로 만듭니다. 또한 이러한 새 필드 이름은 ASL을 단순화하고 값 전달 및 반환을 위한 모델을 명확히 하는 데 도움이 됩니다.
`Arguments` 및 `Output` 필드(및 `Map` 상태의 `ItemSelector`와 같은 기타 유사한 필드)는 다음과 같은 JSON 객체 중 하나를 허용합니다.
```
"Arguments": {
"field1": 42,
"field2": "{% jsonata expression %}"
}
```
또는 다음과 같이 JSONata 표현식을 직접 사용할 수 있습니다.
```
"Output": "{% jsonata expression %}"
```
출력은 `"Output":true`, `"Output":42`과 같은 모든 유형의 JSON 값도 수락할 수 있습니다.
`Arguments` 및 `Output` 필드는 JSONata만 지원하므로 JSONPath를 사용하는 워크플로에서 사용할 수 없습니다. 반대로 `InputPath`, `Parameters`, `ResultSelector`, `ResultPath`, `OutputPath`, 및 기타 JSONPath 필드는 JSONPath에서만 지원되므로 JSONata를 최상위 워크플로 또는 상태 쿼리 언어로 사용할 때는 경로 기반 필드를 사용할 수 없습니다.
### Pass 상태
패스 상태의 선택적 **결과**는 이전에 가상 작업의 *출력*으로 처리되었습니다. 워크플로 또는 상태 쿼리 언어로 JSONata를 선택한 경우 이제 새 **Output** 필드를 사용할 수 있습니다.
### Choice 상태
JSONPath를 사용하는 경우 Choice 상태에는 입력 `Variable` 및 다음 `NumericLessThanEqualsPath`와 같은 수많은 비교 경로가 있습니다.
```
# JSONPath choice state sample, with Variable and comparison path
"Check Price": {
"Type": "Choice",
"Default": "Pause",
"Choices": [
{
"Variable": "$.current_price.current_price",
"NumericLessThanEqualsPath": "$.desired_price",
"Next": "Send Notification"
} ],
}
```
JSONata의 경우 Choice 상태에는 JSONata 표현식을 사용할 수 있는 `Condition`이 있습니다.
```
# Choice state after JSONata conversion
"Check Price": {
"Type": "Choice",
"Default": "Pause"
"Choices": [
{
"Condition": "{% $current_price <= $states.input.desired_priced %}",
"Next": "Send Notification"
} ]
```
참고: 변수 및 비교 필드는 JSONPath에서만 사용할 수 있습니다. 조건은 JSONata에서만 사용할 수 있습니다.
## JSONata 예
Workflow Studio에서 다음 예를 생성하여 JSONata를 실험할 수 있습니다. 상태 머신을 생성 및 실행하거나 **Test 상태**를 사용하여 데이터를 전달하고 상태 머신 정의를 수정할 수도 있습니다.
### 예: 입력 및 출력
이 예에서는 JSONata를 선택할 때 `$states.input`을 사용하여 상태 입력을 지정하고 `Output` 필드를 사용하여 상태 출력을 지정하는 방법을 보여줍니다.
```
{
"Comment": "Input and Output example using JSONata",
"QueryLanguage": "JSONata",
"StartAt": "Basic Input and Output",
"States": {
"Basic Input and Output": {
"QueryLanguage": "JSONata",
"Type": "Succeed",
"Output": {
"lastName": "{% 'Last=>' & $states.input.customer.lastName %}",
"orderValue": "{% $states.input.order.total %}"
}
}
}
}
```
워크플로가 입력으로 다음을 사용하여 실행되는 경우:
```
{
"customer": {
"firstName": "Martha",
"lastName": "Rivera"
},
"order": {
"items": 7,
"total": 27.91
}
}
```
테스트 상태 또는 상태 머신 실행은 다음 JSON 출력을 반환합니다.
```
{
"lastName": "Last=>Rivera",
"orderValue": 27.91
}
```
![\[테스트 중인 상태의 입력 및 출력을 보여주는 스크린샷입니다.\]](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/jsonata-basic-io.png)
### 예: JSONata로 필터링
JSONata [경로 연산자](https://docs.jsonata.org/path-operators)를 사용하여 데이터를 필터링할 수 있습니다. 예를 들어, 입력을 위한 제품 목록이 있고 0칼로리가 포함된 제품만 처리하려고 한다고 가정해 보겠습니다. 다음 ASL을 사용하여 상태 머신 정의를 생성하고 다음 샘플 입력으로 `FilterDietProducts` 상태를 테스트할 수 있습니다.
**JSONata를 사용한 필터링을 위한 상태 머신 정의**
```
{
"Comment": "Filter products using JSONata",
"QueryLanguage": "JSONata",
"StartAt": "FilterDietProducts",
"States": {
"FilterDietProducts": {
"Type": "Pass",
"Output": {
"dietProducts": "{% $states.input.products[calories=0] %}"
},
"End": true
}
}
}
```
**테스트용 샘플 입력**
```
{
"products": [
{
"calories": 140,
"flavour": "Cola",
"name": "Product-1"
},
{
"calories": 0,
"flavour": "Cola",
"name": "Product-2"
},
{
"calories": 160,
"flavour": "Orange",
"name": "Product-3"
},
{
"calories": 100,
"flavour": "Orange",
"name": "Product-4"
},
{
"calories": 0,
"flavour": "Lime",
"name": "Product-5"
}
]
}
```
**상태 머신에서 단계 테스트의 출력**
```
{
"dietProducts": [
{
"calories": 0,
"flavour": "Cola",
"name": "Product-2"
},
{
"calories": 0,
"flavour": "Lime",
"name": "Product-5"
}
]
}
```
![\[테스트 중인 JSONata 표현식의 출력 예입니다.\]](http://docs.aws.amazon.com/ko_kr/step-functions/latest/dg/images/test-state-jsonata.png)
## Step Functions에서 제공하는 JSONata 함수
JSONata에는 문자열, 숫자, 집계, 부울, 배열, 객체, 날짜/시간 및 고차 함수에 대한 함수 라이브러리가 포함되어 있습니다. Step Functions는 JSONata 표현식에 사용할 수 있는 추가 JSONata 함수를 제공합니다. 이러한 내장 함수는 Step Functions 내장 함수를 대체하는 역할을 합니다. 내장 함수는 JSONPath 쿼리 언어를 사용하는 상태에서만 사용할 수 있습니다.
참고: 파라미터로 정수 값이 필요한 기본 제공 JSONata 함수는 제공된 정수가 아닌 숫자를 자동으로 반올림합니다.
**\$1partition -** 대형 배열을 분할하는 `States.ArrayPartition` 내장 함수와 동일한 JSONata입니다.
첫 번째 파라미터는 분할할 배열이고, 두 번째 파라미터는 청크 크기를 나타내는 정수입니다. 반환 값은 2차원 배열입니다. 인터프리터는 입력 배열을 청크 크기로 지정된 크기의 여러 배열로 청크합니다. 배열에 남아 있는 항목 수가 청크 크기보다 작으면 마지막 배열 청크 길이가 이전 배열 청크 길이보다 짧을 수 있습니다.
```
"Assign": {
"arrayPartition": "{% $partition([1,2,3,4], $states.input.chunkSize) %}"
}
```
**\$1range** - 값 배열을 생성하기 위한 `States.ArrayRange` 내장 함수와 동일한 JSONata입니다.
이 함수는 인수 3개를 사용합니다. 첫 번째 인수는 새 배열의 첫 번째 요소를 나타내는 정수이고, 두 번째 인수는 새 배열의 마지막 요소를 나타내는 정수입니다. 세 번째 인수는 새 배열의 요소를 위한 델타 값 정수입니다. 반환 값은 함수의 첫 번째 인수부터 델타로 조정된 사이에 요소가 있는 함수의 두 번째 인수까지 새로 생성된 값 배열입니다. 델타 값은 양수 또는 음수일 수 있으며, 종료 값에 도달하거나 초과할 때까지 마지막에서 각 요소를 늘리거나 줄일 수 있습니다.
```
"Assign": {
"arrayRange": "{% $range(0, 10, 2) %}"
}
```
**\$1hash** - `States.Hash` 내장 함수와 동일한 JSONata 사용하여 지정된 입력의 해시 값을 계산할 수 있습니다.
이 함수는 인수 2개를 사용합니다. 첫 번째 인수는 해싱할 소스 문자열입니다. 두 번째 인수는 해시 계산을 위해 해싱 알고리즘을 나타내는 문자열입니다. 해싱 알고리즘은 `"MD5"`, `"SHA-1"`, `"SHA-256"`, `"SHA-384"`, `"SHA-512"` 값 중 하나여야 합니다. 반환 값은 데이터의 계산된 해시의 문자열입니다.
이 함수는 JSONata가 기본적으로 해시 계산 기능을 지원하지 않기 때문에 생성되었습니다.
```
"Assign": {
"myHash": "{% $hash($states.input.content, $hashAlgorithmName) %}"
}
```
**\$1random** - `0 ≤ n < 1`에서 난수 n을 반환하는 `States.MathRandom` 내장 함수와 동일한 JSONata입니다.
함수는 임의 함수의 시드 값을 나타내는 *선택적* 정수 인수를 사용합니다. 이 함수를 동일한 시드 값과 함께 사용하면 같은 숫자가 반환됩니다.
오버로드된 이 함수 [https://docs.jsonata.org/numeric-functions#random](https://docs.jsonata.org/numeric-functions#random)은 내장 JSONata 함수가 시드 값을 수락하지 않기 때문에 생성되었습니다.
```
"Assign": {
"randNoSeed": "{% $random() %}",
"randSeeded": "{% $random($states.input.seed) %}"
}
```
**\$1uuid** - `States.UUID` 내장 함수의 JSONata 버전입니다.
함수에는 인수가 필요하지 않습니다. 이 함수는 v4 UUID를 반환합니다.
이 함수는 JSONata가 UUID 생성 기능을 기본적으로 지원하지 않기 때문에 생성되었습니다.
```
"Assign": {
"uniqueId": "{% $uuid() %}"
}
```
**\$1parse** - JSON 문자열을 역직렬화하는 JSONata 함수입니다.
함수는 문자열화된 JSON을 유일한 인수로 사용합니다.
JSONata는 `$eval`을 통해 이 기능을 지원하지만 Step Functions 워크플로에서 `$eval`은 지원되지 않습니다.
```
"Assign": {
"deserializedPayload": "{% $parse($states.input.json_string) %}"
}
```
# Step Functions의 컨텍스트 객체에서 실행 데이터 액세스
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
컨텍스트 객체는 실행 중에 사용할 수 있는 내부 JSON 구조로, 여기에 상태 머신과 실행에 대한 정보가 포함됩니다. 컨텍스트는 워크플로의 특정 실행에 대한 정보를 제공합니다. 워크플로는 `$states.context`를 사용하여 JSONata 표현식의 컨텍스트 객체를 참조할 수 있습니다.
## 컨텍스트 객체 액세스
**JSONata에서 컨텍스트 객체에 액세스하려면**
JSONata 상태의 컨텍스트 객체에 액세스하려면 JSONata 표현식에서 `$states.context`를 사용합니다.
```
{
"ExecutionID" : "{% $states.context.Execution.Id %}"
}
```
**JSONPath에서 컨텍스트 객체에 액세스하려면**
JSONPath의 컨텍스트 객체에 액세스하려면 먼저 키 끝에 `.$`를 추가하여 값이 경로임을 나타냅니다. 그런 다음 값 앞에 `$$.`를 추가하여 컨텍스트 객체에서 노드를 선택합니다.
```
{
"ExecutionID.$": "$$.Execution.Id"
}
```
JSONPath 상태는 다음 JSONPath 필드의 컨텍스트(`$$.`)를 참조할 수 있습니다.
+ `InputPath`
+ `OutputPath`
+ `ItemsPath`(Map 상태에서)
+ `Variable`(Choice 상태에서)
+ `ResultSelector`
+ `Parameters`
+ 변수와 변수 비교 연산자
## 컨텍스트 객체 필드
컨텍스트 객체에는 상태 머신, 상태, 실행 및 작업에 대한 정보가 포함됩니다. 이 JSON 객체에는 각 데이터 유형에 대한 노드가 다음과 같은 형식으로 포함됩니다.
```
{
"Execution": {
"Id": "String",
"Input": {},
"Name": "String",
"RoleArn": "String",
"StartTime": "Format: ISO 8601",
"RedriveCount": Number,
"RedriveTime": "Format: ISO 8601"
},
"State": {
"EnteredTime": "Format: ISO 8601",
"Name": "String",
"RetryCount": Number
},
"StateMachine": {
"Id": "String",
"Name": "String"
},
"Task": {
"Token": "String"
}
}
```
실행 중에 컨텍스트 객체는 관련 데이터로 채워집니다.
경우에 따라 새 필드가 컨텍스트에 추가됩니다. JSON 컨텍스트를 직접 처리하는 경우 알 수 없는 새 필드를 정상적으로 처리할 수 있는 코드를 만드는 것이 좋습니다. 예를 들어 JSON을 마셜링 해제하기 위해 Jackson 라이브러리를 사용하는 경우 `UnrecognizedPropertyException`을 방지하려면 `ObjectMapper`에서 `FAIL_ON_UNKNOWN_PROPERTIES`를 `false`로 설정하는 것이 좋습니다.
`RedriveTime` 컨텍스트 객체는 실행을 redriven한 경우에만 사용 가능합니다. [redriven a Map Run](redrive-map-run.md)한 경우 표준 유형의 하위 워크플로에만 `RedriveTime` 컨텍스트 객체를 사용할 수 있습니다. Express 유형의 하위 워크플로가 포함된 redriven 맵 실행의 경우에는 `RedriveTime`을 사용할 수 없습니다.
진행 중인 실행의 콘텐츠에는 다음 형식의 세부 사항이 포함됩니다.
```
{
"Execution": {
"Id": "arn:aws:states:region:123456789012:execution:stateMachineName:executionName",
"Input": {
"key": "value"
},
"Name": "executionName",
"RoleArn": "arn:aws:iam::123456789012:role...",
"StartTime": "2025-08-27T10:04:42Z"
},
"State": {
"EnteredTime": "2025-08-27T10:04:42.001Z",
"Name": "Test",
"RetryCount": 3
},
"StateMachine": {
"Id": "arn:aws:states:region:123456789012:stateMachine:stateMachineName",
"Name": "stateMachineName"
},
"Task": {
"Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W"
}
}
```
**소수 초가 포함된 타임스탬프 형식**
Step Functions는 필요에 따라 출력이 0, 3, 6 또는 9자리일 수 있음을 명시하는 ISO8601 사양을 따릅니다. 타임스탬프에 분수 초가 0인 경우 Step Functions는 출력을 패딩하지 않고 후행 0을 제거합니다.
Step Functions 타임스탬프를 사용하는 코드를 생성하는 경우 코드는 분수 초의 가변 수를 처리할 수 있어야 합니다.
## Map 상태의 컨텍스트 객체 데이터
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
[`Map` 상태](state-map.md)를 처리할 때 컨텍스트에는 `Index`, `Value` 및 `Source`도 포함됩니다.
`Map` 상태 반복마다 `Index`는 현재 처리 중인 배열 항목의 인덱스 번호를 포함하는 반면 `Value`는 처리 중인 배열 항목을 포함합니다. 또한 `Source`는 `CSV`, `JSON`, `JSONL` 또는 `PARQUET`의 InputType입니다.
`Map` 상태에서 컨텍스트 객체에는 다음 데이터가 포함됩니다.
```
"Map": {
"Item": {
"Index" : Number,
"Key" : "String", // Only valid for JSON objects
"Value" : "String",
"Source": "String"
}
}
```
`Map` 상태에서만 이러한 데이터를 사용할 수 있으며 `ItemSelector(맵)` 필드에 지정할 수 있습니다.
**참고**
컨텍스트 객체의 파라미터는 `ItemSelector` 섹션에 포함된 상태가 아니라 기본 `Map` 상태의 `ItemProcessor` 블록에서 정의할 수 있습니다.
상태 머신이 단순한 **JSONPath** `Map` 상태로 지정되는 것을 고려할 때 컨텍스트 객체의 정보를 다음과 같이 주입할 수 있습니다.
```
{
"StartAt": "ExampleMapState",
"States": {
"ExampleMapState": {
"Type": "Map",
"ItemSelector": {
"ContextIndex.$": "$$.Map.Item.Index",
"ContextValue.$": "$$.Map.Item.Value",
"ContextSource.$": "$$.Map.Item.Source"
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "TestPass",
"States": {
"TestPass": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
JSONata의 경우 `$states.context` 변수에서 추가 Map 상태 컨텍스트 정보에 액세스할 수 있습니다.
```
{
"StartAt": "ExampleMapState",
"States": {
"ExampleMapState": {
"Type": "Map",
"ItemSelector": {
"ContextIndex": "{% $states.context.Map.Item.Index %}",
"ContextValue": "{% $states.context.Map.Item.Value %}",
"ContextSource": "{% $states.context.Map.Item.Source %}"
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "TestPass",
"States": {
"TestPass": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
다음 입력으로 이전 상태 머신을 실행하면 `Index`와 `Value`가 출력에 삽입됩니다.
```
[
{
"who": "bob"
},
{
"who": "meg"
},
{
"who": "joe"
}
]
```
실행 출력은 다음과 같이 반복 3회마다 `Index` 및 `Value` 항목 값을 반환합니다.
```
[
{
"ContextIndex": 0,
"ContextValue": {
"who": "bob"
},
"ContextSource" : "STATE_DATA"
},
{
"ContextIndex": 1,
"ContextValue": {
"who": "meg"
},
"ContextSource" : "STATE_DATA"
},
{
"ContextIndex": 2,
"ContextValue": {
"who": "joe"
},
"ContextSource" : "STATE_DATA"
}
]
```
`$states.context.Map.Item.Source`는 다음 중 하나입니다.
+ 상태 입력의 경우 값은 `STATE_DATA`입니다.
+ `Transformation=NONE`이 있는 `Amazon S3 LIST_OBJECTS_V2`의 경우 값은 버킷의 S3 URI를 표시합니다. 예를 들어 `S3://bucket-name`입니다.
+ 다른 모든 입력 유형의 경우 값은 Amazon S3 URI가 됩니다. 예를 들어 `S3://bucket-name/object-key`입니다.
# JSONPath 경로 사용
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
Amazon States Language에서 *경로*는 JSON 텍스트 내 구성 요소를 식별하는 데 사용할 수 있는 `$`로 시작하는 문자열입니다. 경로는 `QueryLanguage`가 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)로 설정된 경우에만 사용할 수 있는 JSONPath 구문을 따릅니다. `InputPath`, `ResultPath` 및 `OutputPath`의 값을 지정할 때 입력 하위 집합에 액세스하기 위한 경로를 지정할 수 있습니다
필드 이름에 [JsonPath ABNF](https://www.ietf.org/archive/id/draft-ietf-jsonpath-base-21.html#jsonpath-abnf) 규칙의 `member-name-shorthand` 정의에 포함되지 않은 문자가 포함된 경우에는 대괄호 표기법을 사용해야 합니다. 따라서 구두점(`_` 제외)과 같은 특수 문자를 인코딩하려면 대괄호 표기법을 사용해야 합니다. 예를 들어 `$.abc.['def ghi']`입니다.
## 참조 경로
*참조 경로*는 JSON 구조에서 단일 노드만 식별할 수 있는 방식으로 구문이 제한되는 경로입니다.
+ 객체 필드는 점(`.`) 및 대괄호(`[ ]`) 표기를 통해서만 액세스할 수 있습니다.
+ `length()`가 지원되지 않은 등의 함수
+ 기호가 아닌 어휘 연산자(예: `subsetof`)는 지원되지 않습니다.
+ 정규 표현식을 기준으로 또는 JSON 구조의 다른 값을 참조하는 필터링은 지원되지 않습니다.
+ `@`, `,`, `:`, `?` 연산자는 지원되지 않습니다.
예를 들어 상태 입력 데이터에 다음과 같은 값이 포함된 경우:
```
{
"foo": 123,
"bar": ["a", "b", "c"],
"car": {
"cdr": true
}
}
```
다음과 같은 참조 경로가 반환합니다.
```
$.foo => 123
$.bar => ["a", "b", "c"]
$.car.cdr => true
```
특정 상태에서는 경로 및 참조 경로를 사용하여 상태 머신의 흐름을 제어하거나 상태 설정 또는 옵션을 구성합니다. 자세한 내용은 [데이터 흐름 시뮬레이터를 사용한 워크플로 입력 및 출력 경로 처리 모델링](https://aws.amazon.com/blogs/compute/modeling-workflow-input-output-path-processing-with-data-flow-simulator/) 및 [에서 JSONPath를 효과적으로 사용을AWS Step Functions](https://aws.amazon.com/blogs/compute/using-jsonpath-effectively-in-aws-step-functions/) 참조하세요.
### 배열의 배열 평면화
상태 머신의 [병렬 워크플로 상태](state-parallel.md) 또는 [Map 워크플로 상태](state-map.md) 상태에서 배열의 배열을 반환하는 경우 [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) 필드를 사용하여 배열을 평면 배열로 변환할 수 있습니다. Parallel 또는 Map 상태 정의 내에 이 필드를 포함하여 이러한 상태의 결과를 조작할 수 있습니다.
배열을 평면화하려면 다음 예시와 같이 `ResultSelector` 필드에서 `[*]` 구문을 사용합니다.
```
"ResultSelector": {
"flattenArray.$": "$[*][*]"
}
```
배열을 평면화하는 방법을 보여주는 예제는 다음 자습서의 *3단계*를 참조하세요.
+ [Step Functions에서 Lambda 함수를 사용하여 배치 데이터 처리](tutorial-itembatcher-param-task.md)
+ [Step Functions에서 Lambda 함수를 사용하여 개별 항목 처리](tutorial-itembatcher-single-item-process.md)
# Step Functions 워크플로의 파라미터를 사용하여 파라미터 조작
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
`InputPath`, `Parameters` 및 `ResultSelector` 필드는 JSON이 워크플로를 통해 이동할 때 JSON을 조작하는 방법을 제공합니다. `InputPath`는 경로를 사용하여 JSON 표기법을 필터링해 전달되는 입력을 제한할 수 있습니다([JSONPath 경로 사용](amazon-states-language-paths.md) 참조). `Parameters` 필드를 사용하면 정적 값을 사용하거나 경로를 사용하여 입력에서 선택한 항목을 사용하여 키-값 페어 모음을 전달할 수 있습니다.
`ResultSelector` 필드는 `ResultPath`가 적용되기 전의 상태 결과를 조작할 수 있는 방법을 제공합니다.
AWS Step Functions는 먼저 `InputPath` 필드를 적용한 다음 `Parameters` 필드를 적용합니다. 우선 `InputPath`를 사용하여 원시 입력을 필터링한 다음 `Parameters`를 적용하여 입력을 추가로 조작하거나 새 값을 추가할 수 있습니다. 그런 다음 `ResultSelector` 필드를 사용하여 `ResultPath`가 적용되기 전의 상태 출력을 조작할 수 있습니다.
## InputPath
`InputPath`를 사용하여 상태 입력의 부분을 선택합니다.
예를 들어, 상태에 대한 입력에 다음이 포함된다고 가정합니다.
```
{
"comment": "Example for InputPath.",
"dataset1": {
"val1": 1,
"val2": 2,
"val3": 3
},
"dataset2": {
"val1": "a",
"val2": "b",
"val3": "c"
}
}
```
`InputPath`를 적용할 수 있습니다.
```
"InputPath": "$.dataset2",
```
위의 `InputPath`를 통해 입력으로 전달되는 JSON은 다음과 같습니다.
```
{
"val1": "a",
"val2": "b",
"val3": "c"
}
```
**참고**
경로는 값의 모음을 출력할 수 있습니다. 다음 예제를 살펴보세요.
```
{ "a": [1, 2, 3, 4] }
```
경로 `$.a[0:2]`를 적용하는 경우 결과는 다음과 같습니다.
```
[ 1, 2 ]
```
## Parameters
이 섹션에서는 파라미터 필드를 사용할 수 있는 다양한 방법을 설명합니다.
### 키-값 페어
`Parameters` 필드를 사용하여 입력으로 전달되는 키-값 페어 컬렉션을 만듭니다. 각각의 값은 상태 머신 정의에 포함한 정적 값 또는 path를 통해 입력 또는 컨텍스트 객체에서 선택한 값일 수 있습니다. path를 사용하여 값을 선택한 키-값 페어의 경우 키 이름이 `.$` 기호로 끝나야 합니다.
예를 들어 다음과 같은 입력을 제공한다고 가정합니다.
```
{
"comment": "Example for Parameters.",
"product": {
"details": {
"color": "blue",
"size": "small",
"material": "cotton"
},
"availability": "in stock",
"sku": "2317",
"cost": "$23"
}
}
```
정보의 일부를 선택하기 위해 상태 머신 정의에 이러한 파라미터를 지정할 수 있습니다.
```
"Parameters": {
"comment": "Selecting what I care about.",
"MyDetails": {
"size.$": "$.product.details.size",
"exists.$": "$.product.availability",
"StaticValue": "foo"
}
},
```
이전 입력 및 `Parameters` 필드를 지정하면 다음과 같은 JSON이 전달됩니다.
```
{
"comment": "Selecting what I care about.",
"MyDetails": {
"size": "small",
"exists": "in stock",
"StaticValue": "foo"
}
},
```
입력 외에도 컨텍스트 객체라고 알려진 특수 JSON 객체에 액세스할 수 있습니다. 컨텍스트 객체에는 상태 머신 실행에 대한 정보가 포함됩니다. [Step Functions의 컨텍스트 객체에서 실행 데이터 액세스](input-output-contextobject.md)을(를) 참조하세요.
### 연결된 리소스
또한 `Parameters` 필드는 정보를 연결된 리소스로 전달할 수 있습니다. 예를 들어 작업 상태가 AWS Batch작업을 오케스트레이션하는 경우 관련 API 파라미터를 해당 서비스의 API 작업에 직접 전달할 수 있습니다. 자세한 내용은 다음을 참조하세요.
+ [Step Functions의 서비스 API에 파라미터 전달](connect-parameters.md)
+ [ 서비스 통합](integrate-services.md)
### Amazon S3
상태 간에 전달하는 Lambda 함수 데이터가 262,144바이트를 초과하는 경우 Amazon S3를 사용하여 데이터를 저장하고 다음 방법 중 하나를 구현하는 것이 좋습니다.
+ `Map` 상태에서 Amazon S3 데이터 소스에서 직접 입력을 읽을 수 있도록 워크플로에서 *Distributed Map 상태*를 사용합니다. 자세한 내용은 [분산 모드](state-map-distributed.md) 단원을 참조하십시오.
+ `Payload` 파라미터에 있는 버킷의 Amazon 리소스 이름(ARN)을 파싱하여 버킷 이름과 키 값을 가져옵니다. 자세한 내용은 [Step Functions에서 대용량 페이로드를 전달하는 대신 Amazon S3 ARN 사용](sfn-best-practices.md#avoid-exec-failures) 단원을 참조하십시오.
또는 구현을 조정하여 실행에서 더 작은 용량의 페이로드를 전달할 수 있습니다.
## ResultSelector
`ResultSelector` 필드를 사용하여 `ResultPath`가 적용되기 전의 상태 결과를 조작합니다. 이 `ResultSelector` 필드를 사용하면 키 값 페어 컬렉션을 만들 수 있습니다. 여기서 값은 정적이거나 상태 결과에서 선택한 값입니다. `ResultSelector` 필드를 사용하면 `ResultPath` 필드에 전달하려는 상태 결과 부분을 선택할 수 있습니다.
**참고**
`ResultPath` 필드를 사용하여 `ResultSelector` 필드 출력을 원래 입력에 추가할 수 있습니다.
`ResultSelector`는 다음 상태의 선택적 필드입니다.
+ [Map 워크플로 상태](state-map.md)
+ [Task 워크플로 상태](state-task.md)
+ [병렬 워크플로 상태](state-parallel.md)
예를 들어 Step Functions 서비스 통합에서는 결과의 페이로드 외에 메타데이터를 반환합니다. `ResultSelector`는 결과의 일부를 선택하고 `ResultPath`를 사용하여 상태 입력과 병합할 수 있습니다. 이 예제에서는 `resourceType` 및 `ClusterId`만 선택하고 이를 Amazon EMR createCluster.sync의 상태 입력과 병합하려고 합니다. 다음을 예로 들어보겠습니다.
```
{
"resourceType": "elasticmapreduce",
"resource": "createCluster.sync",
"output": {
"SdkHttpMetadata": {
"HttpHeaders": {
"Content-Length": "1112",
"Content-Type": "application/x-amz-JSON-1.1",
"Date": "Mon, 25 Nov 2019 19:41:29 GMT",
"x-amzn-RequestId": "1234-5678-9012"
},
"HttpStatusCode": 200
},
"SdkResponseMetadata": {
"RequestId": "1234-5678-9012"
},
"ClusterId": "AKIAIOSFODNN7EXAMPLE"
}
}
```
그런 다음 `ResultSelector`를 사용하여 `resourceType` 및 `ClusterId`를 선택할 수 있습니다.
```
"Create Cluster": {
"Type": "Task",
"Resource": "arn:aws:states:::elasticmapreduce:createCluster.sync",
"Parameters": {
},
"ResultSelector": {
"ClusterId.$": "$.output.ClusterId",
"ResourceType.$": "$.resourceType"
},
"ResultPath": "$.EMROutput",
"Next": "Next Step"
}
```
지정된 입력에서 `ResultSelector`를 사용하면 다음이 생성됩니다.
```
{
"OtherDataFromInput": {},
"EMROutput": {
"ClusterId": "AKIAIOSFODNN7EXAMPLE",
"ResourceType": "elasticmapreduce",
}
}
```
### 배열의 배열 평면화
상태 머신의 [병렬 워크플로 상태](state-parallel.md) 또는 [Map 워크플로 상태](state-map.md) 상태에서 배열의 배열을 반환하는 경우 [ResultSelector](#input-output-resultselector) 필드를 사용하여 배열을 평면 배열로 변환할 수 있습니다. Parallel 또는 Map 상태 정의 내에 이 필드를 포함하여 이러한 상태의 결과를 조작할 수 있습니다.
배열을 평면화하려면 다음 예시와 같이 `ResultSelector` 필드에서 `[*]` 구문을 사용합니다.
```
"ResultSelector": {
"flattenArray.$": "$[*][*]"
}
```
배열을 평면화하는 방법을 보여주는 예제는 다음 자습서의 *3단계*를 참조하세요.
+ [Step Functions에서 Lambda 함수를 사용하여 배치 데이터 처리](tutorial-itembatcher-param-task.md)
+ [Step Functions에서 Lambda 함수를 사용하여 개별 항목 처리](tutorial-itembatcher-single-item-process.md)
# 예: Step Functions 워크플로에서 경로를 통해 상태 데이터 조작
**상태 관리 및 데이터 트랜스포밍**
[변수를 사용하여 상태 간 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
이 주제에는 InputPath, ResultPath 및 OutputPath 필드를 사용하여 상태 입력 및 출력 JSON을 조작하는 방법의 예가 포함되어 있습니다.
[Fail 워크플로 상태](state-fail.md) 상태 또는 [Succeed 워크플로 상태](state-succeed.md) 상태 이외의 모든 상태에는 `InputPath`, `ResultPath` 또는 `OutputPath`와 같은 입력 및 출력 처리 필드가 포함될 수 있습니다. 또한 [Wait 워크플로 상태](state-wait.md) 및 [Choice 워크플로 상태](state-choice.md) 상태는 `ResultPath` 필드를 지원하지 않습니다. 이러한 필드를 사용하면 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)를 사용하여 워크플로를 통해 이동하는 JSON 데이터를 필터링할 수 있습니다.
또한 `Parameters` 필드를 사용하여 워크플로를 통해 이동하는 JSON 데이터를 조작할 수 있습니다. `Parameters` 사용에 대한 자세한 내용은 [Step Functions 워크플로의 파라미터를 사용하여 파라미터 조작](input-output-inputpath-params.md)을 참조하십시오.
예를 들어 [Lambda를 사용하는 Step Functions 상태 머신 만들기](tutorial-creating-lambda-state-machine.md) 자습서에 설명된 AWS Lambda 함수와 상태 머신을 시작합니다. 상태 머신을 수정하여 다음 `InputPath`, `ResultPath`, `OutputPath`를 포함할 수 있습니다.
```
{
"Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
"StartAt": "HelloWorld",
"States": {
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:HelloFunction",
"InputPath": "$.lambda",
"ResultPath": "$.data.lambdaresult",
"OutputPath": "$.data",
"End": true
}
}
}
```
다음 입력을 사용하여 실행을 시작합니다.
```
{
"comment": "An input comment.",
"data": {
"val1": 23,
"val2": 17
},
"extra": "foo",
"lambda": {
"who": "AWS Step Functions"
}
}
```
`comment` 및 `extra` 노드를 폐기하지만 `data` 노드의 정보를 보존하면서 동시에 Lambda 함수의 출력을 포함하려고 한다고 가정해보겠습니다.
업데이트된 상태 머신에서 `Task` 상태를 변경하여 작업으로 입력을 전달합니다.
```
"InputPath": "$.lambda",
```
상태 머신 정의의 이 라인은 작업 입력을 상태 입력의 `lambda` 노드로만 한정합니다. Lambda 함수는 입력으로 JSON 객체 `{"who": "AWS Step Functions"}`만 수신합니다.
```
"ResultPath": "$.data.lambdaresult",
```
이 `ResultPath`는 상태 머신에게 Lambda 함수 결과를 기존 상태 머신 입력의 `data` 노드 하위 개념으로 `lambdaresult`라는 노드에 입력하라고 지시합니다. 원래 입력과 `OutputPath`를 사용한 결과에서 다른 어떠한 조작도 수행하지 않으므로 이제 상태 출력에는 원래 입력과 함께 Lambda 함수의 결과가 포함됩니다.
```
{
"comment": "An input comment.",
"data": {
"val1": 23,
"val2": 17,
"lambdaresult": "Hello, AWS Step Functions!"
},
"extra": "foo",
"lambda": {
"who": "AWS Step Functions"
}
}
```
하지만 목적은 `data` 노드만 보존하고 Lambda 함수의 결과를 포함하는 것이었습니다. `OutputPath`는 이런 결합된 JSON을 상태 출력으로 보내기 전에 필터링합니다.
```
"OutputPath": "$.data",
```
기존 입력에서 `data` 노드(`lambdaresult`가 입력한 `ResultPath` 하위 개념 포함)만 선택하여 출력으로 전달될 수 있게 합니다. 상태 출력은 다음과 같이 필터링됩니다.
```
{
"val1": 23,
"val2": 17,
"lambdaresult": "Hello, AWS Step Functions!"
}
```
이 `Task`작업 상태에서:
1. `InputPath`는 `lambda` 노드만 입력에서 Lambda 함수로 보냅니다.
1. `ResultPath`는 기존 입력의 `data` 노드의 하위 개념으로 결과를 입력합니다.
1. `OutputPath`는 상태 입력에서 `data` 노드만 상태 출력으로 전달하도록 이제 Lambda 함수의 결과를 포함된 상태 입력을 필터링합니다.
**Example JsonPath를 사용하여 원래 상태 머신 입력, 결과 및 최종 출력을 조작하는 예제**
보험 신청자의 신원과 주소를 확인하는 다음 상태 머신을 고려해보겠습니다.
전체 예제를 보려면 [Step Functions에서 JSON 경로를 사용하는 방법](https://github.com/aws-samples/serverless-account-signup-service)을 참조하세요.
```
{
"Comment": "Sample state machine to verify an applicant's ID and address",
"StartAt": "Verify info",
"States": {
"Verify info": {
"Type": "Parallel",
"End": true,
"Branches": [
{
"StartAt": "Verify identity",
"States": {
"Verify identity": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2:111122223333:function:check-identity:$LATEST"
},
"End": true
}
}
},
{
"StartAt": "Verify address",
"States": {
"Verify address": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2:111122223333:function:check-address:$LATEST"
},
"End": true
}
}
}
]
}
}
}
```
다음 입력을 사용하여 이 상태 머신을 실행하면 검증을 수행하는 Lambda 함수에서 확인이 필요한 데이터만 입력으로 예상하므로 실행이 실패합니다. 따라서 적절한 JsonPath를 사용하여 확인할 정보가 포함된 노드를 지정해야 합니다.
```
{
"data": {
"firstname": "Jane",
"lastname": "Doe",
"identity": {
"email": "jdoe@example.com",
"ssn": "123-45-6789"
},
"address": {
"street": "123 Main St",
"city": "Columbus",
"state": "OH",
"zip": "43219"
},
"interests": [
{
"category": "home",
"type": "own",
"yearBuilt": 2004
},
{
"category": "boat",
"type": "snowmobile",
"yearBuilt": 2020
},
{
"category": "auto",
"type": "RV",
"yearBuilt": 2015
},
]
}
}
```
`check-identity` Lambda 함수에서 사용해야 하는 노드를 지정하려면 다음과 같이 `InputPath` 필드를 사용합니다.
```
"InputPath": "$.data.identity"
```
그리고 `check-address` Lambda 함수에서 사용해야 하는 노드를 지정하려면 다음과 같이 `InputPath` 필드를 사용합니다.
```
"InputPath": "$.data.address"
```
이제 원본 상태 머신 입력 내에 검증 결과를 저장하려면 다음과 같이 `ResultPath` 필드를 사용합니다.
```
"ResultPath": "$.results"
```
하지만 ID 및 확인 결과만 필요하고 원래 입력을 삭제하려면 다음과 같이 `OutputPath` 필드를 사용합니다.
```
"OutputPath": "$.results"
```
자세한 내용은 [Step Functions에서 입력 및 출력 처리](concepts-input-output-filtering.md) 섹션을 참조하세요.
## OutputPath를 사용하여 상태 출력 필터링
`OutputPath`를 사용하면 다음 상태로 전달할 상태 출력 부분을 선택할 수 있습니다. 이 접근 방식을 사용하면 원치 않는 정보를 필터링하고 필요한 JSON 부분만 전달할 수 있습니다.
`OutputPath`를 지정하지 않으면 기본값 `$`가 사용됩니다. 이 값은 전체 JSON 노드(상태 입력, 작업 결과 및 `ResultPath`에 따라 결정됨)를 다음 상태로 전달합니다.
# Step Functions에서 ResultPath를 사용하여 상태 출력 지정
**상태 관리 및 데이터 트랜스포밍**
이 페이지에서는 JSONPath를 참조합니다. Step Functions는 최근에 상태를 관리하고 데이터를 트랜스포밍하기 위해 변수와 JSONata를 추가했습니다.
[변수를 사용하여 데이터 전달](workflow-variables.md)과 [JSONata를 사용하여 데이터 트랜스포밍](transforming-data.md)에 대해 알아봅니다.
상태 출력은 상태 입력의 복사본, 상태 결과(예, `Task` 상태의 Lambda 함수 출력), 또는 상태 입력 및 결과의 조합일 수 있습니다. `ResultPath`를 사용하여 상태 출력으로 이들의 어떤 조합을 전달할지 관리합니다.
다음 상태 유형은 결과를 생성하고 `ResultPath:`를 포함할 수 있습니다.
+ [Pass 워크플로 상태](state-pass.md)
+ [Task 워크플로 상태](state-task.md)
+ [병렬 워크플로 상태](state-parallel.md)
+ [Map 워크플로 상태](state-map.md)
`ResultPath`를 사용하여 작업 입력과 작업 결과를 결합하거나 이들 중 하나를 선택합니다. `ResultPath`에 제공한 경로는 어떤 정보가 출력으로 전달될지 관리합니다.
**참고**
`ResultPath`는 JSON에서 단일 노드만 식별하는 범위가 제한된 [참조 경로](amazon-states-language-paths.md#amazon-states-language-reference-paths)의 사용으로 한정됩니다. [Amazon States Language](concepts-amazon-states-language.md)의 [참조 경로](amazon-states-language-paths.md#amazon-states-language-reference-paths) 섹션을 참조하세요.
## ResultPath를 사용하여 입력을 태스크 결과로 바꾸기
`ResultPath`를 지정하지 않으면 기본 동작은 `"ResultPath": "$"`와 동일합니다. 상태는 전체 상태 입력을 작업의 결과로 바꿉니다.
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$"
# Task result
"Hello, Step Functions!"
# State Output
"Hello, Step Functions!"
```
**참고**
`ResultPath`는 결과를 출력으로 전달하기 전에 입력에 결과의 내용을 포함할 경우 사용됩니다. 하지만 `ResultPath`가 지정되지 않으면 기본적으로 전체 입력을 대체합니다.
## 결과 삭제 및 원래의 입력 유지
`ResultPath`를 `null`로 설정하면 **원래의 입력**이 출력에 전달됩니다. 상태의 입력 페이로드가 태스크 결과에 관계없이 출력에 직접 복사됩니다.
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": null
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
```
## ResultPath를 사용하여 입력에 결과 포함
ResultPath에 대한 경로를 지정하는 경우 상태 출력은 상태 입력과 작업 결과를 결합합니다.
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$.taskresult"
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions",
"taskresult" : "Hello, Step Functions!"
}
```
결과를 입력의 하위 노드로 입력할 수 있습니다. `ResultPath` 속성을 다음과 같이 설정합니다.
```
"ResultPath": "$.strings.lambdaresult"
```
입력은 다음과 같습니다.
```
{
"comment": "An input comment.",
"strings": {
"string1": "foo",
"string2": "bar",
"string3": "baz"
},
"who": "AWS Step Functions"
}
```
태스크 결과는 입력에 `strings` 노드의 하위 항목으로 삽입됩니다.
```
{
"comment": "An input comment.",
"strings": {
"string1": "foo",
"string2": "bar",
"string3": "baz",
"lambdaresult": "Hello, Step Functions!"
},
"who": "AWS Step Functions"
}
```
다음 상태 출력은 기존 입력 JSON과 결과를 하위 노드로 포함합니다.
## ResultPath를 사용하여 입력의 노드를 결과로 업데이트
ResultPath에 기존 노드를 지정하면 작업 결과가 해당 기존 노드를 대체합니다.
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$.comment"
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "Hello, Step Functions!",
"details": "Default example",
"who" : "Step Functions"
}
```
## ResultPath를 사용하여 `Catch`에 오류와 입력 포함
경우에 따라 오류가 있는 기존 입력을 보존하고자 할 수 있습니다. `Catch`에 `ResultPath`를 사용하면 원래 입력을 바꾸는 대신 오류를 포함시킬 수 있습니다.
```
"Catch": [{
"ErrorEquals": ["States.ALL"],
"Next": "NextTask",
"ResultPath": "$.error"
}]
```
이전 `Catch` 상태가 오류를 발견하면 상태 입력 내 `error` 노드에 결과를 포함합니다. 예를 들어 다음 입력을 고려해 보십시오.
```
{"foo": "bar"}
```
오류 발견 시 상태 출력은 다음과 같습니다.
```
{
"foo": "bar",
"error": {
"Error": "Error here"
}
}
```
오류를 처리하는 방법에 대한 자세한 내용은 다음을 참조하십시오.
+ [Step Functions 워크플로의 오류 처리](concepts-error-handling.md)
+ [Step Functions 상태 머신을 사용하여 오류 조건 처리](tutorial-handling-error-conditions.md)
# 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
]
}
]
```