함수에 대한 JSONata 표현식 참조

이 페이지는 함수에서 사용할 수 있는 표현식 구문, 연산자 및 함수에 대한 전체 참조입니다. 출력 블록, URL 필드, 헤더 값, 본문 템플릿 및 실행 조건에 대한 표현식을 작성할 때 사용합니다.

표현식 구분 기호

함수에서 정의하는 모든 값은 상수 또는 표현식이며 둘 다의 혼합이 아닙니다. MediaTailor는 구분 기호를 기준으로 둘을 구분합니다.

구문	유형	평가
`https://ads.example.com/vast`	상수	평가 없이 있는 그대로 반환됩니다.
`{%session.client_ip%}`	표현식	런타임 시 평가됩니다. 결과는 전체 값을 대체합니다.
`GET`	상수	있는 그대로 반환됩니다.
`{%'https://ads.example.com/vast?ip=' & session.client_ip%}`	표현식	런타임 시 평가됩니다.

중요

값은 완전히 상수이거나 완전히 표현식입니다. 두 값을 단일 값으로 혼합할 수 없습니다. 예를 들어, hello {%'world'%}은 유효하지 않습니다. 정적 텍스트를 동적 값과 결합하려면 표현식 내에서 문자열 연결을 사용합니다{%'hello ' & 'world'%}.

언어 기본 사항

경로 탐색을 위한 점 표기법

점 표기법을 사용하여 입력 데이터를 통과합니다. 각 점은 객체 계층 구조로 한 수준 내려갑니다.


session.client_ip              → the viewer's IP address
response.body.envelope         → a field inside a parsed JSON response
player_params.campaign_id      → a player parameter

누락된 필드는 오류를 발생null시키지 않고 반환됩니다.


temp.nonExistent               → null
temp.nonExistent.deeply.nested → null

와 문자열 연결 `&`

& 연산자는 두 문자열 값을 조인합니다. 비문자열 값은 자동으로 문자열로 변환됩니다.


'https://ads.example.com/vast?ip=' & session.client_ip
→ "https://ads.example.com/vast?ip=192.0.2.1"

'duration=' & 30
→ "duration=30"

조건부(3진수) 표현식

삼원 연산자를 사용하여 조건에 따라 두 값 중 하나를 반환합니다.


condition ? value_if_true : value_if_false

예시:


$exists(player_params.env) ? player_params.env : 'prod'
response.statusCode = 200 ? response.body.id : 'unknown'
$random() > 0.5 ? 'groupA' : 'groupB'

다방향 분기를 위해 삼원 표현식을 중첩할 수 있습니다.


$contains(session.user_agent, 'CTV') ? 'ctv'
  : $contains(session.user_agent, 'Mobile') ? 'mobile'
  : 'desktop'

를 사용한 변수 바인딩 `:=`

괄호 안의 := 연산자를 사용하여 표현식 내에서 중간 값을 할당합니다. 바인딩 변수는 묶는 괄호로 범위가 지정되며 표현식 외부에서 지속되지 않습니다.


(
  $base := 'https://ads.example.com';
  $base & '/vast?ip=' & session.client_ip
)

세미콜론은 괄호 안에 문을 구분합니다. 마지막 문은 표현식의 반환 값입니다.


(
  $code := response.statusCode;
  $code != null and $code >= 200 and $code < 300
    ? response.body.value
    : 'fallback'
)

연산자

Arithmetic

연산자	설명	예제	결과
`+`	덧셈	`5 + 3`	`8`
`-`	뺄셈	`10 - 4`	`6`
`*`	곱셈	`6 * 7`	`42`
`/`	나눗셈	`15 / 4`	`3.75`
`%`	모듈로	`17 % 5`	`2`

중요

플레이어 파라미터 및 세션 데이터의 입력 값은 문자열로 도착합니다. $number()를 사용하여 숫자 비교 또는 산술 전에 변환합니다. 문자열을 숫자와 비교하면 예상치 못한 결과가 발생합니다.

비교

