Délimiteurs d'expressions Bases de la langue Opérateurs Fonctions autorisées Schémas courants

Référence d'expression JSonata pour les fonctions

Cette page est une référence complète pour la syntaxe des expressions, les opérateurs et les fonctions disponibles dans Functions. Utilisez-le lorsque vous écrivez des expressions pour des blocs de sortie, des champs d'URL, des valeurs d'en-tête, des modèles de corps et des conditions d'exécution.

Délimiteurs d'expressions

Chaque valeur que vous définissez dans une fonction est une constante ou une expression, et non un mélange des deux. MediaTailor fait la distinction entre les deux à l'aide de délimiteurs.

Syntaxe	Type	Évaluation
`https://ads.example.com/vast`	Constant	Renvoyé tel quel sans évaluation.
`{%session.client_ip%}`	Expression	Évalué au moment de l'exécution. Le résultat remplace la valeur entière.
`GET`	Constant	Renvoyé tel quel.
`{%'https://ads.example.com/vast?ip=' & session.client_ip%}`	Expression	Évalué au moment de l'exécution.

Important

Une valeur est soit entièrement une constante, soit entièrement une expression. Vous ne pouvez pas mélanger les deux en une seule valeur. Par exemple, hello {%'world'%} n’est pas valide. Pour associer du texte statique à des valeurs dynamiques, utilisez la concaténation de chaînes dans l'expression :. {%'hello ' & 'world'%}

Bases de la langue

Notation par points pour la navigation sur le chemin

Utilisez la notation par points pour parcourir les données d'entrée. Chaque point descend d'un niveau dans la hiérarchie des objets.


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

Les champs manquants sont null renvoyés sans générer d'erreur :


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

Concaténation de chaînes avec `&`

L'&opérateur joint deux valeurs de chaîne. Non-string les valeurs sont automatiquement converties en chaînes.


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

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

Expressions conditionnelles (ternaires)

Utilisez l'opérateur ternaire pour renvoyer l'une des deux valeurs en fonction d'une condition.


condition ? value_if_true : value_if_false

Exemples :


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

Vous pouvez imbriquer des expressions ternaires pour le branchement multidirectionnel :


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

Liaison de variables avec `: =`

Utilisez l':=opérateur entre parenthèses pour attribuer des valeurs intermédiaires dans une expression. Les variables liées sont limitées aux parenthèses qui les entourent et ne persistent pas en dehors de l'expression.


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

Des points-virgules séparent les instructions entre parenthèses. La dernière instruction est la valeur renvoyée par l'expression.


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

Opérateurs

Arithmétique

Opérateur	Description	Exemple	Résultat
`+`	Addition	`5 + 3`	`8`
`-`	Soustraction	`10 - 4`	`6`
`*`	Multiplication	`6 * 7`	`42`
`/`	Division	`15 / 4`	`3.75`
`%`	Modulo	`17 % 5`	`2`

Important

Les valeurs d'entrée provenant des paramètres du joueur et des données de session arrivent sous forme de chaînes. Utilisez-le $number() pour les convertir avant les comparaisons numériques ou arithmétiques. La comparaison d'une chaîne à un nombre produit des résultats inattendus.

Comparison (Comparaison)

Opérateur	Description	Exemple	Résultat
`=`	Egal à	`response.statusCode = 200`	`true`
`!=`	Non égal à	`player_params.region != 'us-east-1'`	`true`si ce n'est pas us-east-1
`<`	Inférieur à	`avail.index < 3`	`true`si inférieur à 3
`>`	Supérieur à	`$number(player_params.age) > 18`	`true`si vous avez plus de 18 ans
`<=`	Inférieur ou égal à	`$count(items) <= 10`	`true`si 10 ou moins
`>=`	Supérieur ou égal à	`response.statusCode >= 400`	`true`en cas d'état d'erreur

Booléen

Opérateur	Description	Exemple
`and`	ET logique	`response.statusCode = 200 and $exists(response.body.id)`
`or`	OU logique	`player_params.region = 'us-east-1' or player_params.region = 'us-west-2'`

Utilisez des parenthèses pour la priorité :


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

Note

