Espressioni per l'accesso agli oggetti nella finestra di dialogo

Puoi scrivere le espressioni che accedono agli oggetti e alle proprietà utilizzando il linguaggio Spring Expression (SpEL). Per ulteriori informazioni, vedere Spring Expression Language(SpEL).

Sintassi della valutazione

Per espandere i valori delle variabili all'interno di altre variabili o invocare metodi su proprietà e oggetti globali, utilizzare la sintassi dell'espressione <? expression ?>. Ad esempio:

  • Espansione di una proprietà

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

  • Richiamo dei metodi sulle proprietà degli oggetti globali

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

Sintassi abbreviata

Apprendi come fare velocemente riferimento ai seguenti oggetti utilizzando la sintassi abbreviata SpEL:

Sintassi abbreviata per le variabili di contesto

La seguente tabella mostra esempi di sintassi abbreviata che puoi utilizzare per scrivere variabili di contesto nelle espressioni di condizione.

Sintassi abbreviata
Sintassi abbreviata Sintassi completa in 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'

Nei nomi delle variabili di contesto puoi includere caratteri speciali come trattini o punti. Tuttavia, ciò può causare problemi quando viene valutata l'espressione SpEL. Il trattino può essere interpretato come un segno meno, ad esempio. Per evitare tali problemi, fai riferimento alla variabile utilizzando la sintassi completa dell'espressione o la sintassi abbreviata $(variable-name) e non utilizzare i seguenti caratteri speciali nel nome:

  • Parentesi ()
  • Più di un apostrofo ''
  • virgolette "

Quando fai riferimento a una variabile di contesto in una risposta di testo o in una condizione del nodo di dialogo, puoi utilizzare la sintassi breve.

Ad esempio, Hello, $name. Se la variabile di contesto $name contiene Sam, la risposta viene visualizzata come Hello, Sam.

Se si desidera fare riferimento a una variabile di contesto utilizzando la sintassi completa in una risposta di testo, accertarsi di racchiudere la variabile di contesto in <? ?>. Ad esempio, Hello, <? context['name'] ?>.

Se si desidera fare riferimento a una variabile di contesto che ha più campi, ad esempio $context.integrations.chat.browser_info.page_url. Per utilizzare la sintassi completa, specificare <? context['integrations']['chat']['browser_info']['page_url'] ?>.

Sintassi abbreviata per le entità

La tabella seguente mostra esempi di sintassi abbreviata che si possono usare quando si fa riferimento alle entità.

Sintassi abbreviata
Sintassi abbreviata Sintassi completa in 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')

In SpEL, il punto interrogativo (?) impedisce che venga attivata un'eccezione di puntatore nullo quando un oggetto entità è nullo.

Se il valore di entità che vuoi controllare contiene un carattere ), non puoi utilizzare l'operatore : per il confronto. Ad esempio, se vuoi controllare se l'entità città è Dublin (Ohio), devi utilizzare @city == 'Dublin (Ohio)' invece di @city:(Dublin (Ohio)).

Sintassi abbreviata per gli intenti

La tabella seguente mostra esempi della sintassi stenografica che si può usare quando si fa riferimento agli intenti.

| Shorthand syntax | Sintassi completa in SpEL | | #help | intent == 'help' | | ! #help | intent != 'help' | | NOT #help | intent != 'help' | | #help o #i_am_lost | (intent == 'help' \|\| intent == 'I_am_lost') |

Variabili globali integrate

Puoi utilizzare il linguaggio dell'espressione per estrarre le informazioni sulla proprietà per le seguenti variabili globali:

Variabili globali
Variabile globale Definizione
contesto Parte di oggetto JSON del messaggio di conversazione elaborato.
entities[ ] Elenco di entità che supporta l'accesso predefinito al 1st elemento.
input Parte di oggetto JSON del messaggio di conversazione elaborato.
intenti[ ] Elenco di intenti che supporta l'accesso predefinito al primo elemento.
output Parte di oggetto JSON del messaggio di conversazione elaborato.