연산자	설명	예제	결과
`=`	같음	`response.statusCode = 200`	`true`
`!=`	같지 않음	`player_params.region != 'us-east-1'`	`true` us-east-1이 아닌 경우
`<`	보다 작음	`avail.index < 3`	`true` 3 미만인 경우
`>`	보다 큼	`$number(player_params.age) > 18`	`true` 18세를 초과하는 경우
`<=`	작거나 같음	`$count(items) <= 10`	`true` 10 이하인 경우
`>=`	크거나 같음	`response.statusCode >= 400`	`true` 오류 상태인 경우

부울

연산자	설명	예제
`and`	Logical AND	`response.statusCode = 200 and $exists(response.body.id)`
`or`	Logical OR	`player_params.region = 'us-east-1' or player_params.region = 'us-west-2'`

우선 순위에는 괄호를 사용합니다.


score > 0.5 and (tier = 'premium' or tier = 'gold')

참고

논리적 부정$not()에 사용합니다. not 키워드 연산자는 없습니다.

멤버십(`in`)

연in산자는 값이 배열에 존재하는지 테스트합니다.


'premium' in segments     → true if segments contains 'premium'
player_params.region in ['us-east-1', 'us-west-2']  → true

연결(`~>`)

체인 연산자는 왼쪽 표현식의 결과를 오른쪽의 함수에 첫 번째 인수로 전달합니다.


session.user_agent ~> $lowercase ~> $trim
→ equivalent to $trim($lowercase(session.user_agent))

허용된 함수

MediaTailor는 다음과 같은 내장 함수를 지원합니다. 여기에 나열되지 않은 모든 함수는 차단되며 함수를 생성하거나 업데이트할 때 검증 오류가 발생합니다.

유형 변환(3)

함수	설명	예제	결과
`$string(value)`	문자열로 변환	`$string(200)`	`"200"`
`$number(value)`	숫자로 변환	`$number('42')`	`42`
`$boolean(value)`	부울로 변환	`$boolean(1)`	`true`

내부 검사(4)

함수	설명	예제	결과
`$length(string)`	문자열 길이	`$length('hello')`	`5`
`$count(array)`	배열 요소 수	`$count([1, 2, 3])`	`3`
`$exists(value)`	값이 존재하는지 확인(정의되지 않음)	`$exists(temp.id)`	`true` 또는 `false`
`$keys(object)`	객체 키 이름 가져오기	`$keys(response.body)`	`["id", "name"]`

숫자(7)

함수	설명	예제	결과
`$sum(array)`	배열의 합계	`$sum([1, 2, 3])`	`6`
`$max(array)`	최대값	`$max([10, 5, 20])`	`20`
`$min(array)`	최소값	`$min([10, 5, 20])`	`5`
`$average(array)`	산술 평균	`$average([10, 20, 30])`	`20`
`$abs(number)`	절대값	`$abs(-7)`	`7`
`$floor(number)`	반내림	`$floor(3.9)`	`3`
`$round(number, precision)`	정밀도로 반올림	`$round(3.456, 2)`	`3.46`

문자열(7)

함수	설명	예제	결과
`$uppercase(string)`	대문자로	`$uppercase('hello')`	`"HELLO"`
`$lowercase(string)`	소문자로 설정하려면	`$lowercase('Hello')`	`"hello"`
`$trim(string)`	선행/후행 공백 제거	`$trim(' hi ')`	`"hi"`
`$substring(string, start, length)`	하위 문자열 추출(0 기반)	`$substring('abcdef', 2, 3)`	`"cde"`
`$contains(string, pattern)`	문자열에 패턴이 포함되어 있는지 확인	`$contains(session.user_agent, 'CTV')`	`true` 또는 `false`
`$match(string, pattern)`	정규식 패턴과 문자열 일치	`$match('abc-123', /[0-9]+/)`	`{"match": "123", ...}`
`$replace(string, pattern, replacement)`	일치하는 패턴 바꾸기	`$replace('hello', 'l', 'r')`	`"herro"`

배열(5)

함수	설명	예제	결과
`$append(arr1, arr2)`	배열 연결	`$append([1, 2], [3, 4])`	`[1, 2, 3, 4]`
`$reverse(array)`	역순	`$reverse([1, 2, 3])`	`[3, 2, 1]`
`$sort(array)`	배열 정렬	`$sort([3, 1, 2])`	`[1, 2, 3]`
`$distinct(array)`	중복값 제거	`$distinct([1, 2, 2, 3])`	`[1, 2, 3]`
`$map(array, func)`	각 요소에 함수 적용	`$map([1,2,3], function($v){$v*2})`	`[2, 4, 6]`

