Delimitatori di espressioni Nozioni di base sulla lingua Operatori Funzioni consentite Schemi comuni

JSonata riferimento all'espressione per le funzioni

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

Delimitatori di espressioni

Ogni valore definito in una funzione è una costante o un'espressione, non una combinazione di entrambi. MediaTailor li distingue in base ai delimitatori.

Sintassi	Tipo	Valutazione
`https://ads.example.com/vast`	Costante	Restituito così com'è senza 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, usa la concatenazione di stringhe all'interno dell'espressione:. {%'hello ' & 'world'%}

Nozioni di base sulla lingua

Notazione a punti per la navigazione del percorso

Usa la notazione a punti per scorrere 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 `&`

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)

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: =

Utilizzate l':=operatore racchiuso tra parentesi per assegnare valori intermedi all'interno di un'espressione. Le variabili associate sono limitate alle parentesi che le racchiudono e non permangono all'esterno dell'espressione.


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

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


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

Operatori

Aritmetica

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 immessi dai parametri del giocatore e dai dati della sessione arrivano come stringhe. Utilizzali $number() per convertirli prima dei confronti numerici o dell'aritmetica. Il confronto di una stringa con un numero produce risultati inaspettati.

Confronto

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

Booleano

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 la precedenza:


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

Nota

Usa per la $not() negazione logica. Non esiste un operatore di not parole chiave.

Iscrizione (`in`)

L'inoperatore verifica se esiste un valore in un array.


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

Concatenamento (`~) >`

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

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

Conversione del tipo (3)

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

Introspezione (6)

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 è definito)	`$exists(temp.id)`	`true` o `false`
`$keys(object)`	Ottieni i nomi delle chiavi degli oggetti	`$keys(response.body)`	`["id", "name"]`
`$lookup(object, key)`	Ottieni il valore dall'oggetto in base al nome della chiave	`$lookup(response.body, 'status')`	Valore del `status` campo
`$each(object, func)`	Applica la funzione a ciascuna coppia chiave-valore di un oggetto	`$each({"a":1,"b":2}, function($v,$k){$k & '=' & $v})`	`["a=1", "b=2"]`

Numerico (7)

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)`	Arrotonda per difetto	`$floor(3.9)`	`3`
`$round(number, precision)`	Arrotondato con precisione	`$round(3.456, 2)`	`3.46`

Corda (9)

Funzione	Description	Esempio	Risultato
`$uppercase(string)`	In lettere maiuscole	`$uppercase('hello')`	`"HELLO"`
`$lowercase(string)`	In minuscolo	`$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 un pattern	`$contains(session.user_agent, 'CTV')`	`true` o `false`
`$match(string, pattern)`	Confronta la stringa con il pattern regex	`$match('abc-123', /[0-9]+/)`	`{"match": "123", ...}`
`$replace(string, pattern, replacement)`	Sostituisci il modello corrispondente	`$replace('hello', 'l', 'r')`	`"herro"`
`$join(array, separator)`	Unisci gli elementi dell'array in una stringa	`$join(['a','b','c'], ',')`	`"a,b,c"`
`$split(string, separator)`	Dividi una stringa in un array	`$split('a,b,c', ',')`	`["a", "b", "c"]`

Matrice (7)

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)`	Matrice di ordinamento	`$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]`
`$filter(array, func)`	Restituisce elementi in cui la funzione restituisce true	`$filter([1,2,3,4], function($v){$v > 2})`	`[3, 4]`
`$reduce(array, func, init)`	Riduci l'array a un singolo valore	`$reduce([1,2,3], function($prev,$val){$prev+$val}, 0)`	`6`

Booleano (1)

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

Casuale (1)

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)

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)`	Converte la stringa ISO 8601 in millisecondi	`$toMillis('2024-01-15T12:00:00.000Z')`	`1705320000000`
`$fromMillis(number)`	Converti i millisecondi in una stringa ISO 8601	`$fromMillis(1705320000000)`	`"2024-01-15T12:00:00.000Z"`

Codifica (6)

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

Usare $encodeUrlComponent() per i valori dei singoli parametri di interrogazione. Usalo $encodeUrl() solo quando devi codificare un URL completo preservandone la struttura.

Schemi comuni

Valori di riserva

Fornisci un valore predefinito quando un valore potrebbe non esistere.


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

Costruzione dinamica dell'URL

Crea un URL del server per le decisioni pubblicitarie da più input.


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

Il codice di stato verifica l'output di HTTP_REQUEST

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

I parametri del giocatore arrivano come stringhe. Convertili 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

Assegna agli spettatori i gruppi di esperimenti utilizzando$random().


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

Classificazione dei tipi di dispositivo

Classifica i dispositivi in base alla stringa dell'agente utente.


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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Creazione e gestione

Esempi di funzioni

JSonata riferimento all'espressione per le funzioni

Delimitatori di espressioni

Importante

Nozioni di base sulla lingua

Notazione a punti per la navigazione del percorso

Concatenazione di stringhe con &amp;

Espressioni condizionali (ternarie)

Associazione variabile con: =

Operatori

Aritmetica

Importante

Confronto

Booleano

Nota

Iscrizione (in)

Concatenamento (~) >

Funzioni consentite

Conversione del tipo (3)

Introspezione (6)

Numerico (7)

Corda (9)

Matrice (7)

Booleano (1)

Casuale (1)

Nota

Date/time (4)

Codifica (6)

Suggerimento

Schemi comuni

Valori di riserva

Costruzione dinamica dell'URL

Il codice di stato verifica l'output di HTTP_REQUEST

Conversione numerica dai parametri del giocatore

Importante

Suddivisione casuale del traffico

Classificazione dei tipi di dispositivo

Concatenazione di stringhe con `&`

Iscrizione (`in`)

Concatenamento (`~) >`