기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 함수에 대한 JSONata 표현식 참조
<a name="monetization-functions-jsonata"></a>

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

## 표현식 구분 기호
<a name="monetization-functions-jsonata-delimiters"></a>

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


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

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

## 언어 기본 사항
<a name="monetization-functions-jsonata-basics"></a>

### 경로 탐색을 위한 점 표기법
<a name="monetization-functions-jsonata-dot-notation"></a>

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

```
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
```

### 와 문자열 연결 `&`
<a name="monetization-functions-jsonata-concat"></a>

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

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

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

### 조건부(3진수) 표현식
<a name="monetization-functions-jsonata-ternary"></a>

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

```
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'
```

### 를 사용한 변수 바인딩 `:=`
<a name="monetization-functions-jsonata-binding"></a>

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

```
(
  $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'
)
```

## 연산자
<a name="monetization-functions-jsonata-operators"></a>

### Arithmetic
<a name="monetization-functions-jsonata-operators-arithmetic"></a>


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

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

### 비교
<a name="monetization-functions-jsonata-operators-comparison"></a>


| 연산자 | 설명 | 예제 | 결과 | 
| --- | --- | --- | --- | 
| = | 같음 | 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 오류 상태인 경우 | 

### 부울
<a name="monetization-functions-jsonata-operators-boolean"></a>


| 연산자 | 설명 | 예제 | 
| --- | --- | --- | 
| 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`)
<a name="monetization-functions-jsonata-operators-membership"></a>

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

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

### 연결(`~>`)
<a name="monetization-functions-jsonata-operators-chaining"></a>

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

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

## 허용된 함수
<a name="monetization-functions-jsonata-allowed"></a>

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

### 유형 변환(3)
<a name="monetization-functions-jsonata-allowed-type"></a>


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

### 내부 검사(4)
<a name="monetization-functions-jsonata-allowed-introspection"></a>


| 함수 | 설명 | 예제 | 결과 | 
| --- | --- | --- | --- | 
| $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)
<a name="monetization-functions-jsonata-allowed-numeric"></a>


| 함수 | 설명 | 예제 | 결과 | 
| --- | --- | --- | --- | 
| $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)
<a name="monetization-functions-jsonata-allowed-string"></a>


| 함수 | 설명 | 예제 | 결과 | 
| --- | --- | --- | --- | 
| $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)
<a name="monetization-functions-jsonata-allowed-array"></a>


| 함수 | 설명 | 예제 | 결과 | 
| --- | --- | --- | --- | 
| $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)
<a name="monetization-functions-jsonata-allowed-boolean"></a>


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

### 임의(1)
<a name="monetization-functions-jsonata-allowed-random"></a>


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

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

### 날짜/시간(4)
<a name="monetization-functions-jsonata-allowed-datetime"></a>


| 함수 | 설명 | 예제 | 결과 | 
| --- | --- | --- | --- | 
| $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)
<a name="monetization-functions-jsonata-allowed-encoding"></a>


| 함수 | 설명 | 예제 | 
| --- | --- | --- | 
| $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()` 경우에만를 사용합니다.

## 일반적인 패턴
<a name="monetization-functions-jsonata-patterns"></a>

### 폴백 값
<a name="monetization-functions-jsonata-patterns-fallback"></a>

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

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

### 동적 URL 구성
<a name="monetization-functions-jsonata-patterns-url"></a>

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

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

### HTTP\_REQUEST 출력에 대한 상태 코드 확인
<a name="monetization-functions-jsonata-patterns-status"></a>

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

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

### 플레이어 파라미터에서 숫자 변환
<a name="monetization-functions-jsonata-patterns-numeric"></a>

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

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

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

### 임의 트래픽 분할
<a name="monetization-functions-jsonata-patterns-random"></a>

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

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

### 디바이스 유형 분류
<a name="monetization-functions-jsonata-patterns-device"></a>

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

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