Delimitadores de expresiones Conceptos básicos del lenguaje Operadores Funciones permitidas Patrones comunes

Referencia de expresión JSonata para funciones

Esta página es una referencia completa sobre la sintaxis de las expresiones, los operadores y las funciones disponibles en Functions. Úsala cuando escribas expresiones para bloques de salida, campos de URL, valores de encabezado, plantillas de cuerpo y condiciones de ejecución.

Delimitadores de expresiones

Cada valor que defina en una función es una constante o una expresión, no una mezcla de ambos. MediaTailor distingue entre los dos en función de los delimitadores.

Sintaxis	Tipo	Evaluación
`https://ads.example.com/vast`	Constant	Se devolvió tal cual sin evaluación.
`{%session.client_ip%}`	Expression	Evaluado en tiempo de ejecución. El resultado reemplaza todo el valor.
`GET`	Constant	Se devuelve tal cual.
`{%'https://ads.example.com/vast?ip=' & session.client_ip%}`	Expression	Evaluado en tiempo de ejecución.

importante

Un valor es completamente una constante o completamente una expresión. No se pueden mezclar los dos en un solo valor. Por ejemplo, hello {%'world'%} no es válido. Para combinar texto estático con valores dinámicos, utilice la concatenación de cadenas dentro de la expresión:. {%'hello ' & 'world'%}

Conceptos básicos del lenguaje

Notación de puntos para la navegación por rutas

Utilice la notación de puntos para recorrer los datos de entrada. Cada punto desciende un nivel en la jerarquía de objetos.


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

Los campos que faltan se muestran null sin que se produzca ningún error:


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

Concatenación de cadenas con `&`

El & operador une dos valores de cadena. Non-string los valores se convierten en cadenas automáticamente.


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

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

Expresiones condicionales (ternarias)

Utilice el operador ternario para devolver uno de los dos valores en función de una condición.


condition ? value_if_true : value_if_false

Ejemplos:


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

Puede anidar expresiones ternarias para ramificarlas en varios sentidos:


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

`Enlace de variables con: =`

Utilice el := operador entre paréntesis para asignar valores intermedios dentro de una expresión. Las variables enlazadas se limitan a los paréntesis que las rodean y no persisten fuera de la expresión.


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

Los puntos y comas separan las declaraciones dentro de los paréntesis. La última sentencia es el valor devuelto por la expresión.


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

Operadores

Aritmético

Operador	Description (Descripción)	Ejemplo	Resultado
`+`	Suma	`5 + 3`	`8`
`-`	Resta	`10 - 4`	`6`
`*`	Multiplicación	`6 * 7`	`42`
`/`	División	`15 / 4`	`3.75`
`%`	Módulo	`17 % 5`	`2`

importante

Los valores de entrada de los parámetros del reproductor y los datos de la sesión llegan en forma de cadenas. Se utilizan $number() para convertirlos antes que en las comparaciones numéricas o aritméticas. La comparación de una cadena con un número produce resultados inesperados.

Comparación

Operador	Description (Descripción)	Ejemplo	Resultado
`=`	Igual que	`response.statusCode = 200`	`true`
`!=`	No igual que	`player_params.region != 'us-east-1'`	`true`si no us-east-1
`<`	Menor que	`avail.index < 3`	`true`si es inferior a 3
`>`	Mayor que	`$number(player_params.age) > 18`	`true`si es mayor de 18
`<=`	Menor que o igual a	`$count(items) <= 10`	`true`si tiene 10 o menos
`>=`	Mayor que o igual a	`response.statusCode >= 400`	`true`si es un estado de error

Booleano

Operador	Description (Descripción)	Ejemplo
`and`	AND lógico	`response.statusCode = 200 and $exists(response.body.id)`
`or`	OR lógico	`player_params.region = 'us-east-1' or player_params.region = 'us-west-2'`

Use paréntesis como prioridad:


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

nota

Úselo $not() para la negación lógica. No hay ningún operador de not palabras clave.

Membresía (`en`)

El in operador comprueba si existe un valor en una matriz.


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

