Expresiones para acceder a objetos en el diálogo

Puede escribir expresiones que accedan a objetos y propiedades de objetos mediante el lenguaje Spring Expression (SpEL). Para más información, consulte Spring Expression Language(SpEL).

Sintaxis de evaluación

Para expandir valores de variables dentro de otras variables o para invocar métodos en propiedades y objetos globales, utilice la sintaxis de expresión <? expression ?>. Por ejemplo:

  • Expansión de una propiedad

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

  • Invocación de métodos en propiedades de objetos globales

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

Sintaxis abreviada

Aprenda con rapidez a hacer referencia a los siguientes objetos utilizando la sintaxis abreviada SpEL:

Sintaxis abreviada de las variables de contexto

En la tabla siguiente se muestran ejemplos de la sintaxis abreviada que puede utilizar para escribir variables de contexto en expresiones de condición.

Sintaxis abreviada
Sintaxis abreviada Sintaxis completa 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'

Puede incluir caracteres especiales, como guiones o puntos, en los nombres de las variables de contexto. Sin embargo, hacerlo podría ocasionarle problemas al evaluar la expresión SpEL. El guión puede interpretarse como un signo menos, por ejemplo. Para evitar este tipo de problemas, haga referencia a la variable utilizando la sintaxis de expresión completa o la sintaxis abreviada $(variable-name) y no utilice los siguientes caracteres especiales en el nombre:

  • Paréntesis ()
  • Más de un apóstrofo ''
  • Comillas dobles "

Cuando hace referencia a una variable de contexto en una respuesta de texto o a una condición de nodo de diálogo, puede utilizar la sintaxis abreviada.

Por ejemplo, Hello, $name. Si la variable de contexto $name contiene Sam, la respuesta se muestra como Hello, Sam.

Si desea hacer referencia a una variable de contexto utilizando la sintaxis completa en una respuesta de texto, asegúrese de escribir la variable de contexto entre <? ?>. Por ejemplo, Hello, <? context['name'] ?>.

Si desea hacer referencia a una variable de contexto que tenga varios campos, como, por ejemplo, $context.integrations.chat.browser_info.page_url. Para utilizar la sintaxis completa, especifique <? context['integrations']['chat']['browser_info']['page_url'] ?>.

Sintaxis abreviada de las entidades

La siguiente tabla muestra ejemplos de la sintaxis abreviada que puede utilizar cuando se refiera a entidades.

Sintaxis abreviada
Sintaxis abreviada Sintaxis completa 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')

En SpEL, el signo de interrogación (?) impide que se active una excepción de puntero nulo cuando un objeto de entidad es nulo.

Si el valor de entidad que desea comprobar contiene un carácter ), no puede utilizar el operador : para la comparación. Por ejemplo, si desea comprobar si la entidad city es Dublin (Ohio), debe utilizar @city == 'Dublin (Ohio)' en lugar de @city:(Dublin (Ohio)).

Sintaxis abreviada de las intenciones

La siguiente tabla muestra ejemplos de la sintaxis abreviada que puede utilizar cuando se refiera a intents.

| Sintaxis abreviada | Sintaxis completa en SpEL | | #help | intent == 'help' | | ! #help | intent != 'help' | | NOT #help | intent != 'help' | | #help o #i_am_lost | (intent == 'help' \|\| intent == 'I_am_lost') |

Variables globales incorporadas

Utilice el lenguaje de expresiones para extraer información de propiedades para las siguientes variables globales:

Variables globales
Variable global Definición
context Parte del objeto JSON del mensaje de la conversación procesada.
entidades[ ] Lista de entidades que admiten el acceso por defecto al 1st elemento.
input Parte del objeto JSON del mensaje de la conversación procesada.
intenciones[ ] Lista de intents que admite el acceso por defecto al primer elemento.
output Parte del objeto JSON del mensaje de la conversación procesada.

Acceso a entidades

La matriz de entidades contiene una o varias entidades reconocidas en la entrada del usuario.

Mientras prueba su diálogo, puede ver los detalles de las entidades que se reconocen en la entrada del usuario especificando esta expresión en una respuesta de nodo de diálogo:

<? entities ?>

