내장 함수

Amazon States Language는 Task 상태를 사용하지 않고도 기본적인 데이터 처리 작업을 수행하는 데 도움이 되는 몇 가지 내장 함수를 제공합니다. 내장 함수는 프로그래밍 언어의 함수와 비슷해 보이는 구성입니다. 이 함수를 사용하여 페이로드 빌더에서 Resource 상태의 Task 필드를 오가는 데이터를 처리할 수 있습니다.

Amazon States Language에서 내장 함수는 수행하려는 데이터 처리 작업의 유형에 따라 다음과 같은 범주로 그룹화됩니다.

• 배열의 내장 함수

• 데이터 인코딩 및 디코딩을 위한 내장 함수

• 해시 계산을 위한 내장 함수

• JSON 데이터 조작을 위한 내장 함수

• 수학 연산을 위한 내장 함수

• 문자열 작업을 위한 내장 연산

• 고유 식별자 생성을 위한 내장 함수

• 일반 연산을 위한 내장 함수

참고

• 내장 함수를 사용하려면 다음 예제와 같이 상태 시스템 정의의 키 값에 .$를 지정해야 합니다.

  "KeyId.$": "States.Array($.Id)"

• 워크플로의 필드 내에 내장 함수를 최대 10개까지 중첩할 수 있습니다. 다음 예제에서는 중첩된 내장 함수 9개가 포함된 myArn이라고 하는 필드를 보여줍니다.

  "myArn.$": "States.Format('{}.{}.{}', States.ArrayGetItem(States.StringSplit(States.ArrayGetItem(States.StringSplit($.ImageRecipe.Arn, '/'), 2), '.'), 0), States.ArrayGetItem(States.StringSplit(States.ArrayGetItem(States.StringSplit($.ImageRecipe.Arn, '/'), 2), '.'), 1))"

작은 정보

로컬 개발 환경에서 Step Functions를 사용하는 경우 워크플로에 모든 내장 함수가 포함될 수 있도록 버전 1.12.0 이상을 사용해야 합니다.

내장 함수를 지원하는 필드

다음 표에서는 각 상태에 내장 함수를 지원하는 필드를 보여줍니다.

내장 함수를 지원하는 필드
State
	Pass	작업	Choice	Wait	Succeed	Fail	Parallel	지도
InputPath
파라미터	✓	✓					✓	✓
ResultSelector		✓					✓	✓
ResultPath
OutputPath
변수
<Comparison Operator>Path
TimeoutSecondsPath
HeartbeatSecondsPath
보안 인증		✓

배열의 내장 함수

배열을 조작할 때 다음 내장 함수를 사용하세요.

States.Array

States.Array 내장 함수는 인수를 0개 이상 사용합니다. 인터프리터는 제공된 순서대로 인수 값이 포함된 JSON 배열을 반환합니다. 다음 입력을 예로 들어보겠습니다.

{
  "Id": 123456
}

다음을 사용할 수 있습니다.

"BuildId.$": "States.Array($.Id)"

그러면 응답이 반환됩니다.

“BuildId”: [123456]

States.ArrayPartition

States.ArrayPartition 내장 함수를 사용하여 큰 배열을 분할할 수 있습니다. 이 내장 함수를 사용하여 데이터를 분할한 다음 작은 청크의 페이로드를 전송할 수도 있습니다.

이 내장 함수에서는 인수 2개를 사용합니다. 첫 번째 인수는 배열이고 두 번째 인수는 청크 크기를 정의합니다. 인터프리터는 입력 배열을 청크 크기로 지정된 크기의 여러 배열로 청크합니다. 배열에 남아 있는 항목 수가 청크 크기보다 작으면 마지막 배열 청크 길이가 이전 배열 청크 길이보다 짧을 수 있습니다.

입력 검증

• 배열을 함수의 첫 번째 인수에 대한 입력 값으로 지정해야 합니다.

• 청크 크기 값을 나타내는 두 번째 인수에는 0이 아닌 양의 정수를 지정해야 합니다.

  두 번째 인수에 정수가 아닌 값을 지정하면 Step Functions에서 가장 가까운 정수로 반올림합니다.