Encadenamiento (`~) >`

El operador de encadenamiento pasa el resultado de la expresión de la izquierda como primer argumento a la función de la derecha.


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

Funciones permitidas

MediaTailor admite las siguientes funciones integradas. Cualquier función que no aparezca aquí se bloquea y provoca un error de validación al crear o actualizar una función.

Conversión de tipos (3)

Función	Description (Descripción)	Ejemplo	Resultado
`$string(value)`	Convertir a cadena	`$string(200)`	`"200"`
`$number(value)`	Convertir en número	`$number('42')`	`42`
`$boolean(value)`	Convertir a booleano	`$boolean(1)`	`true`

Introspección (4)

Función	Description (Descripción)	Ejemplo	Resultado
`$length(string)`	Longitud de cadena	`$length('hello')`	`5`
`$count(array)`	Recuento de elementos de matriz	`$count([1, 2, 3])`	`3`
`$exists(value)`	Compruebe si el valor existe (no está indefinido)	`$exists(temp.id)`	`true` o `false`
`$keys(object)`	Obtenga los nombres clave de los objetos	`$keys(response.body)`	`["id", "name"]`

Numérico (7)

Función	Description (Descripción)	Ejemplo	Resultado
`$sum(array)`	Suma de la matriz	`$sum([1, 2, 3])`	`6`
`$max(array)`	Valor máximo	`$max([10, 5, 20])`	`20`
`$min(array)`	Valor mínimo	`$min([10, 5, 20])`	`5`
`$average(array)`	Media aritmética	`$average([10, 20, 30])`	`20`
`$abs(number)`	Valor absoluto	`$abs(-7)`	`7`
`$floor(number)`	Redondea hacia abajo	`$floor(3.9)`	`3`
`$round(number, precision)`	Redondeado con precisión	`$round(3.456, 2)`	`3.46`

Cadena (7)

Función	Description (Descripción)	Ejemplo	Resultado
`$uppercase(string)`	A mayúsculas	`$uppercase('hello')`	`"HELLO"`
`$lowercase(string)`	A minúsculas	`$lowercase('Hello')`	`"hello"`
`$trim(string)`	Eliminar espacios en blanco leading/trailing	`$trim(' hi ')`	`"hi"`
`$substring(string, start, length)`	Extrae la subcadena (de base cero)	`$substring('abcdef', 2, 3)`	`"cde"`
`$contains(string, pattern)`	Compruebe si la cadena contiene un patrón	`$contains(session.user_agent, 'CTV')`	`true` o `false`
`$match(string, pattern)`	Haga coincidir la cadena con el patrón de expresiones regulares	`$match('abc-123', /[0-9]+/)`	`{"match": "123", ...}`
`$replace(string, pattern, replacement)`	Reemplace el patrón coincidente	`$replace('hello', 'l', 'r')`	`"herro"`

Matriz (5)

Función	Description (Descripción)	Ejemplo	Resultado
`$append(arr1, arr2)`	Concatenación de matrices	`$append([1, 2], [3, 4])`	`[1, 2, 3, 4]`
`$reverse(array)`	Orden inverso	`$reverse([1, 2, 3])`	`[3, 2, 1]`
`$sort(array)`	Ordenar matriz	`$sort([3, 1, 2])`	`[1, 2, 3]`
`$distinct(array)`	Eliminación de duplicados	`$distinct([1, 2, 2, 3])`	`[1, 2, 3]`
`$map(array, func)`	Aplica la función a cada elemento	`$map([1,2,3], function($v){$v*2})`	`[2, 4, 6]`

Booleano (1)

Función	Description (Descripción)	Ejemplo	Resultado
`$not(value)`	NOT lógico	`$not(false)`	`true`

Aleatorio (1)

Función	Description (Descripción)	Ejemplo	Resultado
`$random()`	Número aleatorio entre 0 (incluido) y 1 (exclusivo)	`$random() > 0.5 ? 'A' : 'B'`	`"A"` o `"B"`

nota

$random()genera un nuevo valor en cada evaluación. Si necesita el mismo valor aleatorio en varias claves de salida, vincúlelo primero a una variable:($r := $random(); ...).

Date/time (4)

Función	Description (Descripción)	Ejemplo	Resultado
`$now()`	Marca de tiempo actual como cadena ISO 8601	`$now()`	`"2024-01-15T12:00:00.000Z"`
`$millis()`	Marca de tiempo actual en milisegundos desde la época	`$millis()`	`1705320000000`
`$toMillis(string)`	Convierte la cadena ISO 8601 a milisegundos	`$toMillis('2024-01-15T12:00:00.000Z')`	`1705320000000`
`$fromMillis(number)`	Convierte milisegundos en una cadena ISO 8601	`$fromMillis(1705320000000)`	`"2024-01-15T12:00:00.000Z"`

Codificación (6)

Función	Description (Descripción)	Ejemplo
`$encodeUrl(string)`	Codificación de URL (conserva caracteres estructurales como`/`,`?`,`&`)	`$encodeUrl('https://example.com/path?q=hello world')`
`$encodeUrlComponent(string)`	La URL codifica un solo componente (codifica todos los caracteres especiales)	`$encodeUrlComponent('a&b=c')` → `"a%26b%3Dc"`
`$decodeUrl(string)`	Decodifica una cadena URL-encoded	`$decodeUrl('hello%20world')` → `"hello world"`
`$decodeUrlComponent(string)`	Decodifica un componente URL-encoded	`$decodeUrlComponent('a%26b')` → `"a&b"`
`$base64encode(string)`	Codifica en Base64	`$base64encode('hello')` → `"aGVsbG8="`
`$base64decode(string)`	Decodifica desde Base64	`$base64decode('aGVsbG8=')` → `"hello"`

sugerencia

Se utiliza $encodeUrlComponent() para valores de parámetros de consulta individuales. Úselo $encodeUrl() solo cuando necesite codificar una URL completa y, al mismo tiempo, conservar su estructura.

Patrones comunes

Valores alternativos

Indique un valor predeterminado cuando es posible que no exista un valor.


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

Construcción dinámica de URL

Cree una URL de servidor de decisiones publicitarias a partir de varias entradas.


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

El código de estado comprueba la salida de HTTP_REQUEST

Proteja los valores de salida contra los errores de HTTP.


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

Conversión numérica a partir de los parámetros del reproductor

Los parámetros del reproductor llegan en forma de cadenas. Conviértelos antes de realizar comparaciones aritméticas o numéricas.


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

importante

Si $number() recibe una cadena no numérica, retorna. undefined Combínelo con $exists() cuando el parámetro falte o no sea válido:($val := $number(player_params.max_duration); $exists($val) and $val > 30 ? 'long' : 'short').

División aleatoria del tráfico

Asigne espectadores a grupos de experimentos utilizando$random().


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

Clasificación del tipo de dispositivo

Clasifique los dispositivos en función de la cadena del agente de usuario.


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

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Crear y administrar

Ejemplos de funciones

Referencia de expresión JSonata para funciones

Delimitadores de expresiones

importante

Conceptos básicos del lenguaje

Notación de puntos para la navegación por rutas

Concatenación de cadenas con &amp;

Expresiones condicionales (ternarias)

Enlace de variables con: =

Operadores

Aritmético

importante

Comparación

Booleano

nota

Membresía (en)

Encadenamiento (~) >

Funciones permitidas

Conversión de tipos (3)

Introspección (4)

Numérico (7)

Cadena (7)

Matriz (5)

Booleano (1)

Aleatorio (1)

nota

Date/time (4)

Codificación (6)

sugerencia

Patrones comunes

Valores alternativos

Construcción dinámica de URL

El código de estado comprueba la salida de HTTP_REQUEST

Conversión numérica a partir de los parámetros del reproductor

importante

División aleatoria del tráfico

Clasificación del tipo de dispositivo

Concatenación de cadenas con `&`

`Enlace de variables con: =`

Membresía (`en`)

Encadenamiento (`~) >`