Delimitadores de expressão Noções básicas de idioma Operadores Funções permitidas Padrões comuns

JSONata referência de expressão para funções

Esta página é uma referência completa para a sintaxe de expressões, operadores e funções disponíveis em Funções. Use-o ao escrever expressões para blocos de saída, campos de URL, valores de cabeçalho, modelos de corpo e condições de execução.

Delimitadores de expressão

Cada valor que você define em uma função é uma constante ou uma expressão, não uma mistura de ambos. MediaTailor distingue entre os dois com base em delimitadores.

Sintaxe	Tipo	Avaliação
`https://ads.example.com/vast`	Constante	Retornado no estado em que se encontra, sem avaliação.
`{%session.client_ip%}`	Expressão	Avaliado em tempo de execução. O resultado substitui todo o valor.
`GET`	Constante	Retornado como está.
`{%'https://ads.example.com/vast?ip=' & session.client_ip%}`	Expressão	Avaliado em tempo de execução.

Importante

Um valor é totalmente constante ou totalmente uma expressão. Você não pode misturar os dois em um único valor. Por exemplo, hello {%'world'%} não é válido. Para combinar texto estático com valores dinâmicos, use a concatenação de strings dentro da expressão:. {%'hello ' & 'world'%}

Noções básicas de idioma

Notação de pontos para navegação por caminhos

Use a notação de pontos para percorrer os dados de entrada. Cada ponto desce um nível na hierarquia do objeto.


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

Os campos ausentes retornam null sem gerar um erro:


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

Concatenação de strings com `&`

O & operador une dois valores de cadeia de caracteres. Non-string os valores são convertidos em strings automaticamente.


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

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

Expressões condicionais (ternárias)

Use o operador ternário para retornar um dos dois valores com base em uma condição.


condition ? value_if_true : value_if_false

Exemplos:


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

Você pode agrupar expressões ternárias para ramificação multidirecional:


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

Vinculação de variável com`: =`

Use o := operador entre parênteses para atribuir valores intermediários em uma expressão. As variáveis vinculadas têm como escopo os parênteses delimitadores e não persistem fora da expressão.


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

Os pontos e vírgulas separam as declarações dentro de parênteses. A última declaração é o valor de retorno da expressão.


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

Operadores

Aritmética

Operador	Description	Exemplo	Resultado
`+`	Adição	`5 + 3`	`8`
`-`	Subtração	`10 - 4`	`6`
`*`	Multiplicação	`6 * 7`	`42`
`/`	Divisão	`15 / 4`	`3.75`
`%`	Módulo	`17 % 5`	`2`

Importante

Os valores de entrada dos parâmetros do jogador e dos dados da sessão chegam como strings. Use $number() para convertê-los antes de comparações numéricas ou aritméticas. Comparar uma string com um número produz resultados inesperados.

Comparação

Operador	Description	Exemplo	Resultado
`=`	Igual a	`response.statusCode = 200`	`true`
`!=`	Não é igual a	`player_params.region != 'us-east-1'`	`true`se não for us-east-1
`<`	Menor que	`avail.index < 3`	`true`se abaixo de 3
`>`	Maior que	`$number(player_params.age) > 18`	`true`se tiver mais de 18 anos
`<=`	Menor ou igual a	`$count(items) <= 10`	`true`se 10 ou menos
`>=`	Maior ou igual a	`response.statusCode >= 400`	`true`se o status do erro

Booleano

