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

Riferimento all'espressione JSonata per le funzioni

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

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

Notazione a punti per la navigazione dei percorsi

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

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

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

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

L'inoperatore 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 (`~) >`

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 è 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)`	Converti in stringa	`$string(200)`	`"200"`
`$number(value)`	Converti in numero	`$number('42')`	`42`
`$boolean(value)`	Converti in booleano	`$boolean(1)`	`true`

Introspezione (4)

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)

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)

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)

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)

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

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

Valori di fallback

Fornisci un valore predefinito quando un valore potrebbe non esistere.


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

Costruzione dinamica di URL

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

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

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

Classificate i dispositivi in base alla stringa dello user agent.


{%$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

Riferimento all'espressione JSonata per le funzioni

Delimitatori di espressione

Importante

Nozioni di base sulla lingua

Notazione a punti per la navigazione dei percorsi

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 (4)

Numerico (7)

Corda (7)

Matrice (5)

Booleano (1)

Casuale (1)

Nota

Date/time (4)

Codifica (6)

Suggerimento

Schemi comuni

Valori di fallback

Costruzione dinamica di URL

Controlli del codice di stato per l'output di HTTP_REQUEST

Conversione numerica dai parametri del giocatore

Importante

Suddivisione casuale del traffico

Classificazione del tipo di dispositivo

Concatenazione di stringhe con `&`

`Associazione variabile con: =`

Iscrizione (`in`)

Concatenamento (`~) >`