Métodos de linguagem de expressão para ações
A linguagem de expressão do watsonx Assistant 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ão watsonx Assistant é baseada na Spring Expression Language SpEL ), mas com algumas diferenças importantes na sintaxe. Para obter informações detalhadas sobre o SpEL, consulte Spring Expression Language(SpEL).
É possível usar expressões SpEL de duas maneiras:
- Definindo uma condição de etapa. Para obter mais informações, consulte Gravando expressões.
- Designando um valor a uma variável de sessão. Para obter mais informações, consulte Usando variáveis para gerenciar informações da conversa.
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 o 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:
timepercentagecurrency
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').
Neste exemplo, se a data e hora atuais forem 2021-11-26 11:41:00, a cadeia 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 mudança no formato da cadeia de saída também é aplicável aos métodos de cálculo de data e hora. Por exemplo, se a sequência <date> usada estiver no formato yyyy-MM-dd HH:mm:ss, como quando você usar o método
today(), a saída estará no mesmo formato (yyyy-MM-dd HH:mm:ss). No entanto, se a sequência <date> estiver no formato yyyy-MM-dd HH:mm:ss 'GMT'XXX, como quando você usar 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 formato 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/yyyypara 12/31/2016h apara 10pm
Para retornar o dia da semana:
EEEEpara terça-feiraEpara o Tueupara í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 de valores incompatíveis
(por exemplo, comparar uma data com um horário) retornam false; uma exceção é registrada em output.debug.log_messages (o que pode ser visto na visualização do assistente ou em respostas de API).
.after(String date/time)
- Determina se o valor de data e hora é posterior ao argumento de data e hora
.sameMoment(String date/time)
- Determina se o valor de data e hora é igual ao 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.
| Método | Descrição |
|---|---|
<date>.minusDays(_n_) |
Retorna a data do dia n dias antes da data especificada. |
<date>.minusMonths(_n_) |
Retorna a data do dia n meses antes da data especificada. |
<date>.minusYears(_n_) |
Retorna a data do dia n anos antes da data especificada. |
<date>.plusDays(_n_) |
Retorna a data do dia n dias após a data especificada. |
<date>.plusMonths(_n_) |
Retorna a data do dia 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.
| Método | Descrição |
|---|---|
<time>.minusHours(_n_) |
Retorna o horário n horas antes do horário especificado. |
<time>.minusMinutes(_n_) |
Retorna o horário n minutos antes do horário especificado. |
<time>.minusSeconds(_n_) |
Retorna o horário n segundos antes do horário especificado. |
<time>.plusHours(_n_) |
Retorna o horário n horas depois do horário especificado. |
<time>.plusMinutes(_n_) |
Retorna o horário n minutos depois do horário especificado. |
<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})
Suporte java.util.Date
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:
| 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 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 (
trueoufalse), usenew 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 que você especificar, use
new Random().nextInt(_n_), em que n é um maior que o topo do intervalo de números desejado. Por exemplo, se quiser retornar um número aleatório entre 0 e 10, especifiquenew 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 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.Bytejava.lang.Integerjava.lang.Longjava.lang.Doublejava.lang.Shortjava.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 Referência de sintaxe 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 variável de sessão contiver uma subsequência, 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 regex groupIndex 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 sequência 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()
Este método analisa uma sequência 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 sequência:
"{ \"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.
Suporte java.lang.String
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 de Sequência 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 o posicionamento 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 ajudam você a trabalhar com matrizes.
Array.add(value...)
Esse método inclui um ou mais novos valores na matriz e retornará true se a operação for bem-sucedida
${Items}.add('four', 'five')
Se Items for ['one', 'two', 'three'], este exemplo o atualizará no local para se tornar ['one', 'two', 'three', 'four', 'five']
Array.addAll(Array array)
Esse método inclui uma matriz em outra, e retorna null
${Items}.addAll(${New_items})
Se Items for ['one', 'two', 'three'] e New_items for ['four', 'five', 'six'], este exemplo atualizará Items no local para se tornar ['one', 'two', 'three', 'four', 'five', 'six']
Array.append(value...)
Este método anexa um ou mais novos valores para a matriz e retorna o resultado como uma nova matriz A matriz original não foi modificada
${Items}.append('four', 'five')
Se Items for ['one', 'two', 'three'], este 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()
Após essa expressão ser avaliada, Items é uma matriz vazia ([]).
Array.contains(value)
Esse método retornará true se a matriz contiver um item que seja exatamente igual ao valor de entrada O valor especificado pode ser uma sequência 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 igual ao valor de entrada. As sequências são correspondidas independentemente de o valor ser especificado em letras maiúsculas ou minúsculas. O valor especificado pode ser
uma sequência ou um número.
${Items}.contains('two')
Este exemplo retorna true se a matriz Items contiver qualquer capitalização da cadeia two (por exemplo, TWO ou Two também corresponderia).
Array.filter(temp_var, "temp_var.property operator comparison_value")
Filtra uma matriz comparando cada elemento de matriz com um valor especificado, 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 de matriz conforme ele é avaliado... Por exemplo, se a matriz original contiver objetos que descrevem cidades, você poderá usarcitycomo o nome da variável temporária. -
property: A propriedade do elemento que você deseja filtrar. Essa deve ser uma propriedade dos elementos na matriz de origem Especifique a propriedade como uma propriedade detemp_varusando a sintaxetemp_var.property. Por exemplo, selatitudefor um nome de propriedade válido para os elementos de origem, você poderá especificar a propriedade comocity.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:Operadores de filtro suportados Operador Descrição ==É igual a >é maior do que <é menor do que >=É maior ou igual a <=É menor do que ou igual a !=Não é igual a -
comparison_value: O valor com o qual você deseja comparar cada valor de propriedade do 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 contenha apenas cidades com populações maiores que 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 permanentemente, você também pode filtrar com base em um valor dinâmico armazenado em uma variável. Este exemplo filtra usando um valor de preenchimento 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)
Este método retorna o item da matriz que está na posição de índice especificada As matrizes têm índice zero, o que significa que o primeiro item na 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 você estiver usando um valor que é especificado por um cliente para escolher um item de uma matriz, poderá ser necessário subtrair 1 para converter em um valor zero indexado. Por exemplo, você pode usar uma expressão como ${Items}.get(${step_123} - 1) para recuperar o valor desejado.
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, aleatoriamente.
Array.indexOf(value)
Este método retorna a posição de í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 sequência ou um número.
${Items}.indexOf(`two`)
Se Items for ['one', 'two', 'three'], este exemplo retornará o número inteiro 1 (indicando a segunda posição na matriz indexada 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 denominada pizza_toppings que contém a matriz ["pepperoni", "ham", "mushrooms"]. A expressão a seguir converte essa matriz na cadeia pepperoni, ham, mushrooms:
${toppings_array}.join(', ')
Se você usar essa expressão para definir o valor de uma variável, será possível fazer referência a essa variável em sua saída do assistente para criar uma mensagem legível (por exemplo, You have selected the following toppings: pepperoni, ham, mushrooms).
JSONArray.joinToArray(template, retainDataType)
Esse método extrai informações de cada item na matriz e constrói uma nova matriz que é formatada de acordo com o modelo especificado. O modelo pode ser uma sequência, um objeto JSON ou uma matriz.. O método retorna uma matriz de sequências, uma matriz de objetos ou uma matriz de matrizes, dependendo do tipo de modelo..
Esse método é útil para formatar informações como uma sequência que você pode retornar como parte da saída de uma etapa, ou para transformar dados em uma estrutura diferente para que você possa usá-la com uma API externa
No modelo, é possível referenciar valores da matriz de origem usando a sintaxe a seguir:
%e.{property}%
em que {property} representa o nome da propriedade na matriz de origem..
Por exemplo, suponha que seu assistente armazene uma matriz que contenha detalhes de voo em uma variável de sessão. Os dados armazenados podem ser semelhantes a este:
"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 construir uma matriz de sequências que descrevem esses voos em um formato legível pelo usuário, é possível usar a expressão a seguir:
${Flight_data}.joinToArray("Flight %e.flight% to %e.destination%", true)
Essa expressão retornaria a seguinte matriz de cadeias: ["Flight AZ1040 to FCO","Flight DL1710 to LAX","Flight VS4379 to LHR"].
O parâmetro retainDataType opcional especifica se o método preserva o tipo de dados de todos os valores de entrada na matriz retornada Se retainDataType for configurado como false ou omitido, em algumas
situações, as sequências 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, você pode desejar armazenar o modelo em uma variável de sessão, que você pode então passar para o método joinToArray em vez de uma cadeia.
Por exemplo, esse modelo complexo contém um subconjunto dos elementos de matriz, incluindo 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 qualquer formatação usada em seu modelo seja suportada pela integração de canal que exibe a saída do assistente.
Se você criar uma variável de sessão denominada Template e designar esse modelo como seu valor, será possível 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 sequência, é possível definir um modelo como um objeto JSON, que fornece 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 detalhes de voo dos elementos especificados na matriz que está 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 Items original também é modificada no local..
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 sequência ou um número.
${Items}.removeValue('two')
Se Items for ['one', 'two', 'three'], este exemplo retornará ['one', 'three'] A matriz Items original também é modificada no local..
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 Items original também é modificada no local..
Array.size()
Este 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. É possível especificar descending para alterar a ordem de classificação.. Qualquer outra entrada de parâmetro
é ignorada e um erro de log é exibido
${Items}.sort("ascending")
O método compara números e sequências. Um número é sempre menor do que uma cadeia. Qualquer outro tipo é convertido em sequência por padrão para comparar.
Por exemplo:
| Matriz original | Matriz classificada |
|---|---|
| [2,1,3,5,4,3,2] | [1,2,2,3,4,5] |
| ["Banana", "Orange", "Apple", "Mango"] | ["Apple", "Banana", "Mango", "Orange"] |
| [3, 2, 4, "1", "10", "12", "Banana", "Orange", 0, "Apple", "Mango"] | [0, 2, 3, 4, "1", "10", "12", "Apple", "Banana", "Mango", "Orange"] |
Array.transform()
O método Array.transform() é usado com o Variável session_history apenas. É possível transformar a saída da variável para
corresponder a um sistema de IA gerador específico.
Tabela: Assinaturas para formatos de bate-papo mostra assinaturas que podem ser usadas para os diferentes formatos de bate-papo:
| Informações | 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::
| Usos do assistente | Descrição |
|---|---|
| Apenas ações | A transformação exclui todas as mensagens em que n é true, o que indica que uma questão do cliente acionou uma nova ação de base |
| Apenas diálogo | currentAction é ignorada e a conversão inclui o conteúdo inteiro da variável session history. |
| Diálogo e ações | A conversão inclui tudo na variável session_history desde o início mais recente de uma ação, independentemente de quaisquer nós de diálogo serem acionados. |
Os sinalizadores n : true não são incluídos na saída da conversão..