À utiliser $not() pour une négation logique. Il n'existe aucun opérateur de not mot clé.

Adhésion (`en`)

L'inopérateur teste si une valeur existe dans un tableau.


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

Enchaînement (`~ >`)

L'opérateur de chaînage transmet le résultat de l'expression de gauche comme premier argument à la fonction de droite.


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

Fonctions autorisées

MediaTailor prend en charge les fonctions intégrées suivantes. Toute fonction non répertoriée ici est bloquée et provoque une erreur de validation lorsque vous créez ou mettez à jour une fonction.

Conversion de type (3)

Fonction	Description	Exemple	Résultat
`$string(value)`	Convertir en chaîne	`$string(200)`	`"200"`
`$number(value)`	Convertir en nombre	`$number('42')`	`42`
`$boolean(value)`	Convertir en booléen	`$boolean(1)`	`true`

Introspection (4)

Fonction	Description	Exemple	Résultat
`$length(string)`	String length	`$length('hello')`	`5`
`$count(array)`	Nombre d'éléments du tableau	`$count([1, 2, 3])`	`3`
`$exists(value)`	Vérifiez si la valeur existe (non indéfinie)	`$exists(temp.id)`	`true` ou `false`
`$keys(object)`	Obtenir les noms des clés des objets	`$keys(response.body)`	`["id", "name"]`

Numérique (7)

Fonction	Description	Exemple	Résultat
`$sum(array)`	Somme du tableau	`$sum([1, 2, 3])`	`6`
`$max(array)`	Valeur maximale	`$max([10, 5, 20])`	`20`
`$min(array)`	Valeur minimale	`$min([10, 5, 20])`	`5`
`$average(array)`	Moyenne arithmétique	`$average([10, 20, 30])`	`20`
`$abs(number)`	Valeur absolue	`$abs(-7)`	`7`
`$floor(number)`	Arrondir vers le bas	`$floor(3.9)`	`3`
`$round(number, precision)`	Du rond à la précision	`$round(3.456, 2)`	`3.46`

Corde (7)

Fonction	Description	Exemple	Résultat
`$uppercase(string)`	Vers les majuscules	`$uppercase('hello')`	`"HELLO"`
`$lowercase(string)`	Vers les minuscules	`$lowercase('Hello')`	`"hello"`
`$trim(string)`	Supprimer les espaces leading/trailing blancs	`$trim(' hi ')`	`"hi"`
`$substring(string, start, length)`	Extraire une sous-chaîne (base zéro)	`$substring('abcdef', 2, 3)`	`"cde"`
`$contains(string, pattern)`	Vérifiez si la chaîne contient un motif	`$contains(session.user_agent, 'CTV')`	`true` ou `false`
`$match(string, pattern)`	Faire correspondre la chaîne au modèle regex	`$match('abc-123', /[0-9]+/)`	`{"match": "123", ...}`
`$replace(string, pattern, replacement)`	Remplacer le modèle correspondant	`$replace('hello', 'l', 'r')`	`"herro"`

Réseau (5)

Fonction	Description	Exemple	Résultat
`$append(arr1, arr2)`	Concaténation de tableaux	`$append([1, 2], [3, 4])`	`[1, 2, 3, 4]`
`$reverse(array)`	Ordre inversé	`$reverse([1, 2, 3])`	`[3, 2, 1]`
`$sort(array)`	Tableau de tri	`$sort([3, 1, 2])`	`[1, 2, 3]`
`$distinct(array)`	Suppression des doublons	`$distinct([1, 2, 2, 3])`	`[1, 2, 3]`
`$map(array, func)`	Appliquer une fonction à chaque élément	`$map([1,2,3], function($v){$v*2})`	`[2, 4, 6]`

Booléen (1)

Fonction	Description	Exemple	Résultat
`$not(value)`	Logique : NON	`$not(false)`	`true`

Aléatoire (1)

Fonction	Description	Exemple	Résultat
`$random()`	Nombre aléatoire compris entre 0 (inclus) et 1 (exclusif)	`$random() > 0.5 ? 'A' : 'B'`	`"A"` ou `"B"`

Note

