Referência do Apache FreeMarker

Operações Incorporadas de String do FreeMarker

A tabela a seguir mostra como usar algumas operações de string incorporadas usando uma variável de string chamada tester, cujo valor é enviado para "hello world " (com três espaços em branco à direita).

Observação

A expressão a seguir permite que o bot gere o valor tester ou no string found se nenhum valor tiver sido definido para a variável.

${tester.value!'no string found'}

Operação Incorporada	Uso	Saída
`capitalize`	`${tester.value?capitalize}`	`Hello World`
`last_index_of`	`${tester.value?last_index_of('orld')}`	`7`
`left_pad`	`${tester.value?left_pad(3,'_')}`	`___hello world`
`length`	`${tester.value?length}`	`14`
`lower_case`	`${tester.value?lower_case}`	`hello world`
`upper_case`	`${tester.value?upper_case}`	`HELLO WORLD`
`replace`	`${tester.value?replace('world', 'friends')}`	`hello friends`
`remove_beginning`	`${tester.value?remove_beginning('hello')}`	`world`
`trim`	`${tester.value?trim}`	`hello world` (os três espaços à direita são removidos)
`ensure_starts_with`	`${tester.value?ensure_starts_with('brave new ')}`	`brave new hello world`
`ensure_ends_with`	${tester.value?ensure_ends_with(' my friend')}$	`hello world my friend`
`contains`	`${tester.value?contains('world')?string ('You said world', 'You did not say world')}`	`You said world` As expressões `contains('world')` retornam `true` ou `false`. Esses valores boolianos são substituídos por uma string usando a função `string ('string1','string2')`.
`ends_with`	`${tester.value?ends_with('world')?string ('Ends with world', 'Doesn't end with world')}`	`Ends with world`
`starts_with`	`${tester.value?starts_with('world')?string ('Starts with world', 'Doesn't start with world')}`	`Doesn't start with world`
`matches` (expressão regular retorna verdadeiro ou falso)	`${tester.value?matches('^([^0-9]*)$')}`	A expressão regular retorna `true` ou `false`, dependendo de se o valor contém um número (nesse caso, o valor booliano é retornado como `false`). O valor `tester` retorna `true`.
`matches` (expressão regular retorna uma string)	`${tester.value?matches('^([^0-9]*)$')?}`	Igual ao anterior, mas desta vez, `true` é retornado como string. A função `matches('regular expression')` retorna `true` ou `false` como tipos boolianos. Para imprimir `true` ou `false` em um componente `System.Output`, use `?string` para executar uma conversão em string. Observação: Você não pode usar a expressão regular para retornar um grupo de valores; use-a para retornar um único valor correspondente (ou nenhuma correspondência).

Exemplo: Transformando Caso com o Componente Switch

Imagine um caso em que diferentes estados são chamados dependendo da entrada do usuário (wine ou beer), que é armazenada na variável choice.

A capitalização da entrada do usuário pode estar inconsistente, mesmo em uma palavra (WiNE). Em vez de adicionar todas as variações possíveis à definição do componente, use uma operação FTL, como upper_case, para uniformizar a capitalização:

${choice.value?upper_case}

Exemplo: Concatenando Expressões FTL

Você também pode concatenar operações FTL em uma única expressão.

No exemplo a seguir, os números de voo da companhia aérea (representados pela variável flight.value) de UA1234 e UA 1234 seriam transformados em 1234.

${flight.value?trim?lower_case?remove_beginning('ua ')?remove_beginning('ua')}"

Operações Incorporadas de Número do FreeMarker

A tabela a seguir lista as operações incorporadas de número e mostra como elas geram o valor definido para as variáveis negativeValue (-2,5) e positiveValue (0,5175):

