Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Riferimento all'espressione JSonata per le funzioni
<a name="monetization-functions-jsonata"></a>

Questa pagina è un riferimento completo per la sintassi, gli operatori e le funzioni delle espressioni disponibili in Funzioni. Usala quando scrivi espressioni per blocchi di output, campi URL, valori di intestazione, modelli di corpo e condizioni di esecuzione.

## Delimitatori di espressione
<a name="monetization-functions-jsonata-delimiters"></a>

Ogni valore definito in una funzione è una costante o un'espressione, non una combinazione di entrambe. MediaTailor distingue tra i due in base ai delimitatori.


| Sintassi | Tipo | Valutazione | 
| --- | --- | --- | 
| https://ads.example.com/vast | Costante | Restituito così com'è senza alcuna valutazione. | 
| {%session.client\_ip%} | Expression | Valutato in fase di esecuzione. Il risultato sostituisce l'intero valore. | 
| GET | Costante | Restituito così com'è. | 
| {%'https://ads.example.com/vast?ip=' & session.client\_ip%} | Expression | Valutato in fase di esecuzione. | 

**Importante**  
Un valore è interamente una costante o interamente un'espressione. Non è possibile combinare i due valori in un unico valore. Ad esempio, `hello {%'world'%}` non è valido. Per combinare testo statico con valori dinamici, utilizzate la concatenazione di stringhe all'interno dell'espressione:. `{%'hello ' & 'world'%}`

## Nozioni di base sulla lingua
<a name="monetization-functions-jsonata-basics"></a>

### Notazione a punti per la navigazione dei percorsi
<a name="monetization-functions-jsonata-dot-notation"></a>

Usa la notazione a punti per attraversare i dati di input. Ogni punto scende di un livello nella gerarchia degli oggetti.

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

I campi mancanti vengono restituiti `null` senza generare un errore:

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

### Concatenazione di stringhe con `&amp;`
<a name="monetization-functions-jsonata-concat"></a>

L'`&`operatore unisce due valori di stringa. Non-string i valori vengono convertiti automaticamente in stringhe.

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

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

### espressioni condizionali (ternarie)
<a name="monetization-functions-jsonata-ternary"></a>

Utilizzate l'operatore ternario per restituire uno dei due valori in base a una condizione.

```
condition ? value_if_true : value_if_false
```

Esempi:

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

È possibile annidare espressioni ternarie per la ramificazione multidirezionale:

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

### `Associazione variabile con: =`
<a name="monetization-functions-jsonata-binding"></a>

Utilizzate l'`:=`operatore tra parentesi per assegnare valori intermedi all'interno di un'espressione. Le variabili associate rientrano nell'ambito delle parentesi racchiuse e non persistono all'esterno dell'espressione.

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

I punti e virgola separano le istruzioni tra parentesi. L'ultima istruzione è il valore restituito dall'espressione.

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

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

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


| Operatore | Description | Esempio | Risultato | 
| --- | --- | --- | --- | 
| \+ | Addizione | 5 \+ 3 | 8 | 
| - | Sottrazione | 10 - 4 | 6 | 
| \* | Moltiplicazione | 6 \* 7 | 42 | 
| / | Divisione | 15 / 4 | 3.75 | 
| % | Modulo | 17 % 5 | 2 | 

**Importante**  
I valori di input dei parametri del giocatore e dei dati della sessione arrivano sotto forma di stringhe. Utilizzateli `$number()` per convertirli prima dei confronti numerici o dell'aritmetica. Il confronto di una stringa con un numero produce risultati inaspettati.

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


| Operatore | Description | Esempio | Risultato | 
| --- | --- | --- | --- | 
| = | Equal to | response.statusCode = 200 | true | 
| \!= | Non uguale a | player\_params.region \!= 'us-east-1' | truese non us-east-1 | 
| < | Less than | avail.index < 3 | truese inferiore a 3 | 
| > | Greater than | $number(player\_params.age) > 18 | truese più di 18 anni | 
| <= | Minore di o uguale a | $count(items) <= 10 | truese 10 o meno | 
| >= | Maggiore di o uguale a | response.statusCode >= 400 | truese lo stato di errore | 

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


| Operatore | Description | Esempio | 
| --- | --- | --- | 
| and | AND logico | response.statusCode = 200 and $exists(response.body.id) | 
| or | OR logico | player\_params.region = 'us-east-1' or player\_params.region = 'us-west-2' | 