부울(1)

함수	설명	예제	결과
`$not(value)`	논리적 NOT	`$not(false)`	`true`

임의(1)

함수	설명	예제	결과
`$random()`	0(포함)에서 1(제외) 사이의 난수	`$random() > 0.5 ? 'A' : 'B'`	`"A"` 또는 `"B"`

참고

$random()는 각 평가에 대해 새 값을 생성합니다. 여러 출력 키에 동일한 임의 값이 필요한 경우 먼저 변수에 바인딩합니다($r := $random(); ...).

날짜/시간(4)

함수	설명	예제	결과
`$now()`	ISO 8601 문자열로서의 현재 타임스탬프	`$now()`	`"2024-01-15T12:00:00.000Z"`
`$millis()`	epoch 이후 밀리초 단위의 현재 타임스탬프	`$millis()`	`1705320000000`
`$toMillis(string)`	ISO 8601 문자열을 밀리초로 변환	`$toMillis('2024-01-15T12:00:00.000Z')`	`1705320000000`
`$fromMillis(number)`	밀리초를 ISO 8601 문자열로 변환	`$fromMillis(1705320000000)`	`"2024-01-15T12:00:00.000Z"`

인코딩(6)

함수	설명	예제
`$encodeUrl(string)`	URL 인코딩(, `/`, `?`와 같은 구조 문자 보존`&`)	`$encodeUrl('https://example.com/path?q=hello world')`
`$encodeUrlComponent(string)`	단일 구성 요소 URL 인코딩(모든 특수 문자 인코딩)	`$encodeUrlComponent('a&b=c')` → `"a%26b%3Dc"`
`$decodeUrl(string)`	URL 인코딩 문자열 디코딩	`$decodeUrl('hello%20world')` → `"hello world"`
`$decodeUrlComponent(string)`	URL 인코딩 구성 요소 디코딩	`$decodeUrlComponent('a%26b')` → `"a&b"`
`$base64encode(string)`	Base64로 인코딩	`$base64encode('hello')` → `"aGVsbG8="`
`$base64decode(string)`	Base64에서 디코딩	`$base64decode('aGVsbG8=')` → `"hello"`

작은 정보

개별 쿼리 파라미터 값에 $encodeUrlComponent()를 사용합니다. 구조를 유지하면서 전체 URL을 인코딩해야 하는 $encodeUrl() 경우에만를 사용합니다.

일반적인 패턴

폴백 값

값이 없을 때 기본값을 제공합니다.


{%$exists(player_params.region) ? player_params.region : 'us-east-1'%}

동적 URL 구성

여러 입력에서 광고 결정 서버 URL을 빌드합니다.


{%'https://ads.example.com/v1/vast?ip=' & $encodeUrlComponent(session.client_ip) & '&ua=' & $encodeUrlComponent(session.user_agent) & '&sid=' & session.id%}

HTTP_REQUEST 출력에 대한 상태 코드 확인

HTTP 실패에 대해 출력 값을 보호합니다.


{%response.statusCode != null and response.statusCode = 200 ? response.body.envelope : 'default-envelope'%}

플레이어 파라미터에서 숫자 변환

플레이어 파라미터는 문자열로 도착합니다. 산술 또는 숫자 비교 전에 변환합니다.


{%$number(player_params.max_duration) > 30 ? 'long' : 'short'%}

중요

가 숫자가 아닌 문자열을 $number() 수신하면를 반환합니다undefined. 파라미터가 누락되거나 유효하지 않은 $exists() 경우와 결합합니다($val := $number(player_params.max_duration); $exists($val) and $val > 30 ? 'long' : 'short').

임의 트래픽 분할

를 사용하여 실험 그룹에 뷰어를 할당합니다$random().


{%$random() > 0.5 ? 'https://ads.example.com/v1/vast-a' : 'https://ads.example.com/v1/vast-b'%}

디바이스 유형 분류

사용자 에이전트 문자열을 기준으로 디바이스를 분류합니다.


{%$contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop'%}

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

생성 및 관리

함수 예제