Operador	Description	Exemplo
`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ênteses para dar precedência:


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

nota

Use $not() para negação lógica. Não há operador de not palavra-chave.

Filiação (`em`)

O in operador testa se existe um valor em uma matriz.


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

Encadeamento (`~) >`

O operador de encadeamento passa o resultado da expressão à esquerda como o primeiro argumento para a função à direita.


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

Funções permitidas

MediaTailor suporta as seguintes funções integradas. Qualquer função não listada aqui é bloqueada e causa um erro de validação quando você cria ou atualiza uma função.

Conversão de tipo (3)

Função	Description	Exemplo	Resultado
`$string(value)`	Converter em string	`$string(200)`	`"200"`
`$number(value)`	Converter em número	`$number('42')`	`42`
`$boolean(value)`	Converter em booleano	`$boolean(1)`	`true`

Introspecção (6)

Função	Description	Exemplo	Resultado
`$length(string)`	Tamanho da segmento	`$length('hello')`	`5`
`$count(array)`	Contagem de elementos da matriz	`$count([1, 2, 3])`	`3`
`$exists(value)`	Verifique se o valor existe (não indefinido)	`$exists(temp.id)`	`true` ou `false`
`$keys(object)`	Obter nomes de chaves de objetos	`$keys(response.body)`	`["id", "name"]`
`$lookup(object, key)`	Obter valor do objeto pelo nome da chave	`$lookup(response.body, 'status')`	Valor do `status` campo
`$each(object, func)`	Aplicar função a cada par de valores-chave de um objeto	`$each({"a":1,"b":2}, function($v,$k){$k & '=' & $v})`	`["a=1", "b=2"]`

Numérico (7)

Função	Description	Exemplo	Resultado
`$sum(array)`	Soma da 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)`	Média aritmética	`$average([10, 20, 30])`	`20`
`$abs(number)`	Valor absoluto	`$abs(-7)`	`7`
`$floor(number)`	Arredondar para baixo	`$floor(3.9)`	`3`
`$round(number, precision)`	Redondo até a precisão	`$round(3.456, 2)`	`3.46`

Corda (9)

Função	Description	Exemplo	Resultado
`$uppercase(string)`	Para maiúsculas	`$uppercase('hello')`	`"HELLO"`
`$lowercase(string)`	Para minúsculas	`$lowercase('Hello')`	`"hello"`
`$trim(string)`	Remover espaço em leading/trailing branco	`$trim(' hi ')`	`"hi"`
`$substring(string, start, length)`	Extrair substring (com base em zero)	`$substring('abcdef', 2, 3)`	`"cde"`
`$contains(string, pattern)`	Verifique se a string contém padrão	`$contains(session.user_agent, 'CTV')`	`true` ou `false`
`$match(string, pattern)`	Combine a string com o padrão regex	`$match('abc-123', /[0-9]+/)`	`{"match": "123", ...}`
`$replace(string, pattern, replacement)`	Substitua o padrão correspondente	`$replace('hello', 'l', 'r')`	`"herro"`
`$join(array, separator)`	Unir elementos de matriz em uma string	`$join(['a','b','c'], ',')`	`"a,b,c"`
`$split(string, separator)`	Dividir string em uma matriz	`$split('a,b,c', ',')`	`["a", "b", "c"]`

Matriz (7)

Função	Description	Exemplo	Resultado
`$append(arr1, arr2)`	Concatenar matrizes	`$append([1, 2], [3, 4])`	`[1, 2, 3, 4]`
`$reverse(array)`	Ordem inversa	`$reverse([1, 2, 3])`	`[3, 2, 1]`
`$sort(array)`	Matriz de classificação	`$sort([3, 1, 2])`	`[1, 2, 3]`
`$distinct(array)`	Remover duplicações	`$distinct([1, 2, 2, 3])`	`[1, 2, 3]`
`$map(array, func)`	Aplicar função a cada elemento	`$map([1,2,3], function($v){$v*2})`	`[2, 4, 6]`
`$filter(array, func)`	Elementos de retorno em que a função retorna verdadeira	`$filter([1,2,3,4], function($v){$v > 2})`	`[3, 4]`
`$reduce(array, func, init)`	Reduzir a matriz para um único valor	`$reduce([1,2,3], function($prev,$val){$prev+$val}, 0)`	`6`

Booleano (1)

Função	Description	Exemplo	Resultado
`$not(value)`	Lógico (NÃO)	`$not(false)`	`true`

Aleatório (1)

Função	Description	Exemplo	Resultado
`$random()`	Número aleatório entre 0 (inclusive) e 1 (exclusivo)	`$random() > 0.5 ? 'A' : 'B'`	`"A"` ou `"B"`