Operação	Exemplo	Saída
`abs`	`${negativeValue.value?abs}`	2,5 O operador transforma o valor numérico negativo em um valor positivo.
`string` (usado com um valor numérico)	`${negativeValue.value?abs?string.percent}`	250% O operador primeiro altera o valor negativo para um positivo. Em seguida, ele o converte em percentual, multiplicando implicitamente o valor por 100.
`string` (com o valor de formato decimal e várias moedas) Dica: Verifique Base de Caracteres para obter outros símbolos de moeda.	`${positiveValue.value?string['###.##']}`	0,51
	`${positiveValue.value?string['###.##%']}`	51% O operador adiciona um caractere de porcentagem depois de multiplicar o valor por 100.
	`${positiveValue.value?string['##.###\u00A4']}`	0,51 $
	`${positiveValue.value?string['##.###\u20AC']}`	0,51 €
	`${positiveValue.value?string['##.###\u00A3']}`	0,51 £
`round`	`${negativeValue.value?round}`	-2 O operador arredonda para o número inteiro mais próximo. Se o número terminar com ,5, ele será arredondado para cima.
`round`	`${positiveValue.value?round}`	1 O operador arredonda para o número inteiro mais próximo. Se o número terminar com ,5, ele será arredondado para cima.
`floor`	`${positiveValue.value?floor}`	0 O operador arredonda para baixo.
`ceiling`	`${positiveValue.value?ceiling}`	1 O operador arredonda para cima.
`lower_abc`	`${negativeValue.value?abs?round?lower_abc}`	c O operador transforma o valor negativo em um positivo e o arredonda para 3. Retorna c, a terceira letra do alfabeto.
`upper_abc`	`${negativeValue.value?abs?round?upper_abc}`	C O operador transforma o valor negativo em um positivo e o arredonda para 3. Retorna C, a terceira letra do alfabeto.
`is_infinite`	`${positiveValue.value?is_infinite?string}`	falso O operador retorna falso porque um valor flutuante não é infinito de acordo com o IEEE 754 (Padrão para Floating-Point Arithmetic). Observação: O valor retornado seria um booliano sem `?string`.

Operações Incorporadas de Array do FreeMarker

As operações de array (ou sequência ) permitem que seu bot, entre outras coisas, determine o tamanho de um array, classifique os arrays ou encontre conteúdo em um array.

Você pode usar arrays para criar dados simulados de teste ou para definir estruturas de dados que persistem além das sessões do usuário. Você pode salvar uma matriz em um componente personalizado, em um fluxo ou em uma variável global. Aqui estão arrays para variáveis person e colors, respectivamente.

[
  {
    "firstName" : "Frank",
    "lastName" : "Normal"
  },
  {
    "firstName" : "Grant",
    "lastName" : "Right"
  },
  {
    "firstName" : "Geoff",
    "lastName" : "Power"
  },
  {
    "firstName" : "Marcelo",
    "lastName" : "Jump"
  }
]

[
    "yellow", "blue", "red", "black", "white", "green"
  ]

Essas matrizes são usadas para ilustrar as operações de matrizes na tabela a seguir e no Exemplo: Iterando Matrizes.