Usa le parentesi per avere la precedenza:

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

**Nota**  
Utilizzare per la `$not()` negazione logica. Non esiste un operatore di `not` parole chiave.

### Iscrizione (`in`)
<a name="monetization-functions-jsonata-operators-membership"></a>

L'`in`operatore verifica se un valore esiste in un array.

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

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

L'operatore di concatenamento passa il risultato dell'espressione a sinistra come primo argomento alla funzione a destra.

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

## Funzioni consentite
<a name="monetization-functions-jsonata-allowed"></a>

MediaTailor supporta le seguenti funzioni integrate. Qualsiasi funzione non elencata qui è bloccata e causa un errore di convalida quando si crea o si aggiorna una funzione.

### Conversione del tipo (3)
<a name="monetization-functions-jsonata-allowed-type"></a>


| Funzione | Description | Esempio | Risultato | 
| --- | --- | --- | --- | 
| $string(value) | Converti in stringa | $string(200) | "200" | 
| $number(value) | Converti in numero | $number('42') | 42 | 
| $boolean(value) | Converti in booleano | $boolean(1) | true | 

### Introspezione (4)
<a name="monetization-functions-jsonata-allowed-introspection"></a>


| Funzione | Description | Esempio | Risultato | 
| --- | --- | --- | --- | 
| $length(string) | Lunghezza delle stringhe | $length('hello') | 5 | 
| $count(array) | Conteggio degli elementi dell'array | $count([1, 2, 3]) | 3 | 
| $exists(value) | Controlla se il valore esiste (non è indefinito) | $exists(temp.id) | true o false | 
| $keys(object) | Ottieni i nomi delle chiavi degli oggetti | $keys(response.body) | ["id", "name"] | 

### Numerico (7)
<a name="monetization-functions-jsonata-allowed-numeric"></a>


| Funzione | Description | Esempio | Risultato | 
| --- | --- | --- | --- | 
| $sum(array) | Somma della matrice | $sum([1, 2, 3]) | 6 | 
| $max(array) | Valore massimo | $max([10, 5, 20]) | 20 | 
| $min(array) | Valore minimo | $min([10, 5, 20]) | 5 | 
| $average(array) | Media aritmetica | $average([10, 20, 30]) | 20 | 
| $abs(number) | Valore assoluto | $abs(-7) | 7 | 
| $floor(number) | Arrotondare | $floor(3.9) | 3 | 
| $round(number, precision) | Arrotondato alla precisione | $round(3.456, 2) | 3.46 | 

### Corda (7)
<a name="monetization-functions-jsonata-allowed-string"></a>


| Funzione | Description | Esempio | Risultato | 
| --- | --- | --- | --- | 
| $uppercase(string) | Verso le lettere maiuscole | $uppercase('hello') | "HELLO" | 
| $lowercase(string) | In lettere minuscole | $lowercase('Hello') | "hello" | 
| $trim(string) | Rimuovi gli spazi bianchi leading/trailing  | $trim(' hi ') | "hi" | 
| $substring(string, start, length) | Estrai la sottostringa (a base zero) | $substring('abcdef', 2, 3) | "cde" | 
| $contains(string, pattern) | Controlla se la stringa contiene uno schema | $contains(session.user\_agent, 'CTV') | true o false | 
| $match(string, pattern) | Abbina la stringa al modello regex | $match('abc-123', /[0-9]\+/) | {"match": "123", ...} | 
| $replace(string, pattern, replacement) | Sostituisci il modello corrispondente | $replace('hello', 'l', 'r') | "herro" | 

### Matrice (5)
<a name="monetization-functions-jsonata-allowed-array"></a>


| Funzione | Description | Esempio | Risultato | 
| --- | --- | --- | --- | 
| $append(arr1, arr2) | Concatena matrici | $append([1, 2], [3, 4]) | [1, 2, 3, 4] | 
| $reverse(array) | Ordine inverso | $reverse([1, 2, 3]) | [3, 2, 1] | 
| $sort(array) | Ordina matrice | $sort([3, 1, 2]) | [1, 2, 3] | 
| $distinct(array) | Rimozione dei duplicati | $distinct([1, 2, 2, 3]) | [1, 2, 3] | 
| $map(array, func) | Applica la funzione a ciascun elemento | $map([1,2,3], function($v){$v\*2}) | [2, 4, 6] | 