• 입력 배열은 Step Functions의 페이로드 크기 한도인 256KB를 초과할 수 없습니다.

다음 입력 배열을 예로 들어보겠습니다.

{"inputArray": [1,2,3,4,5,6,7,8,9] }

States.ArrayPartition 함수를 사용하여 배열을 값이 4개인 청크로 나눌 수 있습니다.

"inputArray.$": "States.ArrayPartition($.inputArray,4)"

그러면 다음과 같은 배열 청크가 반환됩니다.

{"inputArray": [ [1,2,3,4], [5,6,7,8], [9]] }

이전 예제에서 States.ArrayPartition 함수는 배열 3개를 출력합니다. 처음 두 배열에는 청크 크기로 정의된 대로 각각 값 4개가 포함됩니다. 세 번째 배열은 나머지 값을 포함하며 정의된 청크 크기보다 작습니다.

States.ArrayContains

States.ArrayContains 내장 함수를 사용하여 배열에 특정 값이 있는지 확인할 수 있습니다. 예를 들어 이 함수를 사용하여 Map 상태 반복에 오류가 있었는지 여부를 감지할 수 있습니다.

이 내장 함수에서는 인수 2개를 사용합니다. 첫 번째 인수는 배열이고, 두 번째 인수는 배열 내에서 검색할 값입니다.

입력 검증

• 배열을 함수의 첫 번째 인수에 대한 입력값으로 지정해야 합니다.

• 유효한 JSON 객체를 두 번째 인수로 지정해야 합니다.

• 입력 배열은 Step Functions의 페이로드 크기 한도인 256KB를 초과할 수 없습니다.

다음 입력 배열을 예로 들어보겠습니다.

{
   "inputArray": [1,2,3,4,5,6,7,8,9],
   "lookingFor": 5
}

States.ArrayContains 함수를 사용하여 inputArray 내에서 lookingFor 값을 찾을 수 있습니다.

"contains.$": "States.ArrayContains($.inputArray, $.lookingFor)"

lookingFor에 저장된 값이 inputArray에 포함되므로 States.ArrayContains에서 다음과 같은 결과를 반환합니다.

{"contains": true }

States.ArrayRange

States.ArrayRange 내장 함수를 사용하여 특정 범위의 요소를 포함하는 새 배열을 만들 수 있습니다. 새 배열에는 요소가 최대 1,000개까지 포함될 수 있습니다.

이 함수는 인수 3개를 사용합니다. 첫 번째 인수는 새 배열의 첫 번째 요소이고 두 번째 인수는 새 배열의 마지막 요소입니다. 세 번째 인수는 새 배열의 요소 간 증분 값입니다.

입력 검증

• 모든 인수에 정수 값을 지정해야 합니다.

  인수에 정수가 아닌 값을 지정하면 Step Functions에서 가장 가까운 정수로 반올림합니다.

• 세 번째 인수에는 0이 아닌 값을 지정해야 합니다.

• 새로 생성된 배열에는 항목이 1,000개 넘게 포함될 수 없습니다.

예를 들어 다음 States.ArrayRange 함수를 사용하여 첫 번째 값이 1이고 최종 값이 9이며 첫 번째 값과 최종 값 사이의 값이 각 항목에 대해 2씩 증가하는 배열을 만듭니다.

"array.$": "States.ArrayRange(1, 9, 2)"

그러면 다음과 같은 배열이 반환됩니다.

{"array": [1,3,5,7,9] }

States.ArrayGetItem

이 내장 함수는 지정된 인덱스 값을 반환합니다. 이 함수는 인수 2개를 사용합니다. 첫 번째 인수는 값의 배열이고 두 번째 인수는 반환할 값의 배열 인덱스입니다.

예를 들어 다음 inputArray 및 index 값을 사용합니다.

{
   "inputArray": [1,2,3,4,5,6,7,8,9],
   "index": 5
}

States.ArrayGetItem 함수를 사용하여 다음 값에서 배열 내 index 위치 5의 값을 반환할 수 있습니다.

