Métodos de lenguaje de expresión para acciones
El lenguaje de expresión de watsonx Assistant se puede utilizar para especificar valores que son independientes o derivados de valores que se recopilan en pasos o se almacenan en variables de sesión. Puede utilizar una expresión para definir una condición de paso o para definir el valor de una variable de sesión.
El lenguaje de expresión watsonx Assistant está basado en el Lenguaje de Expresión de Spring SpEL ), pero con algunas diferencias importantes en la sintaxis. Para obtener información detallada sobre SpEL, consulte Spring Expression Language(SpEL).
Puede utilizar expresiones SpEL de dos maneras:
- Definiendo una condición de paso. Para obtener más información, consulte Cómo escribir expresiones.
- Asignando un valor a una variable de sesión. Para obtener más información, consulte Utilización de variables para gestionar la información de conversación.
Referencia a variables de acción
Una variable de acción se crea implícitamente para cualquier paso que espera la entrada del cliente, y la variable está enlazada al paso. Para hacer referencia a una variable de acción dentro de una expresión, debe especificar el ID del paso
utilizando el formato ${step_id}
(por ejemplo, ${step_771}
. Para buscar el ID de paso de un paso, seleccione el paso y, a continuación, busque el final del URL en el navegador.
Referencia a variables de sesión
Las variables de sesión se crean explícitamente en la sección Variables del paso. Para hacer referencia a una variable de sesión dentro de una expresión, debe especificar el ID de la variable utilizando el formato ${variable_id}
(por ejemplo, ${current_time}
. Puede encontrar el ID de variable en la lista de variables. (Para obtener más información, consulte Utilización de variables para gestionar la información de conversación).
Cuando esté editando una expresión, puede escribir $
para ver una lista de variables a las que puede hacer referencia. Seleccione una variable de la lista para insertar automáticamente el ID de paso o el ID de variable.
Tipos de datos soportados
Las expresiones pueden utilizar tipos JSON atómicos (como integer
, string
, number
, y boolean
), y tipos de datos compuestos (como matrices JSON ( []
) y objetos ( {}
). Cuando especifique valores literales de cadena, puede utilizar comillas simples ( '
) o dobles ( "
).
Los valores que los pasos de acción recopilan de los clientes utilizan tipos de respuesta del cliente como, por ejemplo, fecha, hora, moneda o porcentaje. Estos valores se almacenan como objetos JSON en el formato siguiente:
{
"system_type": "{system_type}",
"value": "{value}"
}
donde {system_type}
es uno de los tipos siguientes:
time
percentage
currency
Métodos de fecha y hora
Hay varios métodos disponibles para trabajar con valores de fecha y hora.
now(String timezone)
El método now()
devuelve la fecha y hora actuales para un huso horario especificado, en el formato yyyy-MM-dd HH:mm:ss 'GMT'XXX
:
now('Australia/Sydney').
En este ejemplo, si la fecha y hora actuales son 2021-11-26 11:41:00
, la serie devuelta es 2021-11-26 21:41:00 GMT+10.00
o 2021-11-26 21:41:00 GMT+11.00
en función del horario de verano.
El cambio de formato de serie de salida también es aplicable a los métodos de cálculo de fecha y hora. Por ejemplo, si la serie <date>
utilizada está en el formato yyyy-MM-dd HH:mm:ss
, como cuando se utiliza
el método today()
, la salida está en el mismo formato (yyyy-MM-dd HH:mm:ss
). Sin embargo, si la serie <date>
está en el formato yyyy-MM-dd HH:mm:ss 'GMT'XXX
, como cuando se utiliza
el método now()
, la salida está en el formato yyyy-MM-dd HH:mm:ss 'GMT'XXX
.
.reformatDateTime(String format)
Formatea las series de fecha y hora para la salida. El parámetro es una cadena de formato que especifica cómo se formatea el valor de la fecha o la hora. La cadena de formato debe especificarse utilizando la sintaxis Java SimpleDateFormat.
Este método devuelve una cadena formateada según el formato especificado:
MM/dd/yyyy
para 12/31/2016h a
para 10pm
Para devolver el día de la semana:
EEEE
para martesE
para Tueu
para índice de días (1 = lunes, ..., 7 = domingo)
Por ejemplo, esta expresión devuelve el valor 17:30:00 como 5:30 PM
:
${system_current_date}.reformatDateTime('h:mm a')
Si la serie de entrada incluye sólo la hora, se utiliza la fecha predeterminada 1970-01-01
en la salida. Si la serie de entrada incluye sólo una fecha, se utiliza la hora predeterminada 12 AM (00:00)
.
.before(String date/time)
- Determina si un valor de fecha y hora es anterior al argumento de fecha y hora especificado, como en este ejemplo:
${system_current_date}.before('2021-11-19')
Puede comparar una fecha con otra fecha o una hora con otra. También puede comparar una hora con un valor de fecha y hora, en cuyo caso se ignora la fecha y sólo se comparan las horas. Cualquier otra comparación de valores no coincidentes
(por ejemplo, la comparación de una fecha con una hora) devuelve false
y se registra una excepción en output.debug.log_messages
(que puede ver en la vista previa del asistente o en las respuestas de la API).
.after(String date/time)
- Determina si el valor de fecha y hora es posterior al argumento de fecha y hora.
.sameMoment(String date/time)
- Determina si el valor de fecha y hora es el mismo que el argumento de fecha y hora.
.sameOrAfter(String date/time)
- Determina si el valor de fecha y hora es posterior o igual que el argumento de fecha y hora.
- Similar a
.after()
.
.sameOrBefore(String date/time)
- Determina si el valor de fecha y hora es anterior o el mismo que el argumento de fecha y hora.
Cálculos de fecha y hora
Utilice los métodos siguientes para calcular una fecha.
Método | Descripción |
---|---|
<date>.minusDays(_n_) |
Devuelve la fecha del día n días antes de la fecha especificada. |
<date>.minusMonths(_n_) |
Devuelve la fecha del día n meses antes de la fecha especificada. |
<date>.minusYears(_n_) |
Devuelve la fecha del día n años antes de la fecha especificada. |
<date>.plusDays(_n_) |
Devuelve la fecha del día n días después de la fecha especificada. |
<date>.plusMonths(_n_) |
Devuelve la fecha del día n meses después de la fecha especificada. |
<date>.plusYears(n) |
Devuelve la fecha del día n años después de la fecha especificada. |
donde <date>
se especifica en los formatos yyyy-MM-dd
o yyyy-MM-dd HH:mm:ss
.
Por ejemplo, para obtener la fecha de mañana, especifique la expresión siguiente:
${system_current_date}.plusDays(1)
Utilice los métodos siguientes para calcular una hora.
Método | Descripción |
---|---|
<time>.minusHours(_n_) |
Devuelve la hora n horas antes de la hora especificada. |
<time>.minusMinutes(_n_) |
Devuelve la hora n minutos antes de la hora especificada. |
<time>.minusSeconds(_n_) |
Devuelve la hora n segundos antes de la hora especificada. |
<time>.plusHours(_n_) |
Devuelve la hora n horas después de la hora especificada. |
<time>.plusMinutes(_n_) |
Devuelve la hora n minutos después de la hora especificada. |
<time>.plusSeconds(_n_) |
Devuelve la hora n segundos después de la hora especificada. |
donde <time>
se especifica en el formato HH:mm:ss
.
Por ejemplo, para obtener la hora una hora posterior a partir de ahora, especifique la siguiente expresión:
now().plusHours(1)
Cómo trabajar con intervalos de tiempo
Para mostrar una respuesta basada en si la fecha de hoy está dentro de un intervalo de tiempo determinado, puede utilizar una combinación de métodos relacionados con la hora. Por ejemplo, si ejecuta una oferta especial durante la temporada de vacaciones cada año, es posible que desee comprobar si la fecha de hoy está entre el 25 de noviembre y el 24 de diciembre de este año.
En primer lugar, defina las fechas de interés como variables de sesión. En las siguientes expresiones de variables de sesión de fecha inicial y final, la fecha se construye concatenando el valor dinámico del año actual con los valores de mes y día codificados:
start_date = now().reformatDateTime('Y') + '-12-24'
end_date = now().reformatDateTime('Y') + '-11-25'
A continuación, en una condición de paso, puede indicar que desea mostrar la respuesta solo si la fecha actual cae entre las fechas de inicio y finalización que ha definido como variables de sesión:
now().after(${start_date}) && now().before(${end_date})
Soporte de java.util.Date
Además de los métodos incorporados, utilice los métodos estándar de la clase java.util.Date
.
Por ejemplo, para obtener la fecha del día una semana posterior a partir de hoy, puede utilizar la siguiente sintaxis:
new Date(new Date().getTime() + (7 * (24*60*60*1000L)))
Esta expresión primero obtiene la fecha actual en milisegundos (desde el 1 de enero de 1970 a las 00:00:00 GMT). También calcula el número de milisegundos en 7 días ((24*60*60*1000L)
representa un día en milisegundos). A continuación
añade 7 días a la fecha actual. El resultado es la fecha completa del día posterior a una semana a partir de hoy (por ejemplo, Fri Jan 26 16:30:37 UTC 2018
).
Métodos numéricos
Estos métodos ayudan a reformatear valores numéricos.
Para obtener información sobre el reconocimiento de números en las respuestas de los clientes, consulte Elección de un tipo de respuesta.
Si desea cambiar la posición decimal para un número (por ejemplo, para volver a formatear un número como un valor de moneda), consulte Método String format().
toDouble()
Convierte el objeto o campo al tipo de número Double (doble). Puede llamar a este método sobre cualquier objeto o campo. Si la conversión falla, se devuelve null
.
toInt()
Convierte el objeto o campo al tipo de número Integer (entero). Puede llamar a este método sobre cualquier objeto o campo. Si la conversión falla, se devuelve null
.
toLong()
Convierte el objeto o campo al tipo de número Long (largo). Puede llamar a este método sobre cualquier objeto o campo. Si la conversión falla, se devuelve null
.
Para especificar un tipo de número Long en una expresión SpEL, debe añadir L
al número para identificarlo como tal (por ejemplo, 5000000000L
). Esta sintaxis es necesaria para cualquier número que no quepa en el tipo
Integer de 32 bits. Los números mayores que 2^31 (2.147.483.648) o menores que -2 (-2.147.483.648) se consideran tipos de números Largos. Los tipos de números Long tienen un valor mínimo de -2^63 y un valor máximo de 2^63-1 (o 9,223,372,036,854,775,807).
Matemáticas estándares
Utilice expresiones SpEL para definir ecuaciones matemáticas estándares, donde los operadores se representan con estos símbolos:
Operación aritmética | Símbolo |
---|---|
adición | + |
división | / |
multiplicación | * |
Resta | - |
java.lang.Math()
Puede utilizar las funciones de la clase java.lang.Math para realizar operaciones numéricas básicas.
Puede utilizar los métodos de la clase, incluyendo:
-
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 la documentación de referencia de java.lang.Math para obtener información sobre otros métodos.
java.util.Random()
Devuelve un número aleatorio. Puede utilizar cualquiera de las siguientes opciones de sintaxis:
- Para devolver un valor booleano aleatorio (
true
ofalse
), utilicenew Random().nextBoolean()
. - Para devolver un número doble aleatorio comprendido entre 0 (incluido) y 1 (excluido), utilice
new Random().nextDouble()
- Para devolver un entero aleatorio entre 0 (inclusive) y un número que especifique, utilice
new Random().nextInt(_n_)
, donde n es 1 mayor que el límite superior del rango de números que desea. Por ejemplo, si quiere que se devuelva un número aleatorio comprendido entre 0 y 10, especifiquenew Random().nextInt(11)
. - Para devolver un entero aleatorio del rango completo de valores enteros (entre -2147483648 y 2147483648), utilice
new Random().nextInt()
.
Por ejemplo, puede crear un paso que se ejecute solo para un subconjunto de clientes seleccionado aleatoriamente. La condición de paso siguiente significaría que el paso tiene un 50% de posibilidades de ejecución:
new Random().nextInt(2) == 1
Consulte la documentación de referencia de java.util.Random para obtener información sobre otros métodos.
También puede utilizar métodos estándar de las clases siguientes:
java.lang.Byte
java.lang.Integer
java.lang.Long
java.lang.Double
java.lang.Short
java.lang.Float
Métodos de serie (String)
Estos métodos le ayudan a trabajar con texto.
Para obtener más información sobre la sintaxis que se debe utilizar en los métodos que utilizan expresiones regulares, consulte la Referencia sintáctica RE2.
String.append(Object)
Este método añade un objeto de entrada (como una serie) a una serie y devuelve una serie modificada.
${step_297}.append('next text')
String.contains(String)
Este método devuelve true
si la variable de acción o variable de sesión contiene una subserie, que es útil en condiciones.
${step_297}.contains('Yes')
String.endsWith(String)
Este método devuelve true
si la serie finaliza con la subserie de entrada.
${step_297}.endsWith('?')
String.equals(String)
Este método devuelve true
si la serie especificada es igual a la variable de acción o a la variable de sesión.
${step_297}.equals('Yes')
String.equalsIgnoreCase(String)
Este método devuelve true
si la serie especificada es igual a la variable de acción o a la variable de sesión.
${step_297}.equalsIgnoreCase('Yes')
String.extract(String regexp, Integer groupIndex)
Este método devuelve una serie de la entrada que coincide con el patrón de grupo de expresiones regulares especificado. Devuelve una serie vacía si no se encuentra ninguna coincidencia.
Este método se ha diseñado para extraer coincidencias para distintos grupos de patrones de expresión regular (regex), no diferentes coincidencias para un patrón de expresión regular único. Para encontrar diferentes coincidencias, consulte el método getMatch().
En este ejemplo, la variable de acción guarda una serie que coincide con el grupo de patrones regex que especifique. En la expresión, se definen dos grupos de patrones de expresión regular, cada uno encerrado entre paréntesis. Inherente es un tercer grupo que se compone de los dos grupos. Este es el primer grupo regex groupIndex 0); coincide con una cadena que contiene el grupo de números completo y el grupo de texto. El segundo grupo de regex (groupIndex 1) coincide con la primera aparición de un grupo de números. El tercer grupo (groupIndex 2) coincide con la primera aparición de un grupo de texto después de un grupo de números.
${step_297}.extract('([\d]+)(\b [A-Za-z]+)', <n>)
Si la variable de acción contiene:
Hello 123 this is 456.
el resultado será el siguiente:
- Cuando
<n>
=0
, el valor es123 this
. - Cuando
<n>
=1
, el valor es123
. - Cuando
<n>
=2
, el valor esthis
.
String.find(String regexp)
Este método devuelve true
si algún segmento de la serie coincide con la expresión regular de entrada. Puedes llamar a este método contra un elemento JSONArray o JSONObject, y convierte el array u objeto en una cadena antes de
hacer la comparación.
Por ejemplo, si la variable de acción ${step_297}
recopila la serie Hello 123456
, la expresión siguiente devuelve true
:
${step_297}.find('^[^\d]*[\d]{6}[^\d]*$')
La condición es true
porque la parte numérica del texto de entrada coincide con la expresión regular ^[^\d]*[\d]{6}[^\d]*$
.
String.getMatch(String regexp, Integer matchIndex)
Este método devuelve una serie que coincide con la aparición del patrón de expresión regular especificado. Este método devuelve una serie vacía si no se encuentra ninguna coincidencia.
A medida que se encuentran coincidencias, se añaden a lo que se puede considerar como una matriz de coincidencias. Puesto que el recuento de elementos de la matriz se inicia en 0, si desea devolver la tercera coincidencia, debe especificar
2 como valor de matchIndex
. Por ejemplo, si especifica una serie de texto con tres palabras que coincidan con el patrón especificado, puede devolver la primera, segunda o tercera coincidencia solo especificando el valor de su
índice.
Por ejemplo, el ejemplo siguiente busca un grupo de números en una variable de acción.
${step_297}.getMatch('([\d]+)', 1)
Si la variable de acción ${step_297}
contiene la serie hello 123 i said 456 and 8910
, esta expresión devuelve 456
.
String.isEmpty()
Este método devuelve true
si la serie es una serie vacía, pero no null
, como en este ejemplo:
${step_297}.isEmpty()
String.length()
Este método devuelve la longitud de caracteres de la serie, como en este ejemplo:
${step_297}.length()
Si la variable de acción ${step_297}
contiene la serie Hello
, esta expresión devuelve 5.
String.matches(String regexp)
Este método devuelve true
si la serie coincide con la expresión regular de entrada, como en el ejemplo:
${step_297}.matches('^Hello$')
Si la variable de acción ${step_297}
contiene la serie Hello
, esta expresión se evalúa como true
.
String.startsWith(String)
Este método devuelve true
si la serie empieza por la subserie especificada, como en este ejemplo:
${step_297}.startsWith('What')
Si la variable de acción ${step_297}
contiene la serie What is your name?
, esta expresión devuelve true
.
String.substring(Integer beginIndex, Integer endIndex)
Este método devuelve una subserie que empieza por el carácter en beginIndex
y termina con el carácter anterior a endIndex
. (El propio carácter endIndex
no se incluye en la subserie.) Los valores de índice
están basados en cero, por lo que el primer carácter de la cadena está en el índice 0.
Este ejemplo devuelve una subserie que empieza en el índice 5 (que es el sexto carácter) y continúa hasta el final de la serie:
${step_297}.substring(5, ${step_297}.length())
Si la variable de acción ${step_297}
contiene la serie This is a string.
, esta expresión devuelve is a string.
String.toJson()
Este método analiza una serie que contiene datos JSON y devuelve un objeto o matriz JSON, como en este ejemplo:
${json_var}.toJson()
Si la variable de sesión ${json_var}
contiene la siguiente serie:
"{ \"firstname\": \"John\", \"lastname\": \"Doe\" }"
el método toJson()
devuelve el objeto siguiente:
{
"firstname": "John",
"lastname": "Doe"
}
String.toLowerCase()
Este método devuelve la cadena especificada convertida a minúsculas, como en este ejemplo:
${step_297}.toLowerCase()
Si la variable de acción ${step_297}
contiene la serie This is A DOG!
, esta expresión devuelve la serie this is a dog!
.
String.toUpperCase()
Este método devuelve la cadena original convertida a mayúsculas, como en este ejemplo:
${step_297}.toUpperCase()
Si la variable de acción ${step_297}
contiene la serie hi there
, este método devuelve la serie HI THERE
.
String.trim()
Este método recorta los espacios al principio y al final de una serie y devuelve la serie modificada, como en este ejemplo:
${step_297}.trim()
Si la variable de acción ${step_297}
contiene la serie something is here
, este método devuelve la serie something is here
.
Soporte de java.lang.String
Además de los métodos incorporados, utilice los métodos estándar de la clase java.lang.String
.
java.lang.String.format()
Puede aplicar el método de series Java estándar format()
al texto. Para obtener información sobre la sintaxis que se debe utilizar, consulte Sintaxis de serie de formato.
Este ejemplo utiliza tres enteros decimales (1, 1 y 2) y los añade a una sentencia:
T(java.lang.String).format('%d + %d equals %d', 1, 1, 2)
La serie resultante es 1 + 1 equals 2
.
Este ejemplo cambia la colocación decimal para un número que es recogido por un paso:
T(String).format('%.2f',${step_297})
Si la variable ${step_297}
que debe formatearse en dólares estadounidenses es 4.5, la serie resultante es 4.50
.
Métodos de matriz
Estos métodos le ayudan a trabajar con matrices.
Array.add(value...)
Este método añade uno o más valores nuevos a la matriz y devuelve true
si la operación es satisfactoria.
${Items}.add('four', 'five')
Si Items
es ['one', 'two', 'three']
, este ejemplo lo actualiza para que se convierta en ['one', 'two', 'three', 'four', 'five']
.
Array.addAll(Array array)
Este método añade una matriz a otra y devuelve null
.
${Items}.addAll(${New_items})
Si Items
es ['one', 'two', 'three']
y New_items
es ['four', 'five', 'six']
, este ejemplo actualiza Items
en su lugar para que se convierta en ['one', 'two', 'three', 'four', 'five', 'six']
.
Array.append(value...)
Este método añade uno o más valores nuevos a la matriz y devuelve el resultado como una matriz nueva. La matriz original no se modifica.
${Items}.append('four', 'five')
Si Items
es ['one', 'two', 'three']
, este ejemplo devuelve la nueva matriz ['one', 'two', 'three', 'four', 'five']
.
Array.clear()
Este método elimina todos los valores de la matriz y devuelve null.
${Items}.clear()
Después de evaluar esta expresión, Items
es una matriz vacía ([]
).
Array.contains(value)
Este método devuelve true
si la matriz contiene un elemento que es exactamente igual al valor de entrada. El valor especificado puede ser una serie o un número.
${Items}.contains(123)
Si Items
es [123, 456, 789]
, este ejemplo devuelve true
.
Array.containsIgnoreCase(value)
Este método devuelve true
si la matriz contiene un elemento que es igual al valor de entrada. Las series se comparan independientemente de si el valor se especifica en mayúsculas o minúsculas. El valor especificado puede ser una
serie o un número.
${Items}.contains('two')
Este ejemplo devuelve true
si la matriz Items
contiene alguna capitalización de la serie two
(por ejemplo, TWO
o Two
también coincidiría).
Array.filter(temp_var, "temp_var.property operator comparison_value")
Filtra una matriz comparando cada elemento de matriz con un valor que especifique, devolviendo una nueva matriz que contiene sólo los elementos coincidentes.
La expresión de filtro consta de los valores siguientes:
-
temp_var
: un nombre arbitrario para una variable temporal que se utiliza para contener cada elemento de matriz a medida que se evalúa. Por ejemplo, si la matriz original contiene objetos que describen ciudades, puede utilizarcity
como nombre de variable temporal. -
property
: la propiedad de elemento por la que desea filtrar. Debe ser una propiedad de los elementos de la matriz de origen. Especifique la propiedad como una propiedad detemp_var
, utilizando la sintaxistemp_var.property
. Por ejemplo, silatitude
es un nombre de propiedad válido para los elementos de origen, puede especificar la propiedad comocity.latitude
. -
operator
: El operador a utilizar para comparar el valor de la propiedad con el valor de comparación. Puede utilizar cualquiera de los siguientes operadores:Operadores de filtro admitidos Operador Descripción ==
Es igual que >
Es mayor que <
Es menos que >=
Mayor o igual que <=
Menor o igual que !=
No es igual que -
comparison_value
: El valor con el que desea comparar cada valor de propiedad de elemento de matriz. Puede especificar un valor literal o hacer referencia a una variable.
Ejemplos de filtro
Por ejemplo, puede tener una matriz de objetos que contienen nombres de ciudad y sus números de población:
[
{
"name":"Tokyo",
"population":13988129
},
{
"name":"Rome",
"population":2860009
},
{
"name":"Beijing",
"population":21893095
},
{
"name":"Paris",
"population":2165423
}
]
Si la matriz de origen se almacena en una variable denominada ${cities}
, la expresión siguiente devuelve una matriz más pequeña que sólo contiene ciudades con poblaciones mayores de 5 millones:
${cities}.filter("city", "city.population > 5000000")
La expresión devuelve la siguiente matriz filtrada:
[
{
"name":"Tokyo",
"population":13988129
},
{
"name":"Beijing",
"population":21893095
}
]
En lugar de un valor de comparación codificado, también puede filtrar basándose en un valor dinámico almacenado en una variable. Este ejemplo filtra utilizando un valor de población especificado por una respuesta de cliente en un paso anterior:
${cities}.filter("city", "city.population > ${step_123}")
Cuando compare valores numéricos, asegúrese de establecer la variable de contexto que interviene en la comparación en un valor válido antes de que se active el método de filtrado. Tenga en cuenta que null
puede ser un valor
válido si el elemento de la matriz con el que lo está comparando lo puede contener.
Array.get(Integer index)
Este método devuelve el elemento de la matriz que está en la posición de índice especificada. Las matrices son de índice cero, lo que significa que el primer elemento de la matriz está en la posición de índice 0
.
${Items}.get(1)
Si Items
es ['one', 'two', 'three']
, este ejemplo devuelve two
.
El método get()
es una alternativa al uso de corchetes ([]
) para recuperar un elemento de una matriz. El ejemplo siguiente también es válido y devuelve el mismo resultado:
${Items}[1]
Si está utilizando un valor especificado por un cliente para elegir un elemento de una matriz, es posible que tenga que restar 1 para convertir a un valor indexado cero. Por ejemplo, puede utilizar una expresión como ${Items}.get(${step_123} - 1)
para recuperar el valor previsto.
Array.getRandomItem()
Este método devuelve un elemento elegido aleatoriamente de la matriz.
${Items}.getRandomItem()
Si Items
es ['one', 'two', 'three']
, este ejemplo devuelve one
, two
o three
, de forma aleatoria.
Array.indexOf(value)
Este método devuelve la posición de índice de la primera aparición del valor de entrada en la matriz, o -1
si la matriz no contiene el valor de entrada. El valor especificado puede ser una serie o un número.
${Items}.indexOf(`two`)
Si Items
es ['one', 'two', 'three']
, este ejemplo devuelve el entero 1
(que indica la segunda posición en la matriz con índice cero).
Array.join(String delimiter)
Este método une todos los valores de esta matriz a una serie. Los valores se convierten en una serie y se delimitan mediante el delimitador de entrada.
Por ejemplo, puede utilizar una variable denominada pizza_toppings
que contiene la matriz ["pepperoni", "ham", "mushrooms"]
. La expresión siguiente convierte esta matriz en la serie pepperoni, ham, mushrooms
:
${toppings_array}.join(', ')
Si utiliza esa expresión para definir el valor de una variable, puede hacer referencia a esa variable en la salida del asistente para crear un mensaje legible por el usuario (por ejemplo, You have selected the following toppings: pepperoni, ham, mushrooms
).
JSONArray.joinToArray(template, retainDataType)
Este método extrae información de cada elemento de la matriz y crea una nueva matriz formateada según la plantilla que especifique. La plantilla puede ser una serie, un objeto JSON o una matriz. El método devuelve una matriz de series, una matriz de objetos o una matriz de matrices, en función del tipo de plantilla.
Este método es útil para formatear información como una serie que puede devolver como parte de la salida de un paso, o para transformar datos en una estructura diferente para que pueda utilizarla con una API externa.
En la plantilla, puede hacer referencia a valores de la matriz de origen utilizando la sintaxis siguiente:
%e.{property}%
donde {property}
representa el nombre de la propiedad en la matriz de origen.
Por ejemplo, supongamos que el asistente almacena una matriz que contiene detalles de vuelo en una variable de sesión. Los datos almacenados pueden tener este aspecto:
"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 crear una matriz de series que describan estos vuelos en un formato legible por el usuario, puede utilizar la expresión siguiente:
${Flight_data}.joinToArray("Flight %e.flight% to %e.destination%", true)
Esta expresión devolvería la siguiente matriz de series: ["Flight AZ1040 to FCO","Flight DL1710 to LAX","Flight VS4379 to LHR"]
.
El parámetro opcional retainDataType
especifica si el método conserva el tipo de datos de todos los valores de entrada de la matriz devuelta. Si retainDataType
se establece en false
u se omite, en algunas
situaciones, las series de la matriz de entrada se pueden convertir en números en la matriz devuelta. Por ejemplo, si los valores seleccionados de la matriz de entrada son "1"
, "2"
y "3"
,
la matriz devuelta podría ser [ 1, 2, 3 ]
. Para evitar conversiones de tipo inesperadas, especifique true
para este parámetro.
Plantillas complejas
Una plantilla más compleja puede contener un formato que muestre la información en un diseño legible. Para una plantilla compleja, es posible que desee almacenar la plantilla en una variable de sesión, que luego puede pasar al método joinToArray
en lugar de una serie.
Por ejemplo, esta plantilla compleja contiene un subconjunto de los elementos de matriz, añadiendo etiquetas y formateo:
<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/>
Asegúrese de que cualquier formato que utilice en la plantilla esté soportado por la integración de canal que muestra la salida del asistente.
Si crea una variable de sesión denominada Template
y asigna esta plantilla como su valor, puede utilizar dicha variable en las expresiones:
${Flight_data}.joinToArray(${Template})
En tiempo de ejecución, la respuesta tendría este aspecto:
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
Plantillas JSON
En lugar de una serie, puede definir una plantilla como un objeto JSON, que proporciona una forma de estandarizar el formato de la información de distintos sistemas, o de transformar los datos en el formato necesario para un servicio externo.
En este ejemplo, una plantilla se define como un objeto JSON que extrae detalles de vuelo de los elementos especificados en la matriz que se almacena en la variable de sesión 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%."
}
Utilizando esta plantilla, el método joinToArray()
devuelve una nueva matriz de objetos con la estructura especificada.
Array.remove(Integer index)
Este método elimina de la matriz el elemento en la posición de índice especificada y devuelve la matriz actualizada.
${Items}.remove(1)
Si Items
es ['one', 'two', 'three']
, este ejemplo devuelve ['one', 'three']
. La matriz Items
original también se modifica en su lugar.
Array.removeValue(value)
Este método elimina la primera aparición del valor especificado de la matriz y devuelve la matriz actualizada. El valor especificado puede ser una serie o un número.
${Items}.removeValue('two')
Si Items
es ['one', 'two', 'three']
, este ejemplo devuelve ['one', 'three']
. La matriz Items
original también se modifica en su lugar.
Array.set(Integer index, value)
Este método sustituye el elemento en la posición de índice especificada por el valor especificado y devuelve la matriz actualizada.
${Items}.set(2,'five')
Si Items
es ['one', 'two', 'three']
, este ejemplo devuelve ['one', 'two', 'five']
. La matriz Items
original también se modifica en su lugar.
Array.size()
Este método devuelve el número de elementos de la matriz como un entero.
${Items}.size()
Si Items
es ['one', 'two', 'three']
, este ejemplo devuelve 3
.
Array.sort()
Este método realiza una ordenación in situ y devuelve la matriz ordenada. El parámetro por defecto es ascending
. Puede especificar descending
para cambiar el orden de clasificación. Se ignora cualquier otra entrada
de parámetro y aparece un error de registro.
${Items}.sort("ascending")
El método compara números y series. Un número siempre es menor que una serie. Cualquier otro tipo se convierte a serie de forma predeterminada para comparar.
Por ejemplo:
Matriz original | Matriz ordenada |
---|---|
[2,1,3,5,4,3,2] | [1,2,2,3,3,4,5] |
["Banana", "Orange", "Apple", "Mango"] | ["Apple", "Banana", "Mango", "Naranja"] |
[3, 2, 4, "1", "10", "12", "Banana", "Orange", 0, "Apple", "Mango"] | [0, 2, 3, 4, "1", "10", "12", "Apple", "Banana", "Mango", "Naranja"] |
Array.transform()
El método Array.transform()
sólo se utiliza con Variable session_history
. Puede transformar la salida de la variable para
que coincida con un sistema de IA generativa específico.
Tabla: Firmas para formatos de conversación muestra las firmas que puede utilizar para los distintos formatos de conversación:
Datos | OpenAI | Google PaLM2 | Llama2 |
---|---|---|---|
Firma | 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 de mensaje de 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 de mensaje del asistente | {$rolePrefix: $assistantPrefix, "content": $content} |
{$rolePrefix: $assistantPrefix, "content": $content} |
N/D |
Ejemplo | ${system_session_history}.transform("role", "user", "assistant") |
${system_session_history}.transform("author", "USER", "AI") |
${system_session_history}.transform("<your system prompt>") |
Si currentAction
es true:
Usos del asistente | Descripción |
---|---|
Sólo acciones | La transformación excluye todos los mensajes en los que n es verdadero, lo que indica que una pregunta de cliente ha desencadenado una nueva acción base. |
Sólo diálogo | currentAction se ignora y la transformación incluye todo el contenido de la variable session history . |
Diálogo y acciones | La transformación incluye todo en la variable session_history desde el inicio más reciente de una acción, independientemente de si se desencadena algún nodo de diálogo. |
Los distintivos n : true
no se incluyen en la salida de la transformación.