Expressions permettant d'accéder aux objets de la boîte de dialogue

Vous pouvez écrire des expressions permettant d'accéder à des objets et à des propriétés d'objets à l'aide du langage SpEL (Spring Expression). Pour plus d'informations, voir Spring Expression Language(SpEL).

Syntaxe d'évaluation

Pour développer des valeurs de variable dans d'autres variables ou appeler des méthodes sur des propriétés et des objets globaux, utilisez la syntaxe d'expression <? expression ?>. Exemple :

  • Développement d'une propriété

    "output":{"text":"Your name is <? context.userName ?>"}

  • Appel de méthodes sur des propriétés d'objets globaux

    "context":{"email": "<? @email.literal ?>"}

Syntaxe abrégée

Apprenez à référencer rapidement les objets suivants à l'aide de la syntaxe abrégée SpEL :

Syntaxe abrégée pour les variables contextuelles

Le tableau suivant présente des exemples de la syntaxe abrégée que vous pouvez utiliser pour écrire des variables contextuelles dans des expressions de condition.

Syntaxe abrégée
Syntaxe abrégée Syntaxe complète en SpEL
$card_type context['card_type']
$(card-type) context['card-type']
$card_type:VISA context['card_type'] == 'VISA'
$card_type:(MASTER CARD) context['card_type'] == 'MASTER CARD'

Vous pouvez inclure des caractères spéciaux, par exemple, des traits d'union ou des points, dans des noms de variable contextuelle. Cependant, cela peut entraîner des problèmes lors de l'évaluation de l'expression SpEL. Le trait d'union peut être interprété comme un signe moins, par exemple. Pour éviter ce genre de problèmes, référencez la variable en utilisant la syntaxe d'expression complète ou la syntaxe abrégée $(variable-name) et n'utilisez pas les caractères spéciaux suivants dans le nom :

  • Parenthèses()
  • Plusieurs apostrophes ''
  • Apostrophes"

Lorsque vous faites référence à une variable contextuelle dans une réponse textuelle ou une condition de noeud de dialogue, vous pouvez utiliser la syntaxe abrégée.

Par exemple, Hello, $name. Si la variable contextuelle $name contient Sam, la réponse est Hello, Sam.

Si vous souhaitez faire référence à une variable contextuelle en utilisant la syntaxe complète dans une réponse textuelle, veillez à entourer la variable contextuelle de <? ?>. Par exemple, Hello, <? context['name'] ?>.

Si vous souhaitez référencer une variable contextuelle comportant plusieurs zones, telles que $context.integrations.chat.browser_info.page_url. Pour utiliser la syntaxe complète, spécifiez <? context['integrations']['chat']['browser_info']['page_url'] ?>.

Syntaxe abrégée pour les entités

Le tableau suivant présente des exemples de la syntaxe abrégée que vous pouvez utiliser lorsque vous faites référence à des entités.

Syntaxe abrégée
Syntaxe abrégée Syntaxe complète en SpEL
@year entities['year']?.value
@year == 2016 entities['year']?.value == 2016
@year != 2016 entities['year']?.value != 2016
@city == 'Boston' entities['city']?.value == 'Boston'
@city:Boston entities['city']?.contains('Boston')
@city:(New York) entities['city']?.contains('New York')

Dans SpEL, le point d'interrogation (?) empêche le déclenchement d'une exception de pointeur null lorsqu'un objet d'entité est null.

Si la valeur d'entité que vous souhaitez rechercher contient un caractère ), vous ne pouvez pas utiliser l'opérateur : pour la comparaison. Par exemple, si vous souhaitez vérifier si l'entité de ville est Dublin (Ohio), vous devez utiliser @city == 'Dublin (Ohio)' au lieu de @city:(Dublin (Ohio)).

Syntaxe abrégée pour les intentions

Le tableau suivant présente des exemples de la syntaxe abrégée que vous pouvez utiliser lorsque vous faites référence à des intentions.

| Syntaxe courte | Syntaxe complète dans SpEL | | #help | intent == 'help' | | ! #help | intent != 'help' | | NOT #help | intent != 'help' | | #help ou #i_am_lost | (intent == 'help' \|\| intent == 'I_am_lost') |

Variables globales intégrées

Vous pouvez utiliser le langage d'expression pour extraire les informations de propriété des variables globales suivantes :

Variables globales
Variable globale Définition
Contexte Partie d'objet JSON du message de conversation traité.
entités[ ] Liste des entités qui prennent en charge l'accès par défaut au 1st élément.
entrée Partie d'objet JSON du message de conversation traité.
intentions[ ] Liste d'intentions qui prend en charge l'accès par défaut au premier élément.
sortie Partie d'objet JSON du message de conversation traité.

