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

JSONata referencia de expresiones para funciones

Esta página es una referencia completa para la sintaxis de expresiones, los operadores y las funciones disponibles en Functions. Utilícela cuando escriba 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 combinación de ambos. MediaTailor distingue entre los dos basándose en los delimitadores.

Sintaxis	Tipo	Evaluación
`https://ads.example.com/vast`	Constant	Se devuelve 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 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 devuelven null sin generar 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 tienen un alcance hasta los paréntesis adjuntos y no permanecen fuera de la expresión.


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

Los puntos y comas separan las declaraciones entre 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 jugador y los datos de la sesión llegan en forma de cadenas. Utilízalos $number() para convertirlos antes de realizar 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 es 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'`

Utilice paréntesis para dar prioridad:


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

nota

Utilícelo $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í está bloqueada 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 en cadena	`$string(200)`	`"200"`
`$number(value)`	Convertir en número	`$number('42')`	`42`
`$boolean(value)`	Convertir a booleano	`$boolean(1)`	`true`

Introspección (6)

Función	Description (Descripción)	Ejemplo	Resultado
`$length(string)`	Longitud de cadena	`$length('hello')`	`5`
`$count(array)`	Recuento de elementos de la matriz	`$count([1, 2, 3])`	`3`
`$exists(value)`	Compruebe si el valor existe (no es indefinido)	`$exists(temp.id)`	`true` o `false`
`$keys(object)`	Obtenga los nombres de las claves de los objetos	`$keys(response.body)`	`["id", "name"]`
`$lookup(object, key)`	Obtenga el valor del objeto por el nombre de la clave	`$lookup(response.body, 'status')`	Valor del `status` campo
`$each(object, func)`	Aplica la función a cada par clave-valor de un objeto	`$each({"a":1,"b":2}, function($v,$k){$k & '=' & $v})`	`["a=1", "b=2"]`

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)`	Redondear con precisión	`$round(3.456, 2)`	`3.46`

Cuerda (9)

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)`	Extraer la subcadena (basada en 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)`	Compara la cadena con el patrón de expresiones regulares	`$match('abc-123', /[0-9]+/)`	`{"match": "123", ...}`
`$replace(string, pattern, replacement)`	Reemplazar el patrón coincidente	`$replace('hello', 'l', 'r')`	`"herro"`
`$join(array, separator)`	Une los elementos de la matriz en una cadena	`$join(['a','b','c'], ',')`	`"a,b,c"`
`$split(string, separator)`	Divide una cadena en una matriz	`$split('a,b,c', ',')`	`["a", "b", "c"]`

Matriz (7)

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]`
`$filter(array, func)`	Devuelve los elementos en los que la función devuelve el valor verdadero	`$filter([1,2,3,4], function($v){$v > 2})`	`[3, 4]`
`$reduce(array, func, init)`	Reduce la matriz a un solo valor	`$reduce([1,2,3], function($prev,$val){$prev+$val}, 0)`	`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, primero vincúlelo 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 en 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)`	Decodificar una cadena URL-encoded	`$decodeUrl('hello%20world')` → `"hello world"`
`$decodeUrlComponent(string)`	Decodificar un componente URL-encoded	`$decodeUrlComponent('a%26b')` → `"a&b"`
`$base64encode(string)`	Codifica en Base64	`$base64encode('hello')` → `"aGVsbG8="`
`$base64decode(string)`	Decodificar desde Base64	`$base64decode('aGVsbG8=')` → `"hello"`

sugerencia

Se usa $encodeUrlComponent() para valores de parámetros de consulta individuales. $encodeUrl()Úselo solo cuando necesite codificar una URL completa sin perder su estructura.

Patrones comunes

Valores alternativos

Proporcione 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

Crea 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, la devuelve. 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 de tráfico aleatoria

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 de tipos de dispositivos

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

Creación y administración

Ejemplos de funciones

JSONata referencia de expresiones 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 (6)

Numérico (7)

Cuerda (9)

Matriz (7)

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 de tráfico aleatoria

Clasificación de tipos de dispositivos

Concatenación de cadenas con `&`

Membresía (`en`)

Encadenamiento (`~) >`