Méthodes de langage d'expression pour les actions
Le langage d'expression watsonx Assistant peut être utilisé pour indiquer des valeurs indépendantes ou dérivées de valeurs collectées par étapes ou stockées dans des variables de session. Vous pouvez utiliser une expression pour définir une condition d'étape ou la valeur d'une variable de session.
Le langage d'expression watsonx Assistant est basé sur le langage d'expression Spring SpEL, mais avec quelques différences syntaxiques importantes. Pour plus d'informations sur SpEL, voir Spring Expression Language(SpEL).
Vous pouvez utiliser les expressions SpEL de deux manières :
- Définition d'une condition d'étape. Pour plus d'informations, voir Écriture expressions.
- Affectation d'une valeur à une variable de session. Pour plus d'informations, voir Utilisation des variables pour gérer les informations de conversation.
Référencement des variables d'action
Une variable d'action est créée implicitement pour toute étape qui attend une entrée du client, et cette variable est liée à l'étape. Pour référencer une variable d'action dans une expression, vous devez spécifier l'ID de l'étape en utilisant
le format ${step_id} (par exemple, ${step_771}. Pour trouver l'ID d'étape d'une étape, sélectionnez-la, puis vérifiez la fin de l'URL dans votre navigateur.
Référencement des variables de session
Les variables de session sont créées explicitement dans la section Variables de l'étape. Pour référencer une variable de session dans une expression, vous devez spécifier l'identifiant de la variable en utilisant le format ${variable_id} (par exemple, ${current_time}. Vous pouvez trouver l'ID de la variable dans la liste des variables. (Pour plus d'informations, voir Utilisation des variables pour gérer les informations de conversation).
Lorsque vous modifiez une expression, vous pouvez taper $ pour afficher la liste des variables auxquelles vous pouvez faire référence. Sélectionnez une variable dans la liste pour insérer automatiquement l'ID d'étape ou l'ID de
variable.
Types de données pris en charge
Les expressions peuvent utiliser des types JSON atomiques (tels que integer, string, number et boolean ) et des types de données composées (tels que les tableaux JSON ( [] ) et
les objets ( {} ). Lorsque vous spécifiez des valeurs de chaînes littérales, vous pouvez utiliser des guillemets simples ( ' ) ou doubles ( " ).
Les valeurs que les étapes d'action collectent auprès des clients utilisent des types de réponse client tels que la date, l'heure, la devise ou le pourcentage. Ces valeurs sont stockées en tant qu'objets JSON dans le format suivant :
{
"system_type": "{system_type}",
"value": "{value}"
}
où {system_type} est l'un des types suivants :
timepercentagecurrency
Méthodes de date et d'heure
Plusieurs méthodes sont disponibles pour travailler avec des valeurs de date et d'heure.
now(String timezone)
La méthode now() renvoie la date et l'heure actuelles d'un fuseau horaire donné, au format yyyy-MM-dd HH:mm:ss 'GMT'XXX :
now('Australia/Sydney').
Dans cet exemple, si la date et l'heure en cours sont 2021-11-26 11:41:00, la chaîne renvoyée est 2021-11-26 21:41:00 GMT+10.00 ou 2021-11-26 21:41:00 GMT+11.00 en fonction de l'heure d'été.
Le changement de format de la chaîne de sortie s'applique également aux méthodes de calcul de date et d'heure. Par exemple, si la chaîne <date> utilisée est au format yyyy-MM-dd HH:mm:ss, par exemple lorsque
vous utilisez la méthode today(), la sortie est au même format (yyyy-MM-dd HH:mm:ss). Toutefois, si la chaîne <date> est au format yyyy-MM-dd HH:mm:ss 'GMT'XXX, par exemple lorsque
vous utilisez la méthode now(), la sortie est au format yyyy-MM-dd HH:mm:ss 'GMT'XXX.
.reformatDateTime(String format)
Formate les chaînes de date et d'heure pour leur affichage. Le paramètre est une chaîne de format qui spécifie comment la valeur de la date ou de l'heure est formatée. La chaîne de format doit être spécifiée en utilisant la syntaxe Java SimpleDateFormat.
Cette méthode renvoie une chaîne de caractères formatée selon le format spécifié :
MM/dd/yyyypour 12/31/2016h apour 10pm
Pour renvoyer le jour de la semaine :
EEEEpour mardiEpour Tueupour l'index de jour (1 = Lundi, ..., 7 = Dimanche)
Par exemple, cette expression renvoie la valeur 17:30:00 en tant que 5:30 PM :
${system_current_date}.reformatDateTime('h:mm a')
Si la chaîne d'entrée n'inclut qu'une heure, la date par défaut 1970-01-01 est utilisée dans le résultat. Si la chaîne d'entrée n'inclut qu'une date, l'heure par défaut 12 AM (00:00) est utilisée.
.before(String date/time)
- Détermine si une valeur de date et d'heure est antérieure à l'argument de date et d'heure spécifié, comme dans l'exemple suivant:
${system_current_date}.before('2021-11-19')
Vous pouvez comparer une date avec une autre date, ou une heure avec une autre heure. Vous pouvez également comparer une heure avec une date et une heure, auquel cas la date est ignorée et seules les heures sont comparées. Toute autre comparaison
de valeurs incompatibles (par exemple, la comparaison d'une date avec une heure) renvoie la valeur false, une exception est enregistrée dans output.debug.log_messages (que vous pouvez voir dans l'aperçu de l’assistant
ou dans les réponses de l'API).
.after(String date/time)
- Détermine si la valeur de date et d'heure est postérieure à l'argument de date et d'heure.
.sameMoment(String date/time)
- Détermine si la valeur de date et d'heure est identique à l'argument de date et d'heure.
.sameOrAfter(String date/time)
- Détermine si la valeur de date et d'heure est postérieure ou identique à l'argument de date et d'heure.
- Semblable à
.after().
.sameOrBefore(String date/time)
- Détermine si la valeur de date et d'heure est antérieure ou identique à l'argument de date et d'heure.
Calculs de date et heure
Utilisez les méthodes suivantes pour calculer une date.
| Méthode | Description |
|---|---|
<date>.minusDays(_n_) |
Renvoie la date du jour n jours avant la date spécifiée. |
<date>.minusMonths(_n_) |
Renvoie la date du jour n mois avant la date spécifiée. |
<date>.minusYears(_n_) |
Renvoie la date du jour n années avant la date spécifiée. |
<date>.plusDays(_n_) |
Renvoie la date du jour n jours après la date spécifiée. |
<date>.plusMonths(_n_) |
Renvoie la date du jour n mois après la date spécifiée. |
<date>.plusYears(n) |
Renvoie la date du jour n années après la date spécifiée. |
Où <date> est spécifié au format yyyy-MM-dd ou yyyy-MM-dd HH:mm:ss.
Par exemple, pour obtenir la date de demain, il faut indiquer l'expression suivante :
${system_current_date}.plusDays(1)
Utilisez les méthodes suivantes pour calculer une heure.
| Méthode | Description |
|---|---|
<time>.minusHours(_n_) |
Renvoie l'heure n heures avant l'heure spécifiée. |
<time>.minusMinutes(_n_) |
Renvoie l'heure n minutes avant l'heure spécifiée. |
<time>.minusSeconds(_n_) |
Renvoie l'heure n secondes avant l'heure spécifiée. |
<time>.plusHours(_n_) |
Renvoie l'heure n heures après l'heure spécifiée. |
<time>.plusMinutes(_n_) |
Renvoie l'heure n minutes après l'heure spécifiée. |
<time>.plusSeconds(_n_) |
Renvoie l'heure n secondes après l'heure spécifiée. |
Où <time> est spécifié au format HH:mm:ss.
Par exemple, pour obtenir l'heure dans une heure, indiquez l'expression suivante :
now().plusHours(1)
Utilisation des intervalles de temps
Pour afficher une réponse selon que la date du jour se situe dans une période donnée, vous pouvez utiliser une combinaison de méthodes temporelles. Par exemple, si vous proposez chaque année une offre spéciale pendant la période des fêtes, vous pouvez vérifier si la date d'aujourd'hui se situe entre le 25 novembre et le 24 décembre de cette année.
Tout d'abord, définissez les dates qui vous intéressent en tant que variables de session. Dans les expressions de variables de session de date de début et de fin suivantes, la date est construite en concaténant la valeur dynamique de l'année en cours avec les valeurs de mois et de jour codées en dur :
start_date = now().reformatDateTime('Y') + '-12-24'
end_date = now().reformatDateTime('Y') + '-11-25'
Ensuite, dans une condition d'étape, vous pouvez indiquer que vous souhaitez afficher la réponse uniquement si la date actuelle se situe entre les dates de début et de fin que vous avez définies comme variables de session :
now().after(${start_date}) && now().before(${end_date})
java.util.Date support
En plus des méthodes intégrées, vous pouvez utiliser des méthodes standard de la classe java.util.Date.
Par exemple, pour obtenir la date du jour qui tombe une semaine après aujourd'hui, vous pouvez utiliser la syntaxe suivante :
new Date(new Date().getTime() + (7 * (24*60*60*1000L)))
Cette expression extrait d'abord la date du jour en millisecondes (depuis le 1er janvier 1970, à 00:00:00 GMT). Elle calcule également le nombre de millisecondes en 7 jours ((24*60*60*1000L) représente un jour en millisecondes).
Elle ajoute ensuite 7 jours à la date du jour. Le résultat est la date complète du jour qui tombe une semaine après aujourd'hui (par exemple, Fri Jan 26 16:30:37 UTC 2018).
Méthodes de numérotation
Ces méthodes vous permettent d'obtenir et de reformater les valeurs numériques.
Pour plus d'informations sur la reconnaissance des nombres dans les réponses des clients, voir Choix d'un type de réponse.
Si vous souhaitez modifier la position de la décimale d'un nombre (par exemple, pour reformater un nombre en tant que valeur de devise), voir la méthode Format chaîne().
toDouble()
Convertit l'objet ou la zone en type Nombre double. Vous pouvez appeler cette méthode sur n'importe quel objet ou sur n'importe quelle zone. Si la conversion échoue, null est renvoyé.
toInt()
Convertit l'objet ou la zone en type Nombre entier. Vous pouvez appeler cette méthode sur n'importe quel objet ou sur n'importe quelle zone. Si la conversion échoue, null est renvoyé.
toLong()
Convertit l'objet ou la zone en type Nombre long. Vous pouvez appeler cette méthode sur n'importe quel objet ou sur n'importe quelle zone. Si la conversion échoue, null est renvoyé.
Pour spécifier un type numérique Long dans une expression SpEL, vous devez ajouter L au nombre pour l'identifier en tant que tel (par exemple, 5000000000L). Cette syntaxe est requise pour tous les nombres qui ne correspondent
pas au type Entier 32 bits. Les nombres supérieurs à 2^31 (2 147 483 648) ou inférieurs à -2 (-2 147 483 648) sont considérés comme des nombres longs. Les types numériques Long ont une valeur minimale de -2^63 et une valeur maximale de 2^63-1
(ou 9,223,372,036,854,775,807).
Mathématiques standard
Utilisez des expressions SpEL pour définir des équations mathématiques standard, dans lesquelles les opérateurs sont représentés à l'aide de ces symboles :
| Opération arithmétique | Symbole |
|---|---|
| ajout | + |
| division | / |
| multiplication | * |
| soustraction | - |
java.lang.Math()
Vous pouvez utiliser les fonctions de la classe java.lang.Math pour effectuer des opérations numériques de base.
Vous pouvez utiliser les méthodes de la classe, y compris :
-
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())
Voir la documentation de référence java.lang.Math pour plus d'informations sur les autres méthodes.
java.util.Random()
Renvoie un nombre aléatoire. Vous pouvez utiliser l'une des options de syntaxe suivantes :
- Pour renvoyer une valeur booléenne aléatoire (
trueoufalse), utiliseznew Random().nextBoolean(). - Pour renvoyer un nombre double aléatoire entre 0 (inclus) et 1 (exclu), utilisez
new Random().nextDouble() - Pour renvoyer un entier aléatoire entre 0 (inclus) et un nombre que vous indiquez, utilisez
new Random().nextInt(_n_), où n est 1 supérieur au haut de la plage de nombres que vous voulez. Par exemple, si vous souhaitez renvoyer un nombre aléatoire entre 0 et 10, indiqueznew Random().nextInt(11). - Pour renvoyer un entier aléatoire de la plage complète des valeurs entières (-2147483648 à 2147483648), utilisez
new Random().nextInt().
Par exemple, vous pouvez créer une étape qui n'est exécutée que pour un sous-ensemble de clients sélectionnés au hasard. La condition d'étape suivante signifierait que l'étape a 50 % de chances de s'exécuter :
new Random().nextInt(2) == 1
Voir la documentation de référence java.util.Random pour plus d'informations sur les autres méthodes.
Vous pouvez également utiliser des méthodes standard des classes suivantes :
java.lang.Bytejava.lang.Integerjava.lang.Longjava.lang.Doublejava.lang.Shortjava.lang.Float
Méthodes de chaîne
Ces méthodes vous aident à travailler avec du texte.
Pour plus de détails sur la syntaxe à utiliser dans les méthodes impliquant des expressions régulières, voir la référence syntaxique RE2.
String.append(Object)
Cette méthode ajoute un objet d'entrée (sous forme de chaîne) à une chaîne et renvoie une chaîne modifiée.
${step_297}.append('next text')
String.contains(String)
Cette méthode renvoie true si la variable d'action ou la variable de session contient une sous-chaîne, ce qui est utile dans les conditions.
${step_297}.contains('Yes')
String.endsWith(String)
Cette méthode renvoie true si la chaîne se termine par la sous-chaîne d'entrée.
${step_297}.endsWith('?')
String.equals(String)
Cette méthode renvoie true si la chaîne spécifiée est égale à la variable d'action ou à la variable de session.
${step_297}.equals('Yes')
String.equalsIgnoreCase(String)
Cette méthode renvoie true si la chaîne spécifiée est égale à la variable d'action ou à la variable de session, quel que soit la casse.
${step_297}.equalsIgnoreCase('Yes')
String.extract(String regexp, Integer groupIndex)
Cette méthode renvoie une chaîne de l'entrée qui correspond au modèle de groupe d'expressions régulières spécifié. Elle renvoie une chaîne vide si aucune correspondance n'est trouvée.
Cette méthode est conçue pour extraire des correspondances pour différents groupes de canevas d'expression régulière, et non pour des correspondances différentes pour un canevas d'expression régulière. Pour trouver d'autres correspondances, voir la méthode getMatch().
Dans cet exemple, la variable d'action enregistre une chaîne qui correspond au groupe de modèle d'expression régulière que vous indiquez. Dans l'expression, deux groupes de canevas d'expression régulière sont définis, chacun entre parenthèses. Inhérent est un troisième groupe qui est composé des deux groupes. Il s'agit du premier groupe de regex groupIndex 0) ; il correspond à une chaîne qui contient le groupe de numéros et le groupe de texte complets. Le deuxième groupe d'expressions régulières (groupIndex 1) correspond à la première occurrence d'un groupe de nombres. Le troisième groupe (groupIndex 2) correspond à la première occurrence d'un groupe de textes après un groupe de nombres.
${step_297}.extract('([\d]+)(\b [A-Za-z]+)', <n>)
Si la variable d'action contient:
Hello 123 this is 456.
les résultats seront les suivants :
- Lorsque
<n>=0, la valeur est123 this. - Lorsque
<n>=1, la valeur est123. - Lorsque
<n>=2, la valeur estthis.
String.find(String regexp)
Cette méthode renvoie true si un segment de la chaîne correspond à l'expression régulière d'entrée. Vous pouvez appeler cette méthode sur un élément JSONArray ou JSONObject, et elle convertit le tableau ou l'objet en chaîne de
caractères avant d'effectuer la comparaison.
Par exemple, si la variable d'action ${step_297} collecte la chaîne Hello 123456, l'expression suivante renvoie true:
${step_297}.find('^[^\d]*[\d]{6}[^\d]*$')
La condition est true car la partie numérique du texte d'entrée correspond à l'expression régulière ^[^\d]*[\d]{6}[^\d]*$.
String.getMatch(String regexp, Integer matchIndex)
Cette méthode renvoie une chaîne qui correspond à l'occurrence du modèle d'expression régulière spécifié. Cette méthode renvoie une chaîne vide si aucune correspondance n'est trouvée.
Lorsque des correspondances sont trouvées, elles sont ajoutées à ce que l'on peut considérer comme un tableau de correspondances. Étant donné que le nombre d'éléments du tableau commence à 0, si vous souhaitez renvoyer la troisième correspondance,
vous devez indiquer 2 comme valeur matchIndex. Par exemple, si vous entrez une chaîne de texte avec trois mots correspondant au modèle spécifié, vous pouvez renvoyer la première, la deuxième ou la troisième correspondance uniquement
en spécifiant sa valeur d'index.
Par exemple, l'exemple suivant recherche un groupe de nombres dans une variable d'action.
${step_297}.getMatch('([\d]+)', 1)
Si la variable d'action ${step_297} contient la chaîne hello 123 i said 456 and 8910, cette expression renvoie 456.
String.isEmpty()
Cette méthode renvoie true si la chaîne est une chaîne vide, mais pas null, comme dans l'exemple suivant :
${step_297}.isEmpty()
String.length()
Cette méthode renvoie la longueur de caractère de la chaîne, comme dans l'exemple suivant :
${step_297}.length()
Si la variable d'action ${step_297} contient la chaîne Hello, cette expression renvoie 5.
String.matches(String regexp)
Cette méthode renvoie true si la chaîne correspond à l'expression régulière d'entrée, comme dans l'exemple :
${step_297}.matches('^Hello$')
Si la variable d'action ${step_297} contient la chaîne Hello, cette expression a pour résultat true.
String.startsWith(String)
Cette méthode renvoie true si la chaîne commence par la sous-chaîne spécifiée, comme dans l'exemple suivant :
${step_297}.startsWith('What')
Si la variable d'action ${step_297} contient la chaîne What is your name?, cette expression renvoie true.
String.substring(Integer beginIndex, Integer endIndex)
Cette méthode renvoie une sous-chaîne commençant par le caractère se trouvant à beginIndex et se terminant par le caractère avant endIndex. (Le caractère endIndex lui-même n'est pas inclus dans la sous-chaîne).
Les valeurs d'index sont basées sur zéro, de sorte que le premier caractère de la chaîne se trouve à l'index 0.
Cet exemple renvoie une sous-chaîne qui commence à l'index 5 (qui est le sixième caractère) et continue jusqu'à la fin de la chaîne :
${step_297}.substring(5, ${step_297}.length())
Si la variable d'action ${step_297} contient la chaîne This is a string., cette expression renvoie is a string.
String.toJson()
Cette méthode analyse une chaîne qui contient des données JSON et renvoie un objet ou un tableau JSON, comme dans cet exemple:
${json_var}.toJson()
Si la variable de session ${json_var} contient la chaîne suivante:
"{ \"firstname\": \"John\", \"lastname\": \"Doe\" }"
la méthode toJson() renvoie l'objet suivant:
{
"firstname": "John",
"lastname": "Doe"
}
String.toLowerCase()
Cette méthode renvoie la chaîne spécifiée qui est convertie en lettres minuscules, comme dans cet exemple :
${step_297}.toLowerCase()
Si la variable d'action ${step_297} contient la chaîne This is A DOG!, cette expression renvoie la chaîne this is a dog!.
String.toUpperCase()
Cette méthode renvoie la chaîne originale qui est convertie en majuscules, comme dans cet exemple :
${step_297}.toUpperCase()
Si la variable d'action ${step_297} contient la chaîne hi there, cette méthode renvoie la chaîne HI THERE.
String.trim()
Cette méthode réduit les espaces au début et à la fin d'une chaîne et renvoie la chaîne modifiée, comme dans l'exemple suivant :
${step_297}.trim()
Si la variable d'action ${step_297} contient la chaîne something is here , cette méthode renvoie la chaîne something is here.
java.lang.String support
En plus des méthodes intégrées, vous pouvez utiliser des méthodes standard de la classe java.lang.String.
java.lang.String.format()
Vous pouvez appliquer la méthode format() de chaîne Java à du texte. Pour plus d'informations sur la syntaxe à utiliser, voir Format String Syntax.
Cet exemple prend trois entiers décimaux (1, 1 et 2) et les ajoute à une phrase :
T(java.lang.String).format('%d + %d equals %d', 1, 1, 2)
La chaîne obtenue est 1 + 1 equals 2.
Cet exemple modifie l'emplacement de la décimale pour un nombre qui est collecté par une étape :
T(String).format('%.2f',${step_297})
Si la variable ${step_297} qui doit être formatée en dollars américains est 4,5, la chaîne obtenue est 4.50.
Méthodes de tableau
Ces méthodes vous aident à travailler avec des tableaux.
Array.add(value...)
Cette méthode ajoute une ou plusieurs nouvelles valeurs au tableau et renvoie true si l'opération aboutit.
${Items}.add('four', 'five')
Si Items est ['one', 'two', 'three'], cet exemple le met à jour pour devenir ['one', 'two', 'three', 'four', 'five'].
Array.addAll(Array array)
Cette méthode ajoute un tableau à un autre et renvoie null.
${Items}.addAll(${New_items})
Si Items est ['one', 'two', 'three'] et New_items est ['four', 'five', 'six'], cet exemple met à jour Items en place pour devenir ['one', 'two', 'three', 'four', 'five', 'six'].
Array.append(value...)
Cette méthode ajoute une ou plusieurs nouvelles valeurs au tableau et renvoie le résultat sous la forme d'un nouveau tableau. Le tableau d'origine n'est pas modifié.
${Items}.append('four', 'five')
Si Items est ['one', 'two', 'three'], cet exemple renvoie le nouveau tableau ['one', 'two', 'three', 'four', 'five'].
Array.clear()
Cette méthode supprime toutes les valeurs du tableau et renvoie null.
${Items}.clear()
Une fois cette expression évaluée, Items est un tableau vide ([]).
Array.contains(value)
Cette méthode renvoie true si le tableau contient un élément qui est exactement égal à la valeur d'entrée. La valeur spécifiée peut être une chaîne ou un nombre.
${Items}.contains(123)
Si Items est [123, 456, 789], cet exemple renvoie true.
Array.containsIgnoreCase(value)
Cette méthode renvoie true si le tableau contient un élément égal à la valeur d'entrée. Les chaînes sont mises en correspondance, que la valeur soit spécifiée en majuscules ou en minuscules. La valeur spécifiée peut être une chaîne
ou un nombre.
${Items}.contains('two')
Cet exemple renvoie true si le tableau Items contient une casse de la chaîne two (par exemple, TWO ou Two correspond également).
Array.filter(temp_var, "temp_var.property operator comparison_value")
Filtre un tableau en comparant chaque élément de tableau à une valeur que vous spécifiez, en renvoyant un nouveau tableau contenant uniquement les éléments correspondants.
L'expression de filtre comprend les valeurs suivantes :
-
temp_var: nom arbitraire d'une variable temporaire utilisée pour contenir chaque élément de tableau lors de son évaluation. Par exemple, si le tableau d'origine contient des objets qui décrivent des villes, vous pouvez utilisercitycomme nom de variable temporaire. -
property: propriété d'élément sur laquelle vous souhaitez filtrer. Il doit s'agir d'une propriété des éléments du tableau source. Spécifiez la propriété en tant que propriété detemp_var, à l'aide de la syntaxetemp_var.property. Par exemple, silatitudeest un nom de propriété valide pour les éléments source, vous pouvez spécifier la propriété sous la formecity.latitude. -
operator: L'opérateur à utiliser pour comparer la valeur de la propriété à la valeur de comparaison. Vous pouvez utiliser l'un des opérateurs suivants :Opérateurs de filtre pris en charge Opérateur Description ==Est égal à >Est supérieure à <Est inférieur à >=Est supérieur ou égal à <=Est inférieur ou égal à !=N'est pas égal à -
comparison_value: La valeur à laquelle vous souhaitez comparer la valeur de la propriété de chaque élément du tableau. Vous pouvez spécifier une valeur littérale ou faire référence à une variable.
Exemples de filtre
Par exemple, vous pouvez avoir un tableau d'objets qui contiennent des noms de ville et leurs numéros de population:
[
{
"name":"Tokyo",
"population":13988129
},
{
"name":"Rome",
"population":2860009
},
{
"name":"Beijing",
"population":21893095
},
{
"name":"Paris",
"population":2165423
}
]
Si le tableau source est stocké dans une variable appelée ${cities}, l'expression suivante renvoie un tableau plus petit contenant uniquement les villes dont la population est supérieure à 5 millions:
${cities}.filter("city", "city.population > 5000000")
L'expression renvoie le tableau filtré suivant :
[
{
"name":"Tokyo",
"population":13988129
},
{
"name":"Beijing",
"population":21893095
}
]
Au lieu d'une valeur de comparaison codée en dur, vous pouvez également filtrer en fonction d'une valeur dynamique stockée dans une variable. Cet exemple filtre à l'aide d'une valeur de remplissage spécifiée par une réponse du client à une étape précédente:
${cities}.filter("city", "city.population > ${step_123}")
Lorsque vous comparez des valeurs numériques, veillez à ce que la variable contextuelle impliquée dans la comparaison prenne une valeur valide avant que la méthode de filtrage ne soit déclenchée. Notez que null peut être une
valeur valide si l’élément de tableau avec lequel vous la comparez peut la contenir.
Array.get(Integer index)
Cette méthode renvoie l'élément du tableau qui se trouve à la position d'index spécifiée. Les tableaux sont indexés à zéro, ce qui signifie que le premier élément du tableau se trouve à la position d'index 0.
${Items}.get(1)
Si Items est ['one', 'two', 'three'], cet exemple renvoie two.
La méthode get() est une alternative à l'utilisation de crochets ([]) pour extraire un élément d'un tableau. L'exemple suivant est également valide et renvoie le même résultat:
${Items}[1]
Si vous utilisez une valeur spécifiée par un client pour choisir un élément dans un tableau, vous devrez peut-être la soustraire 1 pour la convertir en valeur indexée par zéro. Par exemple, vous pouvez utiliser une expression telle que ${Items}.get(${step_123} - 1) pour extraire la valeur prévue.
Array.getRandomItem()
Cette méthode renvoie un élément choisi de manière aléatoire dans le tableau.
${Items}.getRandomItem()
Si Items est ['one', 'two', 'three'], cet exemple renvoie one, two ou three de manière aléatoire.
Array.indexOf(value)
Cette méthode renvoie la position d'index de la première occurrence de la valeur d'entrée dans le tableau, ou -1 si le tableau ne contient pas la valeur d'entrée. La valeur spécifiée peut être une chaîne ou un nombre.
${Items}.indexOf(`two`)
Si Items est ['one', 'two', 'three'], cet exemple renvoie l'entier 1 (indiquant la deuxième position dans le tableau indexé à zéro).
Array.join(String delimiter)
Cette méthode joint toutes les valeurs de ce tableau à une chaîne. Les valeurs sont converties en chaîne et délimitées par le délimiteur d'entrée.
Par exemple, vous pouvez utiliser une variable nommée pizza_toppings qui contient le tableau ["pepperoni", "ham", "mushrooms"]. L'expression suivante convertit ce tableau en chaîne pepperoni, ham, mushrooms:
${toppings_array}.join(', ')
Si vous utilisez cette expression pour définir la valeur d'une variable, vous pouvez référencer cette variable dans la sortie de l'assistant pour créer un message lisible par l'utilisateur (par exemple, You have selected the following toppings: pepperoni, ham, mushrooms).
JSONArray.joinToArray(template, retainDataType)
Cette méthode extrait les informations de chaque élément du tableau et génère un nouveau tableau qui est formaté en fonction du modèle que vous spécifiez. Le modèle peut être une chaîne, un objet JSON ou un tableau. La méthode renvoie un tableau de chaînes, un tableau d'objets ou un tableau de tableaux, selon le type de modèle.
Cette méthode est utile pour le formatage d'informations sous forme de chaîne que vous pouvez renvoyer dans le cadre de la sortie d'une étape ou pour la transformation de données dans une structure différente afin de pouvoir l'utiliser avec une API externe.
Dans le modèle, vous pouvez référencer des valeurs du tableau source à l'aide de la syntaxe suivante:
%e.{property}%
où {property} représente le nom de la propriété dans le tableau source.
Par exemple, supposons que votre assistant stocke un tableau contenant les détails du vol dans une variable de session. Les données stockées peuvent se présenter comme suit:
"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"
}
]
Pour générer un tableau de chaînes décrivant ces vols sous une forme lisible par l'utilisateur, vous pouvez utiliser l'expression suivante:
${Flight_data}.joinToArray("Flight %e.flight% to %e.destination%", true)
Cette expression renvoie le tableau de chaînes suivant: ["Flight AZ1040 to FCO","Flight DL1710 to LAX","Flight VS4379 to LHR"].
Le paramètre retainDataType facultatif indique si la méthode conserve le type de données de toutes les valeurs d'entrée dans le tableau renvoyé. Si retainDataType est défini sur false ou omis, dans certains
cas, les chaînes du tableau d'entrée peuvent être converties en nombres dans le tableau renvoyé. Par exemple, si les valeurs sélectionnées dans le tableau d'entrée sont "1", "2" et "3",
le tableau renvoyé peut être [ 1, 2, 3 ]. Pour éviter des conversions de type inattendues, spécifiez true pour ce paramètre.
Modèles complexes
Un modèle plus complexe peut contenir un formatage qui affiche les informations dans une présentation lisible. Pour un modèle complexe, vous pouvez stocker le modèle dans une variable de session, que vous pouvez ensuite transmettre à la
méthode joinToArray au lieu d'une chaîne.
Par exemple, ce modèle complexe contient un sous-ensemble des éléments de tableau, en ajoutant des libellés et du formatage:
<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/>
Assurez-vous que le formatage que vous utilisez dans votre modèle est pris en charge par l'intégration de canal qui affiche la sortie de l'assistant.
Si vous créez une variable de session nommée Template et que vous affectez cette valeur à ce modèle, vous pouvez utiliser cette variable dans vos expressions:
${Flight_data}.joinToArray(${Template})
Au moment de l'exécution, la réponse ressemblerait à ceci :
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
Modèles JSON
Au lieu d'une chaîne, vous pouvez définir un modèle en tant qu'objet JSON, ce qui permet de normaliser le formatage des informations provenant de différents systèmes ou de transformer les données dans le format requis pour un service externe.
Dans cet exemple, un modèle est défini en tant qu'objet JSON qui extrait les détails de vol des éléments spécifiés dans le tableau stocké dans la variable de session 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%."
}
A l'aide de ce modèle, la méthode joinToArray() renvoie un nouveau tableau d'objets avec la structure spécifiée.
Array.remove(Integer index)
Cette méthode supprime du tableau l'élément situé à la position d'index spécifiée et renvoie le tableau mis à jour.
${Items}.remove(1)
Si Items est ['one', 'two', 'three'], cet exemple renvoie ['one', 'three']. Le tableau Items d'origine est également modifié en place.
Array.removeValue(value)
Cette méthode supprime la première occurrence de la valeur spécifiée dans le tableau et renvoie le tableau mis à jour. La valeur spécifiée peut être une chaîne ou un nombre.
${Items}.removeValue('two')
Si Items est ['one', 'two', 'three'], cet exemple renvoie ['one', 'three']. Le tableau Items d'origine est également modifié en place.
Array.set(Integer index, value)
Cette méthode remplace l'élément dans la position d'index spécifiée par la valeur spécifiée et renvoie le tableau mis à jour.
${Items}.set(2,'five')
Si Items est ['one', 'two', 'three'], cet exemple renvoie ['one', 'two', 'five']. Le tableau Items d'origine est également modifié en place.
Array.size()
Cette méthode renvoie le nombre d'éléments du tableau sous la forme d'un entier.
${Items}.size()
Si Items est ['one', 'two', 'three'], cet exemple renvoie 3.
Array.sort()
Cette méthode effectue un tri interne et renvoie le tableau trié. Le paramètre par défaut est ascending. Vous pouvez spécifier descending pour modifier l'ordre de tri. Toute autre entrée de paramètre est ignorée et
une erreur de journal apparaît.
${Items}.sort("ascending")
La méthode compare les nombres et les chaînes. Un nombre est toujours plus petit qu'une chaîne. Tout autre type est converti en chaîne par défaut pour la comparaison.
Exemple :
| Tableau d'origine | Tableau trié |
|---|---|
| [2,1,3,5,4,3,2] | [1,2,2,3,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()
La méthode Array.transform() est utilisée avec Variable session_history uniquement. Vous pouvez transformer la sortie de la
variable pour qu'elle corresponde à un système d'IA générative spécifique.
Tableau: Signatures pour les formats de discussion affiche les signatures que vous pouvez utiliser pour les différents formats de discussion:
| Détails | OpenAI | Google PaLM2 | Llama2 |
|---|---|---|---|
| Signature | 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) |
| Format de message client | {$rolePrefix: $userPrefix, "content": $content} |
{$rolePrefix: $userPrefix, "content": $content} |
<s>[INST] <<SYS>>{{ $systemPrompt }} <</SYS>>{{ $user_content }} [/INST] {{ $assistant_content }} </s><s>[INST] {{ $user_content }} [/INST] |
| Format de message de l'assistant | {$rolePrefix: $assistantPrefix, "content": $content} |
{$rolePrefix: $assistantPrefix, "content": $content} |
ND |
| Exemple | ${system_session_history}.transform("role", "user", "assistant") |
${system_session_history}.transform("author", "USER", "AI") |
${system_session_history}.transform("<your system prompt>") |
Si currentAction a pour valeur true:
| Utilisations de l'assistant | Description |
|---|---|
| Actions uniquement | La transformation exclut tous les messages pour lesquels n a la valeur true, ce qui indique qu'une question client a déclenché une nouvelle action de base. |
| Boîte de dialogue uniquement | currentAction est ignoré et la transformation inclut l'intégralité du contenu de la variable session history. |
| Dialogue et actions | La transformation inclut tous les éléments de la variable session_history depuis le démarrage le plus récent d'une action, que des noeuds de dialogue soient déclenchés ou non. |
Les indicateurs n : true ne sont pas inclus dans la sortie de la transformation.