Métodos de linguagem de expressão para ações

A linguagem de expressões do assistente de IA pode ser usada para especificar valores que são independentes ou derivados de valores coletados em etapas ou armazenados em variáveis de sessão. É possível usar uma expressão para definir uma condição de etapa ou o valor de uma variável de sessão.

A linguagem de expressões do assistente de IA baseia-se na Spring Expression Language ( SpEL ), mas apresenta algumas diferenças importantes na sintaxe. Para obter informações detalhadas sobre a linguagem de expressões do Spring ( SpEL, ), consulte a página Spring Expression Language ( SpEL ).

É possível usar expressões SpEL de duas maneiras:

Referenciando variáveis de ação

Uma variável de ação é criada implicitamente para qualquer etapa que espera a entrada do cliente e está ligada à etapa. Para fazer referência a uma variável de ação dentro de uma expressão, você deve especificar a ID da etapa usando o formato ' ${step_id} (por exemplo, ' ${step_771}. Para localizar o ID da etapa para uma etapa, selecione a etapa e, em seguida, verifique o final da URL no navegador.

Referenciando variáveis de sessão

As variáveis de sessão são criadas explicitamente na seção Variáveis da etapa. Para fazer referência a uma variável de sessão dentro de uma expressão, você deve especificar o ID da variável usando o formato ' ${variable_id} (por exemplo, ' ${current_time}. É possível localizar o ID da variável na lista de variáveis. (Para obter mais informações, consulte Usando variáveis para gerenciar informações da conversa.)

Quando estiver editando uma expressão, você pode digitar ' $ para ver uma lista de variáveis que podem ser referenciadas. Selecione uma variável da lista para inserir automaticamente o ID da etapa ou ID da variável.

Tipos de dados suportados