Operador	Exemplo	Saída
`size`	`${person.value?size?number}`	`4` — O tamanho (quatro membros) do array `person`
índice de array	`${person.value[1].firstName}`	`Grant` — É o valor da segunda propriedade `firstName` no array `person`.
índice de array	`${person.value[1].firstName !'unknown'}`	O mesmo que acima, mas nesse caso, o bot vai gerar um erro desconhecido se a segunda propriedade `firstName` não tiver valor.
`first`	`${person.value?first.firstName}`	`Frank` — A primeira entrada do array de pessoa. Essa operação não usa o índice de array.
`last`	`${person.value?last.firstName}`	`Marcelo` — O valor `lastName` final no array de pessoa.
`sort_by`	`${person.value?sort_by('lastName') [0].firstName}`	`Marcelo` Esse operador classifica o array `person` pela propriedade `lastName` em ordem crescente. Em seguida, ele imprime o valor da propriedade `firstName` correspondente para entrada final no array de pessoa: Saltar, Marcelo Normal, Frank Poder, Geoff Direito, Conceder Observação: A menos que você salve o array classificado em uma variável usando `System.SetVariable`, os dados permanecerão classificados apenas para uma única solicitação.
`sort_by`	`${person.value?sort_by('lastName')?reverse[0].firstName}`	`Grant` — os valores são classificados em ordem decrescente: Direito, Conceder Poder, Geoff Normal, Frank Saltar, Marcelo
`seq_index_of`	`${colors.value?seq_index_of('red')}`	`2` — O valor do índice para vermelho no array de cores.
`seq_last_index_of`	`${colors.value?seq_last_index_of('red')}`	`2` — O último valor de índice para vermelho no
`join`	`${colors.value?join(',')}`	Retorna o array `colors` como string separada por vírgulas: `yellow, blue, red, black, white, green`
`seq_contains`	`${colors.value?seq_contains('red')?string('Yes', 'No')`	Retorna `Yes` porque o array contém vermelho. Observação: `?seq_contains` retorna um valor booliano. Esse valor então é substituído por uma string usando a expressão `?string('…','…')`.
`sort`	`${colors.value?sort?join(',')}`	Retorna o array de cores como string separada por vírgulas na ordem crescente: `black, blue, green, red, white, yellow`
`reverse`	`${colors.value?sort?reverse?join(',')}`	Retorna o array `colors` como string separada por vírgulas em ordem decrescente: `yellow, blue, red, black, white, green`

Retornando Intenções e Pontuações

Você pode usar operações de array para retornar os resultados do processamento da intenção e da entidade. Por exemplo :

${skill.system.nlpresult.value.entityMatches[‘name of entity’]} retorna um array de entidades encontradas em uma string do usuário que é transmitida ao Mecanismo de Intenção armazenado na variável nlpresult.
${skill.system.nlpresult.value.intentMatches.summary[n].intent} retorna o nome da intenção que tem uma classificação de confiança de n, em que 0 representa a intenção com classificação mais alta, 1 representa a segunda intenção classificada etc.
${skill.system.nlpresult.value.intentMatches.summary[n].score} retorna a pontuação de confiança para a intenção fornecida.

Para estas duas expressões, n é o índice do item que você deseja pesquisar. Por exemplo, a expressão para retornar o nome da intenção resolvida no nível superior seria:

${skill.system.nlpresult.value.intentMatches.summary[0].intent}

Para a pontuação da intenção superior, a expressão seria:

${skill.system.nlpresult.value.intentMatches.summary[0].score}

Você pode usar essas expressões para intenções com pontuação acima do limite de confiança, mas também pode usá-las para retornar intenções cuja pontuação está abaixo do limite de confiança. Essas expressões não dependem do valor do limite de confiança configurado na página Definições da Habilidade para que você possa usá-las para retornar as intenções do candidato e suas respectivas pontuações, mesmo quando nenhuma intenção puder ser resolvida e uma ação unresolvedIntent tiver sido acionada. Nesse caso, você pode, por exemplo, usar essas expressões para retornar as três intenções superiores e suas pontuações de limite de subconfiança.

Observação