Accès à des entités

Le tableau des entités contient une ou plusieurs entités qui ont été reconnues dans l'entrée utilisateur.

Lorsque vous testez votre dialogue, vous pouvez voir les détails des entités reconnues dans les entrées utilisateur en spécifiant cette expression dans la réponse d'un nœud de dialogue :

<? entities ?>

Pour l'entrée utilisateur, aujourd'hui, votre assistant reconnaît l'entité système @sys, de sorte que la réponse contient cet objet d'entité :

 [
   {
     "entity":"sys-date",
     "location":[0,5],
     "value":"2020-12-30",
     "confidence":1.0,
     "metadata":
     {
       "calendar_type":"GREGORIAN",
       "timezone":"America/New_York"
     },
     "interpretation":
     {
       "timezone":"America/New_York",
       "relative_day":0,
       "granularity":"day",
       "calendar_type":"GREGORIAN"
      }
    }
  ]

Si vous souhaitez inclure du texte dans la réponse, utilisez la méthode toJson() dans l'expression pour lancer la liste des entités renvoyées dans un objet JSON. Exemple :

Recognized entities are: <? entities.toJson() ?>

Importance de l'emplacement des entités dans l'entrée

Lorsque vous utilisez l'expression abrégée @city.contains('Boston') dans une condition, le nœud de dialogue renvoie vrai seulement si Boston est la première entité détectée dans l'entrée de l'utilisateur. N'utilisez cette syntaxe que si l'emplacement des entités dans l'entrée vous importe et que vous souhaitez vérifier la première mention uniquement.

Utilisez l'expression SpEL complète si vous souhaitez que la condition renvoie un résultat positif chaque fois que le terme est mentionné dans l'entrée de l'utilisateur, quel que soit l'ordre dans lequel les entités sont mentionnées. La condition entities['city']?.contains('Boston') renvoie un résultat positif lorsqu'au moins une entité "Boston" se trouve dans toutes les entités @city, quel que soit leur emplacement.

Par exemple, un utilisateur soumet "I want to go from Toronto to Boston." Le @city:Toronto et @city:Boston les entités sont détectées et sont représentées dans le tableau qui est retourné comme suit :

  • entities.city[0].value = 'Toronto'
  • entities.city[1].value = 'Boston'

L'ordre des entités dans le tableau renvoyé correspond à l'ordre dans lequel elles sont mentionnées dans l'entrée utilisateur.

Propriétés d'entité

Chaque entité possède un ensemble de propriétés qui lui sont associées. Vous pouvez accéder aux informations sur une entité via ses propriétés.

Propriétés d'entité
Propriété Définition Conseils d'utilisation
niveau de fiabilité Pourcentage décimal qui représente la confiance de votre assistant dans l'entité reconnue. La confiance d'une entité est soit 0, soit 1, sauf si vous activez la correspondance floue des entités. Lorsque la fonction Fuzzy Matching est activée, le seuil de la cote de confiance par défaut est 0.3. Que la correspondance floue soit activée ou non, les entités du système ont toujours un niveau de confiance de 1.0 Vous pouvez utiliser cette propriété dans une condition de sorte que celle-ci renvoie la valeur false si la cote de confiance n'est pas supérieure à un pourcentage que vous spécifiez.
Emplacement Un décalage de caractère basé sur des zéros indiquant où les valeurs d'entité détectées commencent et finissent dans le texte d'entrée. Utilisez .literal pour extraire le passage de texte entre les valeurs de début et de fin qui sont stockées dans la propriété location.
valeur Valeur d'entité identifiée dans l'entrée. Cette propriété renvoie la valeur d'entité telle qu'elle est définie dans les données d'apprentissage, même si la correspondance a été établie avec l'un des synonymes qui lui sont associés. Vous pouvez utiliser .values pour capturer plusieurs occurrences d'une entité qui peuvent être présentes dans l'entrée utilisateur.

Exemples d'utilisation de propriété d'entité

Dans les exemples ci-dessous, la compétence contient une entité d'aéroport ayant pour valeur JFK et le synonyme 'aéroport Kennedy". L'utilisateur indique qu' il souhaite se rendre à l'aéroport Kennedy.

  • Pour renvoyer une réponse spécifique si l'entité "JFK" est reconnue dans la saisie de l'utilisateur, vous pouvez ajouter cette expression à la condition de réponse : entities.airport[0].value == 'JFK' ou @airport = "JFK"

  • Pour renvoyer le nom de l'entité tel qu'il a été spécifié par l'utilisateur dans la réponse au dialogue, utilisez la propriété .literal : So you want to go to <?entities.airport[0].literal?>... ou So you want to go to @airport.literal ...