Accesso alle entità

L'array di entità contiene una o più entità che sono state riconosciute nell'input utente.

Mentre si testa la finestra di dialogo, si possono vedere i dettagli delle entità riconosciute nell'input dell'utente specificando questa espressione nella risposta di un nodo di dialogo:

<? entities ?>

Per l'input utente, today, il tuo assistente riconosce l'entità di sistema @sys-date, quindi la risposta contiene questo oggetto 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"
      }
    }
  ]

Se si desidera includere del testo nella risposta, utilizzare il metodo toJson() nell'espressione per eseguire il cast dell'elenco di entità restituito in un oggetto JSON. Ad esempio:

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

Importanza del posizionamento delle entità nell'input

Quando si usa l'espressione abbreviata @city.contains('Boston') in una condizione, il nodo di dialogo restituisce true solo se Boston è la prima entità rilevata nell'input dell'utente. Utilizzate questa sintassi solo se la collocazione delle entità nell'input è importante e volete controllare solo la prima menzione.

Utilizzate l'espressione SpEL completa se volete che la condizione sia vera ogni volta che il termine è menzionato nell'input dell'utente, indipendentemente dall'ordine in cui le entità sono menzionate. La condizione entities['city']?.contains('Boston') restituisce true quando almeno un'entità città 'Boston' viene trovata in tutte le entità @city, indipendentemente dal posizionamento.

Ad esempio, un utente inoltra "I want to go from Toronto to Boston." Le entità @city:Toronto e @city:Boston vengono rilevate e rappresentate nell'array restituito come segue:

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

L'ordine delle entità nell'array che viene restituito corrisponde a quello in cui vengono menzionate nell'input utente.

Proprietà di entità

Ogni entità ha un insieme di proprietà associate. Puoi accedere alle informazioni su un'entità attraverso le sue proprietà.

Proprietà di entità
Proprietà Definizione Suggerimenti sull'utilizzo
affidabilità Una percentuale decimale che rappresenta l'affidabilità del tuo assistente nell'entità riconosciuta. La confidenza di un'entità è 0 o 1, a meno che non si attivi la corrispondenza fuzzy delle entità. Se la corrispondenza fuzzy è abilitata, la soglia del livello di affidabilità predefinita è 0,3. Se la corrispondenza fuzzy è abilitata, le entità del sistema hanno sempre un livello di confidenza pari a 1.0. Puoi utilizzare questa proprietà in una condizione in modo che restituisca false se il livello di affidabilità non è superiore a una percentuale da te specificata.
ubicazione Un offset di caratteri in base zero che indica dove iniziano e terminano i valori di entità rilevati nel testo di input. Utilizza .literal per estrarre la parte di testo tra i valori di indice iniziali e finali memorizzati nella proprietà di posizione.
Valore Il valore di entità identificato nell'input. Questa proprietà restituisce il valore di entità come definito nei dati di addestramento, anche se la corrispondenza è avvenuta in uno dei suoi sinonimi associati. Puoi utilizzare .values per acquisire più ricorrenze di un'entità che potrebbero essere presenti nell'input utente.

Esempi di utilizzo delle proprietà di entità

Nei seguenti esempi, la capacità contiene un'entità aeroporto che include il valore JFK e il sinonimo 'Aeroporto Kennedy". L'input dell'utente è Voglio andare all'aeroporto Kennedy.

  • Per restituire una risposta specifica se l'entità 'JFK' viene riconosciuta nell'input dell'utente, si può aggiungere questa espressione alla condizione di risposta: entities.airport[0].value == 'JFK' oppure @airport = "JFK"

  • Per restituire il nome dell'entità così come è stato specificato dall'utente nella risposta alla finestra di dialogo, usare la proprietà .literal : So you want to go to <?entities.airport[0].literal?>... oppure So you want to go to @airport.literal ...