"item.$": "States.ArrayGetItem($.inputArray, $.index)"

이 예제의 경우 States.ArrayGetItem에서 다음 결과를 반환합니다.

{ "item": 6 }

States.ArrayLength

States.ArrayLength 내장 함수는 배열 길이를 반환합니다. 여기에는 인수 하나가 있으며 이 인수는 길이를 반환할 배열입니다.

다음 입력 배열을 예로 들어보겠습니다.

{
   "inputArray": [1,2,3,4,5,6,7,8,9]
}

States.ArrayLength를 사용하여 inputArray 길이를 반환할 수 있습니다.

"length.$": "States.ArrayLength($.inputArray)"

이 예제의 경우 States.ArrayLength에서 배열 길이를 나타내는 다음 JSON 객체를 반환합니다.

{ "length": 9 }

States.ArrayUnique

States.ArrayUnique 내장 함수는 배열에서 중복된 값을 제거하고 고유한 요소만 포함하는 배열을 반환합니다. 이 함수는 정렬되지 않을 수 있는 배열을 유일한 인수로 사용합니다.

예를 들어 다음 inputArray에는 일련의 중복 값이 포함되어 있습니다.

{"inputArray": [1,2,3,3,3,3,3,3,4] }

States.ArrayUnique 함수를 사용하고 중복된 값을 제거하려는 배열을 지정할 수 있습니다.

"array.$": "States.ArrayUnique($.inputArray)"

States.ArrayUnique 함수에서 고유한 요소만 포함되어 있는 다음 배열을 반환하고 모든 중복 값을 제거합니다.

{"array": [1,2,3,4] }

데이터 인코딩 및 디코딩을 위한 내장 함수

다음 내장 함수를 사용하여 Base64 인코딩 체계를 기반으로 데이터를 인코딩하거나 디코딩할 수 있습니다.

States.Base64Encode

States.Base64Encode 내장 함수를 사용하여 MIME Base64 인코딩 체계를 기반으로 데이터를 인코딩할 수 있습니다. 이 함수를 사용하면 AWS Lambda 함수를 사용하지 않고도 데이터를 다른 AWS 서비스에 전달할 수 있습니다.

이 함수는 최대 10,000자의 데이터 문자열을 유일한 인수로 사용하여 인코딩합니다.

예를 들어 다음 input 문자열을 고려해보겠습니다.

{"input": "Data to encode" }

States.Base64Encode 함수를 사용하여 input 문자열을 MIME Base64 문자열로 인코딩할 수 있습니다.

"base64.$": "States.Base64Encode($.input)"

States.Base64Encode 함수에서 응답으로 다음 인코딩된 데이터를 반환합니다.

{"base64": "RGF0YSB0byBlbmNvZGU=" }

States.Base64Decode

States.Base64Decode 내장 함수를 사용하여 MIME Base64 디코딩 체계를 기반으로 데이터를 디코딩할 수 있습니다. 이 함수를 사용하면 Lambda 함수를 사용하지 않고도 데이터를 다른 AWS 서비스에 전달할 수 있습니다.

이 함수는 최대 10,000자의 Base64로 인코딩된 데이터 문자열을 유일한 인수로 사용하여 디코딩합니다.

다음 입력을 예로 들어보겠습니다.

{"base64": "RGF0YSB0byBlbmNvZGU=" }

States.Base64Decode 함수를 사용하여 base64 문자열을 인간이 읽을 수 있는 문자열로 디코딩할 수 있습니다.

"data.$": "States.Base64Decode($.base64)"

States.Base64Decode function에서 응답으로 다음과 같은 디코딩된 데이터를 반환합니다.

{"data": "Decoded data" }

해시 계산을 위한 내장 함수

States.Hash

States.Hash 내장 함수를 사용하여 지정된 입력의 해시 값을 계산할 수 있습니다. 이 함수를 사용하면 Lambda 함수를 사용하지 않고도 데이터를 다른 AWS 서비스에 전달할 수 있습니다.