Se você precisar se referir à intenção que um usuário selecionou após ser solicitado a desambiguar, poderá usar ${system.intent.name}. (${skill.system.nlpresult.value.intentMatches.summary[0].intent} sempre retorna a intenção com a pontuação superior, que pode não ser a intenção que o usuário seleciona ao desambiguar.

Exemplo: Iterando Arrays

Os arrays determinam o número de entidades na entrada do usuário.

Descrição da ilustração arrayoutput.png

O seguinte snippet da propriedade Metadados de um componente de Resposta Comum mostra como determinar o tamanho do array mantido na variável person e depois repetir seus elementos para que a habilidade gere algo como:


responseItems:
- type: "text"
  text: "${person?index+1}. ${person.firstName} ${person.lastName}"
  name: "Sorry"
  separateBubbles: true
  iteratorVariable: "person"

Observação

A saída descrita neste código não é classificada (ou seja, nenhuma operação sort_by é usada).

Operações Incorporadas de Data do FreeMarker

A expressão a seguir deriva a data atual usando a referência de variável especial FreeMarker .now e o operador date incorporado.

${.now?date}

A tabela a seguir lista algumas das operações de data incorporadas que você pode usar para definir propriedades e manipular valores de entidade.

Operações	Exemplo	Saída
`date`	`${.now?date}`	A data atual
`time`	`${.now?time}`	A hora do dia, como 5:46:09 PM
`datetime`	`${.now?datetime}`	Imprime a data e hora atuais, como Jan 17, 2018 5: 36:13 PM.
`long` e `number_to_date`	`${(.now?long + 86400000)?number_to_date }`	Adicionar 24 horas à data atual. Se a chamada é feita em 17 de janeiro de 2018, o FreeMarker gera 18 de janeiro de 2018.
`string` (com estilos de formatação)	`${.now?string.full}`	Converte a data atual em string formatada como Wednesday, January 17, 2018 6:35:12 PM UTC.
	`${.now?string.long}`	Converte data em string com a seguinte saída formatada: January 17, 20186:36:47 PM UTC.
	`${.now?string.short}`	Converte data em string com a seguinte saída formatada: 1/17/18 6:37 PM
	`${.now?string.medium}`	Converte data em string com a seguinte saída formatada: Jan 17, 2018 6:38:35.
	`${.now?string.iso}`	Imprime a data no padrão ISO 8601, como 2018-01-17T18:54:01.129Z.
`string` (com formatos de saída especificados)	`${.now?string['dd.MM.yyyy, HH:mm']}`	Imprime a data atual em um formato personalizado, como 17.01.2018, 18:58.
`string` (com formatos de saída especificados)	`${.now?string['yyyy']}`	2018
`datetime` (com `string` e estilo de formatação)	`${date_variable?datetime?string.short}`	Converte a data em uma string formatada como 1/17/18 6: 37 PM. O operador `datetime` permite que o FreeMarker informe se a variável contém uma data que contém informações de data e hora. Da mesma forma, você pode usar os operadores `date` ou `time` para indicar se o valor de data contém apenas a data ou apenas a hora, mas o uso de `datetime?string` evita erros.
Convertendo o valor de entidade em uma string com o uso de `date` `long` `number_to_date` estilos de formatação formatos de data personalizados	`${dateVar.value.date?long?number_to_date?date?string.short}`	Converte a data da extração de entidade em uma string formatada como 11/17/18. O operador de data informa ao FreeMarker que a variável mantém apenas uma data, não informações de horário. O uso desse formato evita erros.
	`${dateVar.value.date?long?number_to_date?string.medium}`	Converte a data derivada da extração de entidade em uma string formatada como Jan 17, 2018. Observação: Todos os demais formatos, como `full`, `short`, `long` e `iso`, funcionam da mesma forma com datas derivadas da extração de entidade.
	`${dateVar.value.date?long?number_to_date?string['dd.MM.yyyy']}`	Imprime a data no formato personalizado. Por exemplo: 17.01.2018, 18:58.
	`${dateVar.value.date?long?number_to_date?string['yyyy']}`	Imprime a data derivada da entidade em um formato personalizado.

Exemplo: Extraindo Datas da Entrada do Usuário

Os exemplos a seguir são de uma habilidade que gerencia compromissos. Quando um usuário pergunta, Você pode organizar uma reunião com o Sr. Higgs depois de amanhã?, o bot usa uma entidade complexa, DATE, para extrair amanhã da solicitação. Ele gera a data solicitada usando ${(theDate.value.date?long + 86400000)?number_to_date} para adicionar 24 horas (ou 86.400.000 milissegundos) a "amanhã".

Texto com Expressão	Saída
`"Today is: ${.now}"`	Hoje é: 1/18/18 8:31 AM
`"Date found is: ${theDate.value.date}"`	A data encontrada é: Jan 19, 2018
`"A day later is ${(theDate.value.date?long + 86400000)?number_to_date}"`	Um dia depois é: Jan 20, 2018

Exemplo: Definindo uma Data Padrão (Quando Nenhum Valor de Data Foi Definido)

Se a mensagem do usuário não incluir informações de data, sua habilidade poderá solicitar aos usuários a data ou fornecer uma data padrão. Para fornecer a data atual, você pode usar a seguinte expressão:

${.now?datetime?string.long}

Variáveis de Sistema Acessíveis pelo FreeMarker

O Oracle Digital Assistant tem um conjunto de variáveis de sistema por meio do qual você pode recuperar informações úteis em seus fluxos de caixas de diálogo por meio de expressões do FreeMarker.

Em suas formas mais simples, essas expressões têm o seguinte formato:

${system.variableName}

Algumas variáveis podem conter objetos com propriedades aninhadas que podem ser acessadas usando a notação de ponto após o nome da variável no formato a seguir.

${system.variableName.propertyName}

Além disso, os valores de propriedades aninhadas também podem ser objetos com propriedades aninhadas.

Estas são as variáveis de sistema que estão disponíveis por meio de expressões FreeMarker.

Variável	Descrição
`system.actualState`	Nome do estado para o qual o usuário navegou tocando em um botão "fora da ordem" mais antigo. Se o payload de postback contiver uma propriedade `system.state`, o mecanismo de caixa de diálogo navegará até esse estado e definirá essa variável com o nome desse estado. Consulte também Configurar o Fluxo de Caixas de Diálogo para Ações Inesperadas.
`system.authorizedUsers`	Uma lista de todos os usuários autorizados para um chat em grupo específico.
`system.channelType`	O tipo de canal da sessão do usuário atual. Valores permitidos: `facebook`, `androidsdk`, `iossdk`, `websdk`, `slack`, `twilio`, `msteams`, `cortana`, `webhook` e `test`. Se a sessão estiver sendo executada no testador, o valor corresponderá ao tipo de canal que está sendo simulado.
`system.entityToResolve`	Objeto que representa o item de repositório atual a ser resolvido no componente Resposta Comum quando a propriedade de variável do componente está se referindo a um objeto composto entity.The tem as seguintes propriedades: `nextRangeStart` - número de índice da lista de valores permitidos da entidade que será percorrida ao tocar no botão Mostrar Mais. `updatedEntities` - lista de itens de repositório que foram atualizados com base na última mensagem do usuário. `needShowMoreButton` - Propriedade booliana que pode ser usada como `expression` para a propriedade `visible` para renderizar condicionalmente o botão Mostrar Mais para navegar até o próximo conjunto de valores de entidade. `outOfOrderMatches` - lista de itens de repositório que foram preenchidos com um valor baseado na última mensagem do usuário quando ele foi solicitado a fornecer outro item de repositório. `rangeStartVar` - nome da variável que mantém o início da faixa atual dos valores de entidade. `validationErrors` - para o item de repositório atual, lista de mensagens de erro causadas por um valor inválido fornecido na última mensagem do usuário. `allMatches` - lista de itens de repositório que tiveram valores novos ou atualizados com base na última mensagem do usuário. `resolvingField` - nome do item de repositório atual que o usuário foi solicitado a informar. `userInput` - a última mensagem do usuário. `skippedItems` - lista de itens de repositório em que o número máximo de solicitações de um valor foi excedido. `disambiguationValues` - lista de valores de entidade permitidos que têm correspondências na última mensagem do usuário. `enumValues` - lista de valores permitidos de entidade para o item de repositório atual. Consulte A Variável system.entityToResolve par obter exemplos de como usar `system.entityToResolve`.
`system.errorAction`	O texto da mensagem de um erro inesperado gerado durante a execução do estado.
`system.errorState`	Nome do estado que gerou um erro inesperado durante a execução.
`system.expectedState`	Quando o usuário rola o histórico de mensagens para cima e toca em um botão "fora da ordem" mais antigo, essa variável é preenchida com o nome do estado que deveria ser executado, mas nunca foi porque o usuário decidiu tocar nesse botão "fora da ordem". Consulte também Configurar o Fluxo de Caixas de Diálogo para Ações Inesperadas.
`system.intent.name`	Use para se referir à intenção que um usuário selecionou depois de ser solicitado a desambiguar. ( `${iResult.value.intentMatches.summary[0].intent}` sempre retorna a intenção com a pontuação superior, que pode não ser a intenção que o usuário seleciona ao desambiguar.)
`system.invalidUserInput`	Valor booliano definido como `true` quando a entrada do usuário não pode corresponder ao tipo de variável solicitado.
`system.message`	Última mensagem recebida pelo Oracle Digital Assistant. Essa variável tem as seguintes propriedades: `channelConversation` - o objeto de conversa do canal, que tem as seguintes propriedades: `botId` `channelType` - Ao executar no testador, isso retornará `test`. Para obter o nome do canal que está sendo simulado no testador, use `system.channelType` em seu lugar. `channelName` `channelCategory` - Retorna o tipo de canal. Para canais DA as Agent, isso retorna `botAsAgent`. `groupConversation` - Retorna `true` se a conversa for um chat em grupo. `userId` - Retorna o ID do usuário. Para canais DA as Agent, isso retornará o ID de engajamento. `sessionId` - Retorna o ID da sessão. Para canais DA as Agent, isso retornará o ID de engajamento. `sessionExpiryDuration` `messagePayload` - a mensagem real enviada pelo usuário. As propriedades que você pode acessar dependem do tipo de mensagem: Mensagem de texto: a propriedade `text` que retorna a mensagem real digitada pelo usuário Mensagem de retorno: as propriedades do objeto de retorno, geralmente `action` e `variables` ao usar o componente Resposta Comum. Por exemplo, quando o usuário toca em um botão que define a variável `pizzaSize`, esse valor pode ser recuperado usando esta expressão: `${system.message.messagePayload.variables.pizzaSize}` Mensagem de localização: a propriedade `location`, que contém um objeto de localização com as seguintes propriedades: `title` `url` `latitude` `longitude` `stateCount` - o número de estados executados para processar a última mensagem do usuário. `platformVersion` - a versão atual da plataforma de runtime.
`system.requestedState`	Se um usuário entrar em uma conversa em um estado que exija autorização e o usuário não estiver na lista de usuários armazenados em `system.authorizedUsers`, o mecanismo de caixa de diálogo armazenará o estado que pretendia executar nessa variável.
`system.selectedCardIndex`	Essa variável mantém o índice do cartão selecionado ao usar o recurso de otimizar a renderização do cartão para canais somente texto, como o Twilio. Essa otimização permite que o usuário selecione um cartão em um processo de duas etapas: primeiramente, uma lista de cartões é apresentada; em seguida, o usuário pode informar o número dos cartões que ele deseja selecionar. O número de índice correspondente desse cartão é armazenado nessa variável.

Observação

As variáveis do sistema na tabela acima são as únicas que você pode usar nas expressões FreeMarker. Outras variáveis do sistema não são públicas e seu uso está sujeito a alterações, o que significa que suas habilidades não podem confiar nelas.

Por exemplo, as variáveis system.routingFromSkill, system.routingToSkill, system.routingFromIntent e system.routingToIntent só estão disponíveis para definições específicas do assistente digital. Consulte Variáveis de Sistema para Assistentes Digitais.

Documentação do Oracle Cloud Infrastructure

Referência do D Apache FreeMarker