Les deux formats évaluent So you want to go to Kennedy Airport... dans la réponse.

  • Des expressions comme @airport:(JFK) ou @airport.contains('JFK') font toujours référence à la valeur de l'entité (JFK dans cet exemple).

  • Pour restreindre les termes qui sont identifiés comme des aéroports dans l'entrée lorsque la fonction Fuzzy Matching est activée, vous pouvez spécifier cette expression dans une condition de noeud, par exemple :@airport && @airport.confidence > 0.7. Le nœud ne s'exécute que si votre assistant est sûr à 70 % que le texte d'entrée contient une référence à un aéroport.

Dans l'exemple suivant, l'entrée utilisateur est Est-il possible de changer des devises à JFK, Logan et O'Hare ?

  • Afin de capturer plusieurs occurrences d'un type d'entité dans l'entrée utilisateur, utilisez une syntaxe semblable à celle présentée ci-dessous :

    "context":{
  "airports":"@airport.values"
}

    Pour faire référence ultérieurement à la liste capturée dans une réponse de dialogue, utilisez cette syntaxe : You asked about these airports: <? $airports.join(', ') ?>. Il apparaît comme suit : You asked about these airports: JFK, Logan, O'Hare.

  • Pour capturer les valeurs littérales de plusieurs mentions d'entités, utilisez la syntaxe suivante :

    entities['myEntityName'].![literal]

Accès à des intentions

Le tableau des intentions contient une ou plusieurs intentions reconnues par l'utilisateur, classées par ordre décroissant de confiance.

Chaque intention ne contient qu'une seule propriété, nommée confidence. La propriété confidence est un pourcentage décimal qui représente la cote de confiance de l'assistant dans l'intention reconnue.

Lorsque vous testez votre dialogue, vous pouvez voir les détails des intentions reconnues dans les entrées utilisateur en spécifiant cette expression dans la réponse d'un nœud de dialogue :

<? intents ?>

Pour l'entrée utilisateur Hello now, l'assistant trouve une correspondance exacte avec l'intention #greeting. Par conséquent, il répertorie en premier les détails de l'objet d'intention #greeting. La réponse inclut également les 10 autres premières intentions définies dans la compétence, quelle que soit leur cote de confiance. (Dans cet exemple, la cote de confiance du service pour les autres intentions a pour valeur 0 car la première intention est une correspondance exacte.) Les 10 premières intentions sont renvoyées car le panneau"Try it out" envoie le paramètre alternate_intents:true avec sa demande. Si vous utilisez directement l'API et que vous souhaitez voir les 10 premiers résultats, prenez soin de spécifier ce paramètre dans votre appel. Si alternate_intents est faux, ce qui est la valeur par défaut, seules les intentions dont le degré de confiance est supérieur à 0.2 sont renvoyées dans le tableau.

[{"intent":"greeting","confidence":1},
{"intent":"yes","confidence":0},
{"intent":"pizza-order","confidence":0}]

Si vous souhaitez inclure du texte dans la réponse, utilisez la méthode toJson() dans l'expression pour jeter la liste des intentions renvoyés dans un objet JSON. Exemple :

Recognized intents are: <? intents.toJson() ?>

Les exemples suivants montrent comment rechercher une valeur d'intention :

  • intents[0] == 'Help'
  • intent == 'Help'

intent == 'help' est différent de intents[0] == 'help' car intent == 'help' n'émet pas une exception si aucune intention n'est détectée. L'intention renvoie la valeur true uniquement si sa cote de confiance est supérieure à un seuil. Si vous le souhaitez, vous pouvez spécifier un niveau de confiance personnalisé pour une condition, par exemple intents.size() > 0 && intents[0] == 'help' && intents[0].confidence > 0.1.

Accès à une entrée

L'objet JSON d'entrée contient une seule propriété, text. La propriété text représente le texte de l'entrée utilisateur.

Exemples d'utilisation de propriété d'entrée

L'exemple suivant montre comment accéder à une entrée :

  • Pour exécuter un nœud si l'entrée de l'utilisateur est "Oui", ajoutez cette expression à la condition du nœud : input.text == 'Yes'

Vous pouvez utiliser n'importe laquelle des méthodes String pour évaluer ou manipuler le texte de l'entrée utilisateur. Exemple :

  • Pour vérifier si l'entrée utilisateur contient "Yes", utilisez : input.text.contains( 'Yes' ).
  • La valeur true est renvoyée si l'entrée utilisateur est un nombre : input.text.matches( '[0-9]+' ).
  • Pour vérifier si la chaîne d'entrée contient dix caractères, utilisez : input.text.length() == 10.