Entrambi i formati sono valutati da So you want to go to Kennedy Airport... nella risposta.

  • Espressioni come @airport:(JFK) o @airport.contains('JFK') fanno sempre riferimento al valore dell'entità (in questo esempio, JFK).

  • Per essere più restrittivi sui termini che vengono identificati come aeroporti nell'input quando è abilitata la corrispondenza fuzzy, puoi specificare questa espressione in una condizione del nodo, ad esempio: @airport && @airport.confidence > 0.7. Il nodo viene eseguito solo se l'assistente è sicuro al 70% che il testo in ingresso contenga un riferimento ad un aeroporto.

In questo esempio, l'input utente è Ci sono dei posti per cambiare la valuta in JFK, Logan e O'Hare?

  • Per acquisire più ricorrenze di un tipo di entità nell'input utente, utilizza una sintassi come questa:

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

    Per fare successivamente riferimento all'elenco acquisito in una risposta della finestra di dialogo, utilizzare la sintassi seguente: You asked about these airports: <? $airports.join(', ') ?>. Viene visualizzato in questo modo: You asked about these airports: JFK, Logan, O'Hare.

  • Per acquisire i valori letterali per più citazioni di entità, utilizza la seguente sintassi:

    entities['myEntityName'].![literal]

Accesso agli intenti

L'array degli intenti contiene uno o più intenti riconosciuti nell'input dell'utente, ordinati in ordine decrescente di confidenza.

Ogni intento ha un'unica proprietà: la proprietà confidence. La proprietà di affidabilità è una percentuale decimale che rappresenta l'affidabilità del tuo assistente nell'intento riconosciuto.

Mentre si testa la finestra di dialogo, si possono vedere i dettagli degli intenti riconosciuti nell'input dell'utente specificando questa espressione nella risposta di un nodo di dialogo:

<? intents ?>

Per l'input utente, Hello now, il tuo assistente trova una corrispondenza esatta con l'intento #greeting. Quindi, elenca prima i dettagli dell'oggetto di intento #greeting. La risposta include anche i primi 10 altri intenti definiti nella competenza indipendentemente dal loro punteggio di affidabilità. (In questo esempio, l'affidabilità negli altri intenti è impostata su 0 in quanto il primo intento è una corrispondenza esatta.) Vengono restituiti i primi 10 intenti in quanto il riquadro "Try it out" invia il parametro alternate_intents:true con la sua richiesta. Se stai utilizzando direttamente l'API e desideri vedere i primi 10 risultati, assicurati di specificare questo parametro nella tua chiamata. Se alternate_intents è false, che è il valore predefinito, solo gli intenti con una confidenza superiore a 0.2 vengono restituiti nell'array.

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

Se vuoi includere del testo nella risposta, utilizza il metodo toJson() nell'espressione per eseguire il cast dell'elenco di intenti restituito in un oggetto JSON. Ad esempio:

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

I seguenti esempi mostrano come controllare un valore di intento:

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

intent == 'help' è diverso da intents[0] == 'help' perché intent == 'help' non genera un'eccezione se non viene rilevato alcun intento. Viene valutato come true solo se l'affidabilità dell'intento supera una soglia. Se lo si desidera, è possibile specificare un livello di confidenza personalizzato per una condizione, ad esempio intents.size() > 0 && intents[0] == 'help' && intents[0].confidence > 0.1.

Accesso all'input

L'oggetto JSON di input contiene una sola proprietà: la proprietà di testo. La proprietà di testo rappresenta il testo dell'input utente.

Esempi di utilizzo delle proprietà di input

Il seguente esempio mostra come accedere all'input:

  • Per eseguire un nodo se l'input dell'utente è "Sì", aggiungere questa espressione alla condizione del nodo: input.text == 'Yes'

Puoi utilizzare uno qualsiasi dei Metodi stringa per valutare o manipolare il testo dell'input utente. Ad esempio:

  • Per controllare se l'input utente contiene "Yes", utilizza: input.text.contains( 'Yes' ).
  • Restituisce true se l'input utente è un numero: input.text.matches( '[0-9]+' ).
  • Per controllare se la stringa di input contiene dieci caratteri, utilizza: input.text.length() == 10.