### Booleano (1)
<a name="monetization-functions-jsonata-allowed-boolean"></a>


| Funzione | Description | Esempio | Risultato | 
| --- | --- | --- | --- | 
| $not(value) | NOT logico | $not(false) | true | 

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


| Funzione | Description | Esempio | Risultato | 
| --- | --- | --- | --- | 
| $random() | Numero casuale compreso tra 0 (incluso) e 1 (esclusivo) | $random() > 0.5 ? 'A' : 'B' | "A" o "B" | 

**Nota**  
`$random()`genera un nuovo valore per ogni valutazione. Se hai bisogno dello stesso valore casuale in più chiavi di output, associalo prima a una variabile:`($r := $random(); ...)`.

### Date/time (4)
<a name="monetization-functions-jsonata-allowed-datetime"></a>


| Funzione | Description | Esempio | Risultato | 
| --- | --- | --- | --- | 
| $now() | Timestamp corrente come stringa ISO 8601 | $now() | "2024-01-15T12:00:00.000Z" | 
| $millis() | Timestamp corrente in millisecondi dall'epoca | $millis() | 1705320000000 | 
| $toMillis(string) | Converti la stringa ISO 8601 in millisecondi | $toMillis('2024-01-15T12:00:00.000Z') | 1705320000000 | 
| $fromMillis(number) | Converti millisecondi in una stringa ISO 8601 | $fromMillis(1705320000000) | "2024-01-15T12:00:00.000Z" | 

### Codifica (6)
<a name="monetization-functions-jsonata-allowed-encoding"></a>


| Funzione | Description | Esempio | 
| --- | --- | --- | 
| $encodeUrl(string) | Codifica URL (conserva caratteri strutturali come/,,) ? & | $encodeUrl('https://example.com/path?q=hello world') | 
| $encodeUrlComponent(string) | L'URL codifica un singolo componente (codifica tutti i caratteri speciali) | $encodeUrlComponent('a&b=c') → "a%26b%3Dc" | 
| $decodeUrl(string) | Decodifica una stringa URL-encoded  | $decodeUrl('hello%20world') → "hello world" | 
| $decodeUrlComponent(string) | Decodifica un componente URL-encoded  | $decodeUrlComponent('a%26b') → "a&b" | 
| $base64encode(string) | Codifica in Base64 | $base64encode('hello') → "aGVsbG8=" | 
| $base64decode(string) | Decodifica da Base64 | $base64decode('aGVsbG8=') → "hello" | 

**Suggerimento**  
Utilizzare `$encodeUrlComponent()` per i valori dei singoli parametri di interrogazione. `$encodeUrl()`Utilizzatelo solo quando è necessario codificare un URL completo preservandone la struttura.

## Schemi comuni
<a name="monetization-functions-jsonata-patterns"></a>

### Valori di fallback
<a name="monetization-functions-jsonata-patterns-fallback"></a>

Fornisci un valore predefinito quando un valore potrebbe non esistere.

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

### Costruzione dinamica di URL
<a name="monetization-functions-jsonata-patterns-url"></a>

Crea un URL del server di decisione pubblicitaria partendo da più input.

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

### Controlli del codice di stato per l'output di HTTP\_REQUEST
<a name="monetization-functions-jsonata-patterns-status"></a>

Proteggi i valori di output dagli errori HTTP.

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

### Conversione numerica dai parametri del giocatore
<a name="monetization-functions-jsonata-patterns-numeric"></a>

I parametri del giocatore arrivano sotto forma di stringhe. Convertiteli prima dei confronti aritmetici o numerici.

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

**Importante**  
Se `$number()` riceve una stringa non numerica, restituisce. `undefined` Combinalo con `$exists()` quando il parametro potrebbe essere mancante o non valido:. `($val := $number(player_params.max_duration); $exists($val) and $val > 30 ? 'long' : 'short')`

### Suddivisione casuale del traffico
<a name="monetization-functions-jsonata-patterns-random"></a>

Assegna gli spettatori ai gruppi di esperimenti utilizzando. `$random()`

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

### Classificazione del tipo di dispositivo
<a name="monetization-functions-jsonata-patterns-device"></a>

Classificate i dispositivi in base alla stringa dello user agent.

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