Para la entrada de usuario today, el asistente reconoce la entidad de sistema @sys-date, de modo que la respuesta contiene este objeto de entidad:

 [
   {
     "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 quiere incluir texto en la respuesta, utilice el método toJson() en la expresión para convertir la lista de entidades devueltas en un objeto JSON. Por ejemplo:

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

Cuando es importante colocar entidades en la entrada

Cuando se utiliza la expresión abreviada @city.contains('Boston') en una condición, el nodo de diálogo devuelve verdadero sólo si Boston es la primera entidad que se detecta en la entrada del usuario. Utilice esta sintaxis sólo si la colocación de las entidades en la entrada le importa y desea comprobar sólo la primera mención.

Utilice la expresión SpEL completa si desea que la condición devuelva verdadero siempre que se mencione el término en la entrada del usuario, independientemente del orden en que se mencionen las entidades. La condición entities['city']?.contains('Boston') devuelve verdadero cuando se encuentra al menos una entidad de ciudad "Boston" en todas las entidades @ciudad, independientemente de su ubicación.

Por ejemplo, supongamos que un usuario envía "I want to go from Toronto to Boston." Se detectan las entidades @city:Toronto y @city:Boston, que se representan en la matriz devuelta del modo siguiente:

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

El orden de las entidades de la matriz que se devuelve coincide con el orden en el que se mencionan en la entrada del usuario.

Propiedades de una entidad

Cada entidad tiene un conjunto de propiedades asociadas. Puede acceder a información sobre una entidad a través de sus propiedades.

Propiedades de una entidad
Propiedad Definición Consejos de uso
confidence Un porcentaje decimal que representa la confianza de su asistente en la entidad reconocida. La confianza de una entidad es 0 o 1, a menos que active la correspondencia difusa de entidades. Cuando la coincidencia aproximada está habilitada, el umbral de nivel de confianza predeterminado es 0.3. Tanto si está activada la concordancia difusa, las entidades del sistema siempre tienen un nivel de confianza de 1.0. Puede utilizar esta propiedad en una condición para que devuelva false si el nivel de confianza no es superior al porcentaje que especifique.
location Un desplazamiento de carácter basado en cero que indica dónde empiezan y terminan los valores de entidad detectados en el texto de entrada. Utilice .literal para extraer la parte de texto comprendida entre los valores de índice de inicio y fin almacenados en la propiedad location.
value La entidad value identificada en la entrada. Esta propiedad devuelve el valor de entidad tal como está definido en los datos de entrenamiento, aunque la comparación se haya realizado sobre uno de los sinónimos asociados. Puede utilizar .values para capturar varias apariciones de una entidad que pueda estar presente en la entrada de usuario.

Ejemplos de uso de propiedades de entidades

En los ejemplos siguientes, el conocimiento contiene una entidad airport que incluye el valor JFK y el sinónimo "Kennedy Airport". La entrada del usuario es Quiero ir al aeropuerto Kennedy.

  • Para devolver una respuesta específica si se reconoce la entidad "JFK" en la entrada del usuario, puede añadir esta expresión a la condición de respuesta: entities.airport[0].value == 'JFK' o @airport = "JFK"

  • Para devolver el nombre de la entidad tal y como fue especificado por el usuario en la respuesta del diálogo, utilice la propiedad .literal : So you want to go to <?entities.airport[0].literal?>... o So you want to go to @airport.literal ...

Ambos formatos se evalúan en So you want to go to Kennedy Airport... en la respuesta.

  • Las expresiones como @airport:(JFK) o @airport.contains('JFK') siempre hacen referencia al valor de la entidad (JFK en este ejemplo).

  • Para ser más restrictivo sobre los términos identificados como aeropuertos en la entrada cuando la coincidencia aproximada está habilitada, puede especificar esta expresión en una condición de nodo, por ejemplo: @airport && @airport.confidence > 0.7. El nodo sólo se ejecuta si su asistente está seguro en un 70% de que el texto de entrada contiene una referencia a un aeropuerto.

En este ejemplo, la entrada del usuario es Are there places to exchange currency at JFK, Logan, and O'Hare?

  • Para capturar varias apariciones de un tipo de entidad en la entrada del usuario, utilice una sintaxis como la siguiente:

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

    Para hacer referencia posteriormente a la lista capturada en una respuesta de diálogo, utilice esta sintaxis: You asked about these airports: <? $airports.join(', ') ?>. Se muestra de este modo: You asked about these airports: JFK, Logan, O'Hare.

  • Para capturar los valores literales para varias menciones de entidades, utilice la sintaxis siguiente:

    entities['myEntityName'].![literal]

Acceso a intenciones

La matriz de intents contiene uno o más intents que fueron reconocidos en la entrada del usuario, que se ordena en orden descendente de confianza.

Cada intención tiene una única propiedad: la propiedad confidence. La propiedad confidence es un porcentaje decimal que representa la confianza del asistente en la intención reconocida.

Mientras prueba su diálogo, puede ver los detalles de las intenciones que se reconocen en la entrada del usuario especificando esta expresión en una respuesta de nodo de diálogo:

<? intents ?>

Para la entrada de usuario, Hello now, su asistente encuentra una coincidencia exacta con la intención #greeting. Por lo tanto, lista en primer lugar los detalles del objeto de intención #greeting. La respuesta también incluye las otras 10 primeras intenciones definidas en el conocimiento independientemente de su puntuación de confianza. (En este ejemplo, su confianza en las otras intenciones se establece en 0 porque la primera intención es una coincidencia exacta). Se devuelven las otras 10 primeras intenciones porque el panel "Pruébelo" envía el parámetro alternate_intents:true con su solicitud. Si está utilizando directamente la API y desea ver los primeros 10 resultados, asegúrese de especificar este parámetro en su llamada. Si alternate_intents es falso, que es el valor por defecto, sólo se devuelven en la matriz los intents con una confianza superior a 0.2.

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

Si quiere incluir texto en la respuesta, utilice el método toJson() en la expresión para convertir la lista de intenciones devueltas en un objeto JSON. Por ejemplo:

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

En los ejemplos siguientes se muestra cómo comprobar el valor de una intención:

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

intent == 'help' difiere de intents[0] == 'help' porque intent == 'help' no genera una excepción si no se detecta ninguna intención. Solo se evalúa como true si la confianza de la intención supera un umbral. Si lo desea, puede especificar un nivel de confianza personalizado para una condición, por ejemplo, intents.size() > 0 && intents[0] == 'help' && intents[0].confidence > 0.1.

Acceso de la entrada

El objeto JSON de entrada solo contiene una propiedad: la propiedad text. La propiedad text representa el texto de la entrada del usuario.

Ejemplos de uso de propiedades de entrada

En el ejemplo siguiente se muestra cómo acceder a la entrada:

  • Para ejecutar un nodo si la entrada del usuario es "Yes", añada esta expresión a la condición del nodo: input.text == 'Yes'

Puede utilizar cualquiera de los métodos String para evaluar o manipular texto de la entrada del usuario. Por ejemplo:

  • Para comprobar si la entrada del usuario contiene "Yes", utilice: input.text.contains( 'Yes' ).
  • Devuelve true si la entrada del usuario es un número: input.text.matches( '[0-9]+' ).
  • Para comprobar si la serie de entrada contiene diez caracteres, utilice input.text.length() == 10.