이 함수는 인수 2개를 사용합니다. 첫 번째 인수는 해시 값을 계산하려는 데이터입니다. 두 번째 인수는 해시 계산을 수행하는 데 사용할 해싱 알고리즘입니다. 제공하는 데이터는 10,000자 이하의 객체 문자열이어야 합니다.

지정하는 해싱 알고리즘은 다음 알고리즘 중 하나일 수 있습니다.

• MD5

• SHA-1

• SHA-256

• SHA-384

• SHA-512

예를 들어 이 함수를 사용하면 지정된 Algorithm를 사용해 Data 문자열의 해시 값을 계산할 수 있습니다.

{
   "Data": "input data", 
   "Algorithm": "SHA-1" 
}

States.Hash 함수를 사용하여 해시 값을 계산할 수 있습니다.

"output.$": "States.Hash($.Data, $.Algorithm)"

States.Hash 함수에서 응답으로 다음 해시 값을 반환합니다.

{"output": "aaff4a450a104cd177d28d18d7485e8cae074b7" }

JSON 데이터 조작을 위한 내장 함수

다음 함수를 사용하여 JSON 객체에서 기본적인 데이터 처리 작업을 수행할 수 있습니다.

States.JsonMerge

States.JsonMerge 내장 함수를 사용하여 두 JSON 객체를 단일 객체로 병합할 수 있습니다. 이 함수는 인수 3개를 사용합니다. 처음 두 인수는 병합하려는 JSON 객체입니다. 세 번째 인수는 false의 부울 값입니다. 이 부울 값은 심층 병합 모드가 활성화되어 있는지 여부를 결정합니다.

현재 Step Functions는 단순 병합 모드만 지원합니다. 따라서 부울 값을 false로 지정해야 합니다. 단순 모드에서 두 JSON 객체 모두에 같은 키가 있는 경우 후자 객체 키가 첫 번째 객체의 같은 키를 재정의합니다. 또한 단순 병합을 사용할 때는 JSON 객체 내에 중첩된 객체는 병합되지 않습니다.

예를 들어 States.JsonMerge 함수를 사용하여 a 키를 공유하는 다음 JSON 객체를 병합할 수 있습니다.

{
   "json1": { "a": {"a1": 1, "a2": 2}, "b": 2 },
   "json2": { "a": {"a3": 1, "a4": 2}, "c": 3 }
}

json1 및 json2 객체를 States.JsonMerge 함수의 입력으로 지정하여 병합할 수 있습니다.

"output.$": "States.JsonMerge($.json1, $.json2, false)"

States.JsonMerge에서 결과로 다음과 같은 병합된 JSON 객체를 반환합니다. 병합된 JSON 객체 output에서는 json2 객체의 a 키가 json1 객체의 a 키를 대체합니다. 또한 단순 모드에서는 중첩된 객체 병합을 지원하지 않으므로 json1 객체의 a 키에 있는 중첩된 객체는 삭제됩니다.

{
   "output": {
      "a": {"a3": 1, "a4": 2},
      "b": 2, 
      "c": 3 
   }
}

States.StringToJson

States.StringToJson 함수는 이스케이프된 JSON 문자열에 대한 참조 경로를 유일한 인수로 사용합니다.

인터프리터는 JSON 파서를 적용하고 입력의 파싱된 JSON 형식을 반환합니다. 예를 들어 이 함수를 사용하여 다음 입력 문자열을 이스케이프 처리할 수 있습니다.

{
 "escapedJsonString": "{\"foo\": \"bar\"}"
}
                

States.StringToJson 함수를 사용하고 escapedJsonString을 입력 인수로 지정합니다.

States.StringToJson($.escapedJsonString)

States.StringToJson 함수에서 다음과 같은 결과를 반환합니다.

{ "foo": "bar" }

States.JsonToString

States.JsonToString 함수는 이스케이프 처리되지 않은 문자열로 반환할 JSON 데이터가 포함된 Path라는 인수 하나만 사용합니다. 인터프리터는 Path로 지정된 데이터를 나타내는 JSON 텍스트가 포함된 문자열을 반환합니다. 예를 들어 이스케이프 처리된 값이 포함된 다음 JSON Path를 제공할 수 있습니다.