As expressões podem usar tipos JSON atômicos (como ' integer, ' string, ' number e ' boolean) e tipos de dados compostos (como matrizes JSON ([]) e objetos ({}). Ao especificar valores literais de cadeia de caracteres, você pode usar aspas simples (') ou duplas (").

Os valores que as etapas de ação coletam dos clientes usam tipos de resposta para o cliente como data, horário, moeda ou percentual. Esses valores são armazenados como objetos JSON no formato a seguir:

{
  "system_type": "{system_type}",
  "value": "{value}"
}

em que {system_type} é um dos tipos a seguir:

  • time

  • percentage

  • currency

Métodos de data e horário

Há vários métodos disponíveis para se trabalhar com valores de data e horário.

now(String timezone)

O método now() retorna a data e o horário atuais para um fuso horário especificado no formato yyyy-MM-dd HH:mm:ss 'GMT'XXX:

now('Australia/Sydney').

Nesse exemplo, se a data e a hora atuais forem " 2021-11-26 11:41:00, a cadeia de caracteres retornada será " 2021-11-26 21:41:00 GMT+10.00 ou " 2021-11-26 21:41:00 GMT+11.00, dependendo do horário de verão.

A alteração do formato da string de saída também se aplica aos métodos de cálculo de data e hora. Por exemplo, se a cadeia de caracteres ' <date> usada estiver no formato ' yyyy-MM-dd HH:mm:ss, como quando você usa o método ' today(), a saída estará no mesmo formato (yyyy-MM-dd HH:mm:ss). No entanto, se a cadeia de caracteres ' <date> estiver no formato ' yyyy-MM-dd HH:mm:ss 'GMT'XXX, como quando você usa o método ' now(), a saída estará no formato ' yyyy-MM-dd HH:mm:ss 'GMT'XXX.

.reformatDateTime(String format)

Formata sequências de data e horário para saída. O parâmetro é uma cadeia de caracteres de formato que especifica como o valor de data ou hora é formatado. A string de formatação deve ser especificada usando a sintaxe Java SimpleDateFormat.

Esse método retorna uma cadeia de caracteres formatada de acordo com o formato especificado:

  • MM/dd/yyyy para 12/31/2016

  • h a para 10pm

Para retornar o dia da semana:

  • EEEE para terça-feira

  • E para Tue

  • u para o índice do dia (1 = segunda-feira, ..., 7 = domingo)

Por exemplo, esta expressão retorna o valor 17:30:00 como 5:30 PM:

${system_current_date}.reformatDateTime('h:mm a')

Se a sequência de entrada incluir apenas um horária, a data padrão 1970-01-01 será usada na saída. Se a sequência de entrada incluir apenas uma data, o horário padrão 12 AM (00:00) será usado.

.before(String date/time)

  • Determina se um valor de data e hora é anterior ao argumento de data e hora especificado, como neste exemplo:

${system_current_date}.before('2021-11-19')

É possível comparar uma data com outra ou um horário com outro. Você também pode comparar uma hora com um valor de data e hora; nesse caso, a data é ignorada e somente as horas são comparadas. Quaisquer outras comparações entre valores incompatíveis (por exemplo, comparar uma data com uma hora) retornam uma falseexceção, que é registrada no output.debug.log_messages sistema (e pode ser vista na visualização do assistente de IA ou nas respostas da API).

.after(String date/time)

  • Determina se o valor de data e hora está após o argumento de data e hora.

.sameMoment(String date/time)

  • Determina se o valor de data e hora é o mesmo que o argumento de data e hora.

.sameOrAfter(String date/time)

  • Determina se o valor de data e hora é posterior ou igual ao argumento de data e hora.

  • Análogo a .after().

.sameOrBefore(String date/time)

  • Determina se o valor de data e hora é anterior ou igual ao argumento de data e hora.

Cálculos de data e hora

Use os métodos a seguir para calcular uma data.

Tabela 1. Cálculos de datas

Método

Descrição

<date>.minusDays(_n_)

Retorna a data correspondente ao dia _n_ dias antes da data especificada.

<date>.minusMonths(_n_)

Retorna a data do dia que corresponde a _n_ meses antes da data especificada.

<date>.minusYears(_n_)

Retorna a data do dia que corresponde a _n_ anos antes da data especificada.

<date>.plusDays(_n_)

Retorna a data correspondente ao dia _n_ dias após a data especificada.

<date>.plusMonths(_n_)

Retorna a data do dia que corresponde a _n_ meses após a data especificada.

<date>.plusYears(n)

Retorna a data do dia _n_ anos após a data especificada.

em que <date> é especificado no formato yyyy-MM-dd ou yyyy-MM-dd HH:mm:ss.

Por exemplo, para obter a data de amanhã, especifique a expressão a seguir:

${system_current_date}.plusDays(1)

Use os métodos a seguir para calcular um horário.

Tabela 2. Cálculos de tempo

Método

Descrição

<time>.minusHours(_n_)

Retorna a hora correspondente a _n_ horas antes da hora especificada.

<time>.minusMinutes(_n_)

Retorna a hora _n_ minutos antes da hora especificada.

<time>.minusSeconds(_n_)

Retorna a hora correspondente a _n_ segundos antes da hora especificada.

<time>.plusHours(_n_)

Retorna a hora _n_ horas após a hora especificada.

<time>.plusMinutes(_n_)

Retorna a hora _n_ minutos após a hora especificada.

<time>.plusSeconds(_n_)

Retorna a hora _n_ segundos após a hora especificada.

em que <time> é especificado no formato HH:mm:ss.

Por exemplo, para obter o horário daqui a uma hora, especifique a expressão a seguir:

 now().plusHours(1)  

Trabalhando com períodos de tempo

Para mostrar uma resposta dependendo se a data de hoje cair dentro de um determinado período de tempo, é possível usar uma combinação de métodos relacionados ao tempo. Por exemplo, se você executar uma oferta especial durante a temporada de férias a cada ano, talvez você queira verificar se a data de hoje cairá entre 25 de novembro e 24 de dezembro deste ano.

Primeiro, defina as datas de interesse como variáveis de sessão. Nas expressões de variável de sessão de data inicial e final a seguir, a data está sendo construída pela concatenação do valor dinâmico do ano atual com valores de dia e mês codificados:

start_date = now().reformatDateTime('Y') + '-12-24'
end_date = now().reformatDateTime('Y') + '-11-25'

Em seguida, em uma condição de etapa, é possível indicar que você deseja mostrar a resposta apenas se a data atual cair entre as datas de início e encerramento definidas como variáveis de sessão:

now().after(${start_date}) && now().before(${end_date})

java.util.Date apoio

Além dos métodos integrados, é possível usar os métodos padrão da classe java.util.Date.

Por exemplo, para obter a data do dia que cairá daqui a uma semana, é possível usar a sintaxe a seguir:

new Date(new Date().getTime() + (7 * (24*60*60*1000L)))

Essa expressão obtém primeiro a data atual em milissegundos (desde 1 de janeiro de 1970, 0h GMT). Ela também calcula o número de milissegundos em 7 dias ((24*60*60*1000L) representa um dia em milissegundos). Em seguida, ele inclui 7 dias na data atual. O resultado é a data completa do dia que cairá daqui a uma semana (por exemplo, Fri Jan 26 16:30:37 UTC 2018).

Métodos de número

Esses métodos ajudam a obter e formatar valores de número.

Para obter informações sobre reconhecimento de números nas respostas do cliente, consulte Escolhendo um tipo de resposta.

Para mudar a posição decimal de um número (por exemplo, para reformatar um número como um valor de moeda), consulte o Método string format().

toDouble()

Converte o objeto ou campo no tipo de número Duplo. Será possível chamar esse método em qualquer objeto ou campo. Se a conversão falhar, null será retornado.

toInt()

Converte o objeto ou campo no tipo de número Inteiro. Será possível chamar esse método em qualquer objeto ou campo. Se a conversão falhar, null será retornado.

toLong()

Converte o objeto ou campo no tipo de número Longo. Será possível chamar esse método em qualquer objeto ou campo. Se a conversão falhar, null será retornado.

Para especificar um tipo de número longo em uma expressão SpEL, deve-se anexar um L ao número para identificá-lo como tal (por exemplo, 5000000000L). Essa sintaxe é necessária para quaisquer números que não se ajustem ao tipo de número inteiro de 32 bits. Os números que são maiores que 2^31 (2.147.483.648) ou menores que -2 (-2.147.483.648) são considerados tipos de números longos. Os tipos de número longo têm um valor mínimo de -2^63 e um valor máximo de 2^63-1 (ou 9.223.372.036.854.775.807).

Matemática padrão

Use expressões SpEL para definir equações de matemática padrão, em que os operadores são representados usando estes símbolos:

Tabela 3. Matemática básica

Operação aritmética

Símbolo

adição

+

divisão

/

multiplicação

*

subtração

-

java.lang.Math()

É possível usar as funções da classe java.lang.Math para realizar operações numéricas básicas.

Você pode usar os métodos da classe, incluindo:

  • max():

    T(Math).max(${step_297},${step_569})
  • min():

    T(Math).min(${step_297},${step_569})
  • pow():

    T(Math).pow(${step_297}.toDouble(),2.toDouble())

Consulte a documentação de referência do ` java.lang.Math ` para obter informações sobre outros métodos.

java.util.Random()

Retorna um número aleatório. É possível usar qualquer uma das opções de sintaxe a seguir:

  • Para retornar um valor booleano aleatório (true ou false), use new Random().nextBoolean().

  • Para retornar um número duplo aleatório entre 0 (incluído) e 1 (excluído), use new Random().nextDouble()

  • Para retornar um número inteiro aleatório entre 0 (incluído) e um número de sua escolha, use new Random().nextInt(_n_), onde _n_ é 1 maior que o limite superior do intervalo numérico desejado. Por exemplo, se quiser retornar um número aleatório entre 0 e 10, especifique new Random().nextInt(11).

  • Para retornar um número inteiro aleatório do intervalo de valores de número inteiro completo (-2147483648 a 2147483648), use new Random().nextInt().

Por exemplo, você pode criar uma etapa que é executada apenas para um subconjunto aleatoriamente selecionado de clientes. A condição de etapa a seguir significaria que a etapa tem 50% de chance de ser executada:

new Random().nextInt(2) == 1

Consulte a documentação de referência do ` java.util.Random ` para obter informações sobre outros métodos.

Também é possível usar métodos padrão das classes a seguir:

  • java.lang.Byte

  • java.lang.Integer

  • java.lang.Long

  • java.lang.Double

  • java.lang.Short

  • java.lang.Float

Métodos de sequência

Esses métodos ajudam a trabalhar com texto.

Para obter detalhes sobre a sintaxe a ser usada em métodos que envolvem expressões regulares, consulte a Referência de sintaxe do RE2.

String.append(Object)

Este método anexa um objeto de entrada (como uma sequência) a uma sequência e retorna uma sequência modificada.

${step_297}.append('next text')

String.contains(String)

Esse método retorna ' true se a variável de ação ou a variável de sessão contiver uma substring, o que é útil em condições.

${step_297}.contains('Yes')

String.endsWith(String)

Este método retornará true se a sequência terminar com a subsequência de entrada.

${step_297}.endsWith('?')

String.equals(String)

Este método retornará true se a sequência especificada for igual a variável de ação ou variável de sessão.

${step_297}.equals('Yes')

String.equalsIgnoreCase(String)

Este método retornará true se a sequência especificada for igual à variável de ação ou variável de sessão, independentemente do caso.

${step_297}.equalsIgnoreCase('Yes')

String.extract(String regexp, Integer groupIndex)

Este método retornará uma sequência da entrada que corresponde ao padrão de grupo de expressão regular especificado. Ele retorna uma sequência vazia caso nenhuma correspondência seja localizada.

Esse método foi projetado para extrair correspondências para diferentes grupos de padrões de expressão regular, não diferentes correspondências para um único padrão de expressão regular. Para encontrar correspondências diferentes, consulte o método getMatch().

Neste exemplo, a variável de ação está salvando uma sequência que corresponde ao grupo de padrões de expressão regular especificado. Na expressão, dois grupos de padrões de expressão regular são definidos, ambos entre parênteses. Inerente é um terceiro grupo que é composto pelos dois grupos. Esse é o primeiro grupo regexgroupIndex 0); ele corresponde a uma string que contém o grupo de números completos e o grupo de texto. O segundo grupo de expressão regular (groupIndex 1) corresponde à primeira ocorrência de um grupo de números. O terceiro grupo (groupIndex 2) corresponde à primeira ocorrência de um grupo de texto após um grupo de números.

${step_297}.extract('([\d]+)(\b [A-Za-z]+)', <n>)

Se a variável de ação contiver:

Hello 123 this is 456.

os resultados serão os seguintes:

  • Quando " <n>=0, o valor é " 123 this.

  • Quando " <n>=1, o valor é " 123.

  • Quando " <n>=2, o valor é " this.

String.find(String regexp)

Este método retornará true se algum segmento da sequência corresponder à expressão regular de entrada. Você pode chamar esse método em um elemento JSONArray ou JSONObject, e ele converte o array ou objeto em uma string antes de fazer a comparação.

Por exemplo, se a variável de ação ' ${step_297} coletar a string ' Hello 123456, a expressão a seguir retornará ' true:

${step_297}.find('^[^\d]*[\d]{6}[^\d]*$')

A condição é true, pois a parte numérica do texto de entrada corresponde à expressão regular ^[^\d]*[\d]{6}[^\d]*$.

String.getMatch(String regexp, Integer matchIndex)

Este método retornará uma sequência que corresponde à ocorrência do padrão de expressão regular especificado. Ele retorna uma sequência vazia caso nenhuma correspondência seja localizada.

À medida que as correspondências são localizadas, elas são incluídas no que pode ser considerado uma matriz de correspondências. Como a contagem de elementos da matriz começa em zero, para retornar a terceira correspondência, você especificaria dois como o valor matchIndex. Por exemplo, ao inserir uma sequência de texto com três palavras que correspondem ao padrão especificado, é possível retornar a primeira, a segunda ou a terceira correspondência apenas especificando seu valor de índice.

Por exemplo, o exemplo a seguir está procurando um grupo de números em uma variável de ação.

${step_297}.getMatch('([\d]+)', 1)

Se a variável de ação ${step_297} contiver a sequência hello 123 i said 456 and 8910, esta expressão retornará 456.

String.isEmpty()

Este método retornará true se a sequência for uma sequência vazia, mas não null, como neste exemplo:

${step_297}.isEmpty()

String.length()

Este método retorna o comprimento de caracteres da sequência, como neste exemplo:

${step_297}.length()

Se a variável de ação ${step_297} contiver a sequência Hello, esta expressão retornará cinco.

String.matches(String regexp)

Este método retornará true se a sequência corresponder à expressão regular de entrada, como no exemplo:

${step_297}.matches('^Hello$')

Se a variável de ação ${step_297} contiver a sequência Hello, esta expressão será avaliada para true.

String.startsWith(String)

Este método retornará true se a sequência começar com a subsequência especificada, como neste exemplo:

${step_297}.startsWith('What')

Se a variável de ação ${step_297} contiver a sequência What is your name?, esta expressão retornará true.

String.substring(Integer beginIndex, Integer endIndex)

Este método retorna uma subsequência começando com o caractere em beginIndex e terminando com o caractere antes de endIndex. (O próprio caractere endIndex não está incluído na subsequência.) Os valores de índice são baseados em zero, portanto, o primeiro caractere da cadeia de caracteres está no índice 0.

Este exemplo retorna uma subsequência que começa no índice cinco (que é o sexto caractere) e continua até o final da sequência:

${step_297}.substring(5, ${step_297}.length())

Se a variável de ação ${step_297} contiver a sequência This is a string., esta expressão retornará is a string.

String.toJson()

Esse método analisa uma cadeia de caracteres que contém dados JSON e retorna um objeto ou matriz JSON, como neste exemplo:

${json_var}.toJson()

Se a variável de sessão ' ${json_var} contiver a seguinte cadeia de caracteres:

"{ \"firstname\": \"John\", \"lastname\": \"Doe\" }"

o método ' toJson() retorna o seguinte objeto:

{
  "firstname": "John",
  "lastname": "Doe"
}

String.toLowerCase()

Esse método retorna a cadeia de caracteres especificada que é convertida em letras minúsculas, como neste exemplo:

${step_297}.toLowerCase()

Se a variável de ação ${step_297} contiver a sequência This is A DOG!, esta expressão retornará a sequência this is a dog!.

String.toUpperCase()

Esse método retorna a cadeia de caracteres original que é convertida em letras maiúsculas, como neste exemplo:

${step_297}.toUpperCase()

Se a variável de ação ${step_297} contiver a sequência hi there, este método retornará a sequência HI THERE.

String.trim()

Este método remove quaisquer espaços no início e no fim de uma sequência e retorna a sequência modificada, como neste exemplo:

${step_297}.trim()

Se a variável de ação ${step_297} contiver a sequência something is here , este método retornará a sequência something is here.

java.lang.String apoio

Além dos métodos integrados, é possível usar os métodos padrão da classe java.lang.String.

java.lang.String.format()

É possível aplicar o método de Sequência Java padrão format() ao texto. Para obter informações sobre a sintaxe a ser usada, consulte Sintaxe da string de formato.

Este exemplo usa três números inteiros decimais (1, 1 e 2) e os inclui em uma sentença:

T(java.lang.String).format('%d + %d equals %d', 1, 1, 2)

A sequência resultante é 1 + 1 equals 2.

Este exemplo altera a colocação decimal de um número coletado por uma etapa:

T(String).format('%.2f',${step_297})

Se a variável ${step_297} que precisa ser formatada em dólares dos EUA for 4,5, a sequência resultante será 4.50.

Métodos de matriz

Esses métodos o ajudam a trabalhar com matrizes.

Array.add(value...)

Esse método adiciona um ou mais valores novos à matriz e retorna ' true se a operação for bem-sucedida.

${Items}.add('four', 'five')

Se " Items for " ['one', 'two', 'three'], este exemplo o atualiza no lugar para se tornar " ['one', 'two', 'three', 'four', 'five'].

Array.addAll(Array array)

Esse método adiciona uma matriz a outra e retorna ' null.

${Items}.addAll(${New_items})

Se " Items for " ['one', 'two', 'three'] e " New_items for " ['four', 'five', 'six'], este exemplo atualiza " Items no lugar para se tornar " ['one', 'two', 'three', 'four', 'five', 'six'].

Array.append(value...)

Esse método acrescenta um ou mais valores novos à matriz e retorna o resultado como uma nova matriz. A matriz original não é modificada.

${Items}.append('four', 'five')

Se " Items for " ['one', 'two', 'three'], esse exemplo retornará a nova matriz " ['one', 'two', 'three', 'four', 'five'].

Array.clear()

Esse método remove todos os valores da matriz e retorna null.

${Items}.clear()

Depois que essa expressão é avaliada, ' Items é uma matriz vazia ([]).

Array.contains(value)

Esse método retorna ' true se a matriz contiver um item que seja exatamente igual ao valor de entrada. O valor especificado pode ser uma cadeia de caracteres ou um número.

${Items}.contains(123)

Se " Items for " [123, 456, 789], este exemplo retornará " true.

Array.containsIgnoreCase(value)

Esse método retorna ' true se a matriz contiver um item que seja igual ao valor de entrada. As cadeias de caracteres são combinadas independentemente de o valor ser especificado em letras maiúsculas ou minúsculas. O valor especificado pode ser uma cadeia de caracteres ou um número.

${Items}.contains('two')

Esse exemplo retorna ' true se a matriz ' Items contiver qualquer capitalização da string ' two (por exemplo, ' TWO ou ' Two também corresponderiam).

Array.filter(temp_var, "temp_var.property operator comparison_value")

Filtra uma matriz comparando cada elemento da matriz com um valor especificado por você, retornando uma nova matriz que contém apenas os elementos correspondentes.

A expressão de filtro consiste nos valores a seguir:

  • temp_var: Um nome arbitrário para uma variável temporária que é usada para manter cada elemento do array à medida que ele é avaliado. Por exemplo, se a matriz original contiver objetos que descrevem cidades, você poderá usar " city como o nome da variável temporária.

  • property: A propriedade do elemento que você deseja filtrar. Essa deve ser uma propriedade dos elementos da matriz de origem. Especifique a propriedade como uma propriedade de ' temp_var, usando a sintaxe ' temp_var.property. Por exemplo, se " latitude for um nome de propriedade válido para os elementos de origem, você poderá especificar a propriedade como " city.latitude.

  • operator: O operador a ser usado para comparar o valor da propriedade com o valor de comparação. Você pode usar qualquer um dos seguintes operadores:

Tabela 4. Operadores de filtro suportados

Operador

Descrição

==

É igual a

>

é maior do que

<

é menor do que

>=

é maior do que ou igual a

<=

é menor do que ou igual a

!=

Não é igual a

  • comparison_value: O valor com o qual você deseja comparar o valor da propriedade de cada elemento da matriz. Você pode especificar um valor literal ou fazer referência a uma variável.

Exemplos de Filtro

Por exemplo, você pode ter uma matriz de objetos que contém nomes de cidades e seus números de população:

[
   {
      "name":"Tokyo",
      "population":13988129

   },
   {
      "name":"Rome",
      "population":2860009

   },
   {
      "name":"Beijing",
      "population":21893095

   },
   {
      "name":"Paris",
      "population":2165423

   }
]

Se a matriz de origem for armazenada em uma variável chamada ' ${cities}, a expressão a seguir retornará uma matriz menor que contém apenas cidades com população superior a 5 milhões:

${cities}.filter("city", "city.population > 5000000")

A expressão retorna a matriz filtrada a seguir:

[
   {
      "name":"Tokyo",
      "population":13988129

   },
   {
      "name":"Beijing",
      "population":21893095

   }
]

Em vez de um valor de comparação codificado, você também pode filtrar com base em um valor dinâmico armazenado em uma variável. Este exemplo filtra usando um valor de população que é especificado por uma resposta do cliente em uma etapa anterior:

${cities}.filter("city", "city.population > ${step_123}")

Quando você comparar valores numéricos, certifique-se de definir a variável de contexto envolvida na comparação como um valor válido antes que o método de filtro seja acionado. Observe que null poderá ser um valor válido se o elemento de matriz com o qual você estiver comparando puder contê-lo.

Array.get(Integer index)

Esse método retorna o item da matriz que está na posição de índice especificada. As matrizes são indexadas a zero, o que significa que o primeiro item da matriz está na posição de índice ' 0.

${Items}.get(1)

Se " Items for " ['one', 'two', 'three'], este exemplo retornará " two.

O método " get() é uma alternativa ao uso de colchetes ([]) para recuperar um item de uma matriz. O exemplo a seguir também é válido e retorna o mesmo resultado:

${Items}[1]

Se estiver usando um valor especificado por um cliente para escolher um item de uma matriz, talvez seja necessário subtrair 1 para converter em um valor com índice zero. Por exemplo, você pode usar uma expressão como " ${Items}.get(${step_123} - 1) para recuperar o valor pretendido.

Array.getRandomItem()

Esse método retorna um item escolhido aleatoriamente da matriz.

${Items}.getRandomItem()

Se " Items for " ['one', 'two', 'three'], esse exemplo retornará " one, " two ou " three, de forma aleatória.

Array.indexOf(value)

Esse método retorna a posição do índice da primeira ocorrência do valor de entrada na matriz ou ' -1 se a matriz não contiver o valor de entrada. O valor especificado pode ser uma cadeia de caracteres ou um número.

${Items}.indexOf(`two`)

Se ' Items for ' ['one', 'two', 'three'], esse exemplo retornará o número inteiro ' 1 (indicando a segunda posição na matriz com índice zero).

Array.join(String delimiter)

Esse método reúne todos os valores nessa matriz para uma sequência. Os valores são convertidos em sequência e delimitados pelo delimitador de entrada.

Por exemplo, você pode usar uma variável chamada ' pizza_toppings que contém a matriz ' ["pepperoni", "ham", "mushrooms"]. A expressão a seguir converte essa matriz na string ' pepperoni, ham, mushrooms:

${toppings_array}.join(', ')

Se você usar essa expressão para definir o valor de uma variável, poderá então fazer referência a essa variável na saída do seu assistente de IA para criar uma mensagem legível por humanos (por exemplo, You have selected the following toppings: pepperoni, ham, mushrooms).

JSONArray.joinToArray(template, retainDataType)

Esse método extrai informações de cada item da matriz e cria uma nova matriz formatada de acordo com o modelo que você especificar. O modelo pode ser uma string, um objeto JSON ou uma matriz. O método retorna uma matriz de cadeias de caracteres, uma matriz de objetos ou uma matriz de matrizes, dependendo do tipo de modelo.

Esse método é útil para formatar informações como uma cadeia de caracteres que você pode retornar como parte da saída de uma etapa ou para transformar dados em uma estrutura diferente, de modo que você possa usá-los com uma API externa.

No modelo, você pode fazer referência a valores da matriz de origem usando a seguinte sintaxe:

%e.{property}%

em que " {property} representa o nome da propriedade na matriz de origem.

Por exemplo, suponha que seu assistente de IA armazene uma matriz contendo detalhes de voos em uma variável de sessão. Os dados armazenados podem ter a seguinte aparência:

"flights": [
      {
        "flight": "AZ1040",
        "origin": "JFK",
        "carrier": "Alitalia",
        "duration": 485,
        "destination": "FCO",
        "arrival_date": "2019-02-03",
        "arrival_time": "07:00",
        "departure_date": "2019-02-02",
        "departure_time": "16:45"
      },
      {
        "flight": "DL1710",
        "origin": "JFK",
        "carrier": "Delta",
        "duration": 379,
        "destination": "LAX",
        "arrival_date": "2019-02-02",
        "arrival_time": "10:19",
        "departure_date": "2019-02-02",
        "departure_time": "07:00"
      },
      {
        "flight": "VS4379",
        "origin": "BOS",
        "carrier": "Virgin Atlantic",
        "duration": 385,
        "destination": "LHR",
        "arrival_date": "2019-02-03",
        "arrival_time": "09:05",
        "departure_date": "2019-02-02",
        "departure_time": "21:40"
      }
    ]

Para criar uma matriz de strings que descreva esses voos em um formato legível pelo usuário, você pode usar a seguinte expressão:

${Flight_data}.joinToArray("Flight %e.flight% to %e.destination%", true)

Essa expressão retornaria a seguinte matriz de cadeias de caracteres: ' ["Flight AZ1040 to FCO","Flight DL1710 to LAX","Flight VS4379 to LHR"].

O parâmetro opcional ' retainDataType especifica se o método preserva o tipo de dados de todos os valores de entrada na matriz retornada. Se ' retainDataType for definido como ' false ou omitido, em algumas situações, as cadeias de caracteres na matriz de entrada poderão ser convertidas em números na matriz retornada. Por exemplo, se os valores selecionados da matriz de entrada forem " "1", " "2" e " "3", a matriz retornada poderá ser " [ 1, 2, 3 ]. Para evitar conversões de tipo inesperadas, especifique ' true para esse parâmetro.

Modelos complexos

Um modelo mais complexo pode conter formatação que exibe as informações em um layout legível. Para um modelo complexo, talvez você queira armazenar o modelo em uma variável de sessão, que pode ser passada para o método ' joinToArray em vez de uma cadeia de caracteres.

Por exemplo, esse modelo complexo contém um subconjunto dos elementos da matriz, adicionando rótulos e formatação:

<br/>Flight number: %e.flight% <br/> Airline: %e.carrier% <br/> Departure date: %e.departure_date% <br/> Departure time: %e.departure_time% <br/> Arrival time: %e.arrival_time% <br/>

Certifique-se de que toda a formatação utilizada no seu modelo seja compatível com a integração do canal que exibe a resposta do assistente de IA.

Se você criar uma variável de sessão chamada ' Template e atribuir esse modelo como seu valor, poderá usar essa variável em suas expressões:

${Flight_data}.joinToArray(${Template})

Em tempo de execução, a resposta teria a seguinte aparência:

Flight number: AZ1040
Airline: Alitalia
Departure date: 2019-02-02
Departure time: 16:45
Arrival time: 07:00

Flight number: DL1710
Airline: Delta
Departure date: 2019-02-02
Departure time: 07:00
Arrival time: 10:19

Flight number: VS4379
Airline: Virgin Atlantic
Departure date: 2019-02-02
Departure time: 21:40
Arrival time: 09:05

Modelos JSON

Em vez de uma cadeia de caracteres, você pode definir um modelo como um objeto JSON, que oferece uma maneira de padronizar a formatação de informações de diferentes sistemas ou de transformar dados no formato necessário para um serviço externo.

Neste exemplo, um modelo é definido como um objeto JSON que extrai os detalhes do voo dos elementos especificados na matriz armazenada na variável de sessão " Flight data:

{
  "departure": "Flight %e.flight% departs on %e.departure_date% at %e.departure_time%.",
  "arrival": "Flight %e.flight% arrives on %e.arrival_date% at %e.arrival_time%."
}

Usando esse modelo, o método ' joinToArray() retorna uma nova matriz de objetos com a estrutura especificada.

Array.remove(Integer index)

Esse método remove da matriz o item na posição de índice especificada e retorna a matriz atualizada.

${Items}.remove(1)

Se " Items for " ['one', 'two', 'three'], este exemplo retornará " ['one', 'three']. A matriz original ' Items também é modificada no lugar.

Array.removeValue(value)

Esse método remove a primeira ocorrência do valor especificado da matriz e retorna a matriz atualizada. O valor especificado pode ser uma cadeia de caracteres ou um número.

${Items}.removeValue('two')

Se " Items for " ['one', 'two', 'three'], este exemplo retornará " ['one', 'three']. A matriz original ' Items também é modificada no lugar.

Array.set(Integer index, value)

Esse método substitui o item na posição de índice especificada pelo valor especificado e retorna a matriz atualizada.

${Items}.set(2,'five')

Se " Items for " ['one', 'two', 'three'], este exemplo retornará " ['one', 'two', 'five']. A matriz original ' Items também é modificada no lugar.

Array.size()

Esse método retorna o número de itens na matriz como um número inteiro.

${Items}.size()

Se " Items for " ['one', 'two', 'three'], este exemplo retornará " 3.

Array.sort()

Esse método faz uma classificação no local e retorna a matriz classificada. O parâmetro padrão é ' ascending. Você pode especificar " descending para alterar a ordem de classificação. Qualquer outra entrada de parâmetro é ignorada e um erro de registro é exibido.

${Items}.sort("ascending")

O método compara números e cadeias de caracteres. Um número é sempre menor que uma string. Qualquer outro tipo é convertido em string por padrão para comparação.

Por exemplo:

Tabela 5. Exemplos de classificação

Matriz original

Matriz ordenada

[2,1,3,5,4,3,2]

[1,2,2,3,3,4,5]

["Banana", "Laranja", "Maçã", "Manga"]

["Maçã", "Banana", "Manga", "Laranja"]

[3, 2, 4, "1", "10", "12", "Banana", "Laranja", 0, "Maçã", "Manga"]

[0, 2, 3, 4, "1", "10", "12", "Maçã", "Banana", "Manga", "Laranja"]

Array.transform()

O método ' Array.transform() é usado somente com a variável 'session_history. Você pode transformar a saída da variável para corresponder a um sistema de IA generativo específico.

Tabela: Assinaturas para formatos de bate-papo mostra as assinaturas que você pode usar para os diferentes formatos de bate-papo:

Tabela 6. Tabela: Assinaturas para formatos de bate-papo

Particularidades

OpenAI

Google PaLM2

Llama2

Assinatura

``transform(String rolePrefix, String userPrefix, String assistantPrefix, optional Boolean currentAction=false)``

``transform(String rolePrefix, String userPrefix, String assistantPrefix, optional Boolean currentAction=false)``

``transform(optional String systemPrompt, optional Boolean currentAction=false)``

Formato da mensagem do cliente

``{$rolePrefix: $userPrefix, "content": $content}``

``{$rolePrefix: $userPrefix, "content": $content}``

``<s>[INST] <<SYS>>{{ $systemPrompt }} <</SYS>>{{ $user_content }} [/INST] {{ $assistant_content }} </s><s>[INST] {{ $user_content }} [/INST]``

Formato da mensagem do assistente

``{$rolePrefix: $assistantPrefix, "content": $content}``

``{$rolePrefix: $assistantPrefix, "content": $content}``

N/D

Exemplo

``${system_session_history}.transform("role", "user", "assistant")``

``${system_session_history}.transform("author", "USER", "AI")``

``${system_session_history}.transform("<your system prompt>")``

Se ' currentAction for verdadeiro:

Tabela 7. Se currentAction for verdadeiro

Usos do assistente de IA

Descrição

Somente ações

A transformação exclui todas as mensagens em que " né verdadeiro, o que indica que uma pergunta do cliente acionou uma nova ação de base.

Somente diálogo

currentAction é ignorado e a transformação inclui todo o conteúdo da variável ' session history.

Diálogo e ações

A transformação inclui tudo o que está na variável ' session_history desde o início mais recente de uma ação, independentemente de qualquer nó de diálogo ter sido acionado.

Os sinalizadores ' n : true não são incluídos na saída do transform.