$random()génère une nouvelle valeur à chaque évaluation. Si vous avez besoin de la même valeur aléatoire dans plusieurs clés de sortie, liez-la d'abord à une variable :($r := $random(); ...).

Date/time (4)

Fonction	Description	Exemple	Résultat
`$now()`	Horodatage actuel sous forme de chaîne ISO 8601	`$now()`	`"2024-01-15T12:00:00.000Z"`
`$millis()`	Horodatage actuel en millisecondes depuis Epoch	`$millis()`	`1705320000000`
`$toMillis(string)`	Convertir une chaîne ISO 8601 en millisecondes	`$toMillis('2024-01-15T12:00:00.000Z')`	`1705320000000`
`$fromMillis(number)`	Convertir les millisecondes en chaîne ISO 8601	`$fromMillis(1705320000000)`	`"2024-01-15T12:00:00.000Z"`

Encodage (6)

Fonction	Description	Exemple
`$encodeUrl(string)`	Encodage d'URL (préserve les caractères structurels tels que`/`,`?`,`&`)	`$encodeUrl('https://example.com/path?q=hello world')`
`$encodeUrlComponent(string)`	Encode par URL un seul composant (code tous les caractères spéciaux)	`$encodeUrlComponent('a&b=c')` → `"a%26b%3Dc"`
`$decodeUrl(string)`	Décoder une chaîne URL-encoded	`$decodeUrl('hello%20world')` → `"hello world"`
`$decodeUrlComponent(string)`	Décoder un composant URL-encoded	`$decodeUrlComponent('a%26b')` → `"a&b"`
`$base64encode(string)`	Encoder en Base64	`$base64encode('hello')` → `"aGVsbG8="`
`$base64decode(string)`	Décoder depuis Base64	`$base64decode('aGVsbG8=')` → `"hello"`

Astuce

À utiliser $encodeUrlComponent() pour les valeurs de paramètres de requête individuels. À utiliser $encodeUrl() uniquement lorsque vous devez encoder une URL complète tout en préservant sa structure.

Schémas courants

Valeurs de repli

Indiquez une valeur par défaut lorsqu'une valeur n'existe peut-être pas.


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

Construction d'URL dynamique

Créez une URL de serveur de décision publicitaire à partir de plusieurs entrées.


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

Vérifications du code d'état pour la sortie HTTP_REQUEST

Protégez les valeurs de sortie contre les défaillances HTTP.


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

Conversion numérique à partir des paramètres du joueur

Les paramètres du joueur arrivent sous forme de chaînes. Convertissez-les avant les comparaisons arithmétiques ou numériques.


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

Important

S'il $number() reçoit une chaîne non numérique, il renvoie. undefined Combinez-le avec le $exists() cas où le paramètre est peut-être manquant ou non valide :($val := $number(player_params.max_duration); $exists($val) and $val > 30 ? 'long' : 'short').

Répartition aléatoire du trafic

Assignez des spectateurs à des groupes d'expériences en utilisant$random().


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

Classification des types d'appareils

Classez les appareils en fonction de la chaîne de l'agent utilisateur.


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

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Création et gestion

Exemples de fonctions

Référence d'expression JSonata pour les fonctions

Délimiteurs d'expressions

Important

Bases de la langue

Notation par points pour la navigation sur le chemin

Concaténation de chaînes avec &amp;

Expressions conditionnelles (ternaires)

Liaison de variables avec : =

Opérateurs

Arithmétique

Important

Comparison (Comparaison)

Booléen

Note

Adhésion (en)

Enchaînement (~ >)

Fonctions autorisées

Conversion de type (3)

Introspection (4)

Numérique (7)

Corde (7)

Réseau (5)

Booléen (1)

Aléatoire (1)

Note

Date/time (4)

Encodage (6)

Astuce

Schémas courants

Valeurs de repli

Construction d'URL dynamique

Vérifications du code d'état pour la sortie HTTP_REQUEST

Conversion numérique à partir des paramètres du joueur

Important

Répartition aléatoire du trafic

Classification des types d'appareils

Concaténation de chaînes avec `&`

Liaison de variables avec `: =`

Adhésion (`en`)

Enchaînement (`~ >`)