nota

$random()gera um novo valor em cada avaliação. Se você precisar do mesmo valor aleatório em várias chaves de saída, vincule-o primeiro a uma variável:($r := $random(); ...).

Date/time (4)

Função	Description	Exemplo	Resultado
`$now()`	Carimbo de data/hora atual como uma string ISO 8601	`$now()`	`"2024-01-15T12:00:00.000Z"`
`$millis()`	Carimbo de data/hora atual em milissegundos desde a época	`$millis()`	`1705320000000`
`$toMillis(string)`	Converta a string ISO 8601 em milissegundos	`$toMillis('2024-01-15T12:00:00.000Z')`	`1705320000000`
`$fromMillis(number)`	Converta milissegundos em string ISO 8601	`$fromMillis(1705320000000)`	`"2024-01-15T12:00:00.000Z"`

Codificação (6)

Função	Description	Exemplo
`$encodeUrl(string)`	Codificação de URL (preserva caracteres estruturais como`/`,,`?`) `&`	`$encodeUrl('https://example.com/path?q=hello world')`
`$encodeUrlComponent(string)`	URL codifica um único componente (codifica todos os caracteres especiais)	`$encodeUrlComponent('a&b=c')` → `"a%26b%3Dc"`
`$decodeUrl(string)`	Decodificar uma string URL-encoded	`$decodeUrl('hello%20world')` → `"hello world"`
`$decodeUrlComponent(string)`	Decodificar um componente URL-encoded	`$decodeUrlComponent('a%26b')` → `"a&b"`
`$base64encode(string)`	Codificar para Base64	`$base64encode('hello')` → `"aGVsbG8="`
`$base64decode(string)`	Decodifique a partir de Base64	`$base64decode('aGVsbG8=')` → `"hello"`

dica

Use $encodeUrlComponent() para valores de parâmetros de consulta individuais. Use $encodeUrl() somente quando precisar codificar um URL completo e, ao mesmo tempo, preservar sua estrutura.

Padrões comuns

Valores alternativos

Forneça um padrão quando um valor pode não existir.


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

Construção dinâmica de URL

Crie um URL de servidor de decisão de anúncios a partir de várias entradas.


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

O código de status verifica a saída HTTP_REQUEST

Proteja os valores de saída contra falhas de HTTP.


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

Conversão numérica dos parâmetros do player

Os parâmetros do player chegam como strings. Converta-os antes das comparações aritméticas ou numéricas.


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

Importante

Se $number() receber uma string não numérica, ela retornará. undefined Combine-o com $exists() quando o parâmetro pode estar ausente ou ser inválido:($val := $number(player_params.max_duration); $exists($val) and $val > 30 ? 'long' : 'short').

Divisão aleatória de tráfego

Atribua espectadores a grupos de experimentos usando$random().


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

Classificação do tipo de dispositivo

Classifique os dispositivos com base na string do agente do usuário.


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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Criando e gerenciando

Exemplos de funções

JSONata referência de expressão para funções

Delimitadores de expressão

Importante

Noções básicas de idioma

Notação de pontos para navegação por caminhos

Concatenação de strings com &amp;

Expressões condicionais (ternárias)

Vinculação de variável com: =

Operadores

Aritmética

Importante

Comparação

Booleano

nota

Filiação (em)

Encadeamento (~) >

Funções permitidas

Conversão de tipo (3)

Introspecção (6)

Numérico (7)

Corda (9)

Matriz (7)

Booleano (1)

Aleatório (1)

nota

Date/time (4)

Codificação (6)

dica

Padrões comuns

Valores alternativos

Construção dinâmica de URL

O código de status verifica a saída HTTP_REQUEST

Conversão numérica dos parâmetros do player

Importante

Divisão aleatória de tráfego

Classificação do tipo de dispositivo

Concatenação de strings com `&`

Vinculação de variável com`: =`

Filiação (`em`)

Encadeamento (`~) >`