{
  "unescapedJson": {
     "foo": "bar"
  }
}

unescapedJson 내에 포함된 데이터와 함께 States.JsonToString 함수를 제공합니다.

States.JsonToString($.unescapedJson)
                

States.JsonToString 함수에서 다음 응답을 반환합니다.

{\"foo\": \"bar\"}

수학 연산을 위한 내장 함수

다음 함수를 사용하여 수학 연산을 수행할 수 있습니다.

States.MathRandom

States.MathRandom 내장 함수를 사용하여 지정된 시작 번호(포함)와 끝 번호(제외) 사이의 난수를 반환할 수 있습니다.

이 함수를 사용하여 특정 작업을 리소스 2개 사이에서 분산할 수 있습니다.

이 함수는 인수 3개를 사용합니다. 첫 번째 인수는 시작 번호이고 두 번째 인수는 끝 번호입니다. 마지막 인수는 시드 값을 제어합니다. 시드 값 인수는 선택 사항입니다. 이 함수를 동일한 시드 값과 함께 사용하면 같은 숫자가 반환됩니다.

중요

States.MathRandom 함수에서 암호로 보호되는 난수를 반환하지 않으므로 보안에 민감한 애플리케이션에는 사용하지 않는 것이 좋습니다.

입력 검증

• 시작 번호 인수와 끝 번호 인수에 정수 값을 지정해야 합니다.

  시작 번호 또는 끝 번호 인수에 정수가 아닌 값을 지정하면 Step Functions에서 가장 가까운 정수로 반올림합니다.

예를 들어 1~999 사이의 난수를 생성하려면 다음 입력값을 사용하면 됩니다.

{
   "start": 1,
   "end": 999
}

난수를 생성하려면 start 및 end 값을 States.MathRandom 함수에 제공합니다.

"random.$": "States.MathRandom($.start, $.end)"

States.MathRandom 함수에서 응답으로 다음 난수를 반환합니다.

{"random": 456 }

States.MathAdd

States.MathAdd 내장 함수를 사용하여 두 숫자의 합을 반환할 수 있습니다. 예를 들어 이 함수를 사용하여 Lambda 함수를 호출하지 않고도 루프 내에서 값을 증가시킬 수 있습니다.

입력 검증

• 모든 인수에 정수 값을 지정해야 합니다.

  인수 하나 또는 둘 다에 정수가 아닌 값을 지정하면 Step Functions에서 가장 가까운 정수로 반올림합니다.

• -2147483648~2147483647 범위의 정수 값을 지정해야 합니다.

예를 들어 다음 값을 사용하여 111에서 1을 뺄 수 있습니다.

{
   "value1": 111,
   "step": -1
}

그런 다음, States.MathAdd 함수를 사용하여 value1을 시작 값으로, step을 value1씩 증가할 값으로 정의합니다.

"value1.$": "States.MathAdd($.value1, $.step)"

States.MathAdd 함수에서 응답으로 다음 수를 반환합니다.

{"value1": 110 }

문자열 작업을 위한 내장 연산

States.StringSplit

States.StringSplit 함수를 사용하여 문자열을 값 배열로 분할할 수 있습니다. 이 함수는 인수 2개를 사용합니다. 첫 번째 인수는 문자열이고 두 번째 인수는 함수에서 문자열을 나누는 데 사용할 구분 문자입니다.

예 - 단일 구분 문자를 사용하여 입력 문자열 분할

이 예제에서는 States.StringSplit을 사용하여 쉼표로 구분된 일련의 값이 포함된 다음 inputString을 나눕니다.

{
    "inputString": "1,2,3,4,5",
    "splitter": ","
}

States.StringSplit 함수를 사용하여 inputString을 첫 번째 인수로, 구분 문자 splitter를 두 번째 인수로 정의합니다.

"array.$": "States.StringSplit($.inputString, $.splitter)"

States.StringSplit 함수에서 결과로 다음 문자열 배열을 반환합니다.

{"array":  ["1","2","3","4","5"] }

예 - 여러 구분 문자를 사용하여 입력 문자열 분할

이 예제에서는 States.StringSplit을 사용하여 여러 구분 문자가 포함된 다음 inputString을 나눕니다.

{
  "inputString": "This.is+a,test=string",
  "splitter": ".+,="
}

States.StringSplit 함수를 다음과 같이 사용합니다.

{
  "myStringArray.$": "States.StringSplit($.inputString, $.splitter)"
}

States.StringSplit 함수에서 결과로 다음 문자열 배열을 반환합니다.

{"myStringArray": [
  "This",
  "is",
  "a",
  "test",
  "string"
]}

고유 식별자 생성을 위한 내장 함수

States.UUID

States.UUID 내장 함수를 사용하여 난수로 생성된 버전 4 범용 고유 식별자(v4 UUID)를 반환할 수 있습니다. 예를 들어 이 함수를 사용하여 UUID 파라미터가 필요한 다른 AWS 서비스 또는 리소스를 호출하거나 항목을 DynamoDB 테이블에 삽입할 수 있습니다.

States.UUID 함수는 지정된 인수 없이 호출됩니다.

"uuid.$": "States.UUID()"

함수는 다음 예제와 같이 임의로 생성된 UUID를 반환합니다.

{"uuid": "ca4c1140-dcc1-40cd-ad05-7b4aa23df4a8" }

일반 연산을 위한 내장 함수

States.Format

States.Format 내장 함수를 사용하여 리터럴 값과 보간 값 모두에서 문자열을 구성할 수 있습니다. 이 함수는 인수를 하나 이상 사용합니다. 첫 번째 인수 값은 문자열이어야 하며 0개 이상의 문자 시퀀스 {} 인스턴스를 포함할 수 있습니다. 내장 간접 호출에 남아 있는 인수는 {} 발생 횟수만큼 많아야 합니다. 인터프리터는 첫 번째 인수에 정의된 문자열을 반환합니다. 이 때 각 {}는 내장 간접 호출에서 위치적으로 해당하는 인수의 값으로 대체됩니다.

예를 들어 다음과 같은 개별 name 및 template 문장의 입력 값을 사용하여 이름을 삽입할 수 있습니다.

{
 "name": "Arnav",
 "template": "Hello, my name is {}."
}

States.Format 함수를 사용하여 template 문자열과 {} 문자 대신 삽입할 문자열을 지정합니다.

States.Format('Hello, my name is {}.', $.name)

또는

States.Format($.template, $.name)

States.Format 함수는 이전 입력 중 하나를 사용하여 응답으로 완성된 문자열을 반환합니다.

Hello, my name is Arnav.

내장 함수에 예약된 문자

'{} 및 \ 문자는 내장 함수용으로 예약되어 있으며 값에 이러한 문자를 표시하려면 백슬래시('\')로 이스케이프 처리해야 합니다.

\ 문자가 이스케이프 문자로 제공되지 않고 값의 일부로 표시되어야 하는 경우에는 백슬래시로 문자를 이스케이프 처리해야 합니다. 내장 함수에서는 다음과 같은 이스케이프 처리된 문자 시퀀스가 사용됩니다.

• 리터럴 문자열 \'은 '를 나타냅니다.

• 리터럴 문자열 \{은 {를 나타냅니다.

• 리터럴 문자열 \}은 }를 나타냅니다.

• 리터럴 문자열 \\은 \를 나타냅니다.

JSON에서 문자열 리터럴 값에 포함된 백슬래시를 다른 백슬래시로 이스케이프 처리해야 합니다. JSON에 해당하는 목록은 다음과 같습니다.

• 이스케이프 처리된 문자열 \\\'은 \'를 나타냅니다.

• 이스케이프 처리된 문자열 \\\{은 \{를 나타냅니다.

• 이스케이프 처리된 문자열 \\\}은 \}를 나타냅니다.

• 이스케이프 처리된 문자열 \\\\은 \\를 나타냅니다.

참고

내장 간접 호출 문자열에서 열린 이스케이프 백슬래시 \가 발견되면 인터프리터는 런타임 오류를 반환합니다.