Condividi tramite

Informazioni sui dialoghi componenti e a cascata

si applica a: SDK v4

I dialoghi sono disponibili in alcuni tipi diversi. Questo articolo descrive i dialoghi componente, a cascata e di richiesta. Per informazioni sulle finestre di dialogo in generale, consultare l'articolo libreria di finestre di dialogo. Per informazioni sui dialoghi adattivi, vedere l'introduzione ai dialoghi adattivi.

Un dialogo a cascata (o waterfall) definisce una sequenza di passaggi, consentendo al bot di guidare un utente attraverso un processo lineare. Questi dialoghi sono progettati per funzionare all'interno del contesto di un dialogo componente.

Un dialogo componente è un tipo di finestra di dialogo contenitore che consente ai dialoghi nel set di chiamare altri dialoghi nel set, ad esempio un dialogo a cascata che chiama i dialoghi di richiesta o un altro dialogo a cascata. I dialoghi componenti gestiscono un set di dialoghi figlio , ad esempio dialoghi a cascata, richieste e così via. È possibile progettare una finestra di dialogo del componente per gestire attività specifiche e riutilizzarla, nello stesso bot o in più bot.

Le finestre di dialogo di richiesta (prompt) sono finestre di dialogo progettate per chiedere all'utente tipi specifici di informazioni, ad esempio un numero, una data o un nome e così via. I prompt sono progettati per lavorare con i dialoghi a cascata in una finestra di dialogo componente.

Finestre di dialogo dei componenti

A volte si vuole scrivere una finestra di dialogo riutilizzabile da usare in scenari diversi, ad esempio una finestra di dialogo di indirizzo che chiede all'utente di fornire valori per strada, città e codice postale.

Il dialogo componente fornisce una strategia per la creazione di dialoghi indipendenti per gestire scenari specifici, suddividendo un set di dialoghi di grandi dimensioni in parti più gestibili. Ognuna di queste parti ha un proprio set di dialoghi ed evita conflitti di nomi con il set di dialoghi che lo contiene. Per maggiori informazioni, consultare le istruzioni nella finestra di dialogo del componente.

Dialoghi a cascata

Un dialogo a cascata è un'implementazione specifica di un dialogo comunemente usato per raccogliere informazioni dall'utente o guidare l'utente attraverso una serie di attività. Ogni passaggio della conversazione viene implementato come funzione asincrona che accetta un parametro chiamato contesto del passaggio a cascata (step). A ogni passaggio, il bot sollecita l'utente per un input (o può iniziare un dialogo figlio, anche se spesso è un sollecito), attende una risposta e quindi passa il risultato al passaggio successivo. Il risultato della prima funzione viene passato come argomento alla funzione successiva e così via.

Il diagramma seguente illustra una sequenza di passaggi a cascata e le operazioni dello stack che vengono eseguite. I dettagli sull'uso dello stack di dialoghi sono riportati di seguito nella sezione using dialogs (Uso dei dialoghi ).

Rappresentazione di come i messaggi si mappano ai passaggi a cascata.

All'interno dei passaggi a cascata, il contesto del dialogo a cascata viene archiviato nel contesto del passaggio a cascata. Il contesto del passaggio è simile al contesto del dialogo e fornisce l'accesso al contesto e allo stato del turno corrente. Utilizzare l'oggetto contesto del passo a cascata per interagire con un insieme di dialoghi all'interno di un passo a cascata.

È possibile gestire un valore restituito da un dialogo all'interno di un passaggio a cascata in una finestra di dialogo o dal gestore dei turni del bot, anche se in genere è sufficiente controllare lo stato del risultato del turno del dialogo dalla logica dei turni del bot. All'interno di un passaggio a cascata, il dialogo fornisce il valore restituito nella proprietà result del contesto del passaggio a cascata.

Proprietà del contesto del passaggio a cascata

Nel contesto del passaggio a cascata sono presenti le seguenti proprietà:

  • Opzioni: contiene informazioni di input per la finestra di dialogo.
  • Valori: contiene informazioni che è possibile aggiungere al contesto e vengono inoltrate nei passaggi successivi.
  • Risultato: contiene il risultato del passaggio precedente.

Inoltre, il metodo next (NextAsync in C#, next in JavaScript e Python) passa al passaggio successivo del dialogo a cascata nello stesso turno, permettendo al bot di saltare un determinato passaggio, se necessario.

Suggerimenti

Le richieste, all'interno della libreria dialogs, offrono un modo semplice per chiedere all'utente informazioni e valutare la risposta. Ad esempio, per una richiesta di numeri, si specificano la domanda o le informazioni richieste e la richiesta verifica automaticamente se ha ricevuto una risposta numerica valida. In caso affermativo, la conversazione può proseguire; in caso contrario, verrà richiesto nuovamente all'utente di fornire una risposta valida.

Dietro le quinte, le richieste sono un dialogo in due passaggi. Innanzitutto, il prompt chiede l'input; in secondo luogo, restituisce il valore valido o ricomincia dall'inizio con un nuovo prompt.

I prompt hanno opzioni di prompt specificate quando il prompt viene richiamato. È qui che puoi indicare il testo da visualizzare, il prompt per ripetere in caso di fallimento della validazione, e le opzioni di risposta al prompt. In generale, le proprietà di richiesta e di ripetizione sono attività, anche se esistono alcune varianti sul modo in cui questo viene gestito nei diversi linguaggi di programmazione.

Inoltre, è possibile scegliere di aggiungere una convalida personalizzata per la richiesta quando la crei. Si supponga, ad esempio, di voler ottenere una dimensione del gruppo utilizzando l'inserimento numerico, ma questa dimensione deve essere superiore a 2 e inferiore a 12. Il prompt controlla prima di tutto se ha ricevuto un numero valido, quindi esegue la convalida personalizzata se viene fornita. Se la convalida personalizzata ha esito negativo, l'utente verrà riprovato come indicato in precedenza.

Al termine di un prompt, restituisce in modo esplicito il valore risultante richiesto. Quando viene restituito tale valore, è possibile assicurarsi che sia stata superata la convalida della richiesta predefinita e qualsiasi convalida personalizzata aggiuntiva che potrebbe essere stata fornita.

Per esempi sull'uso di vari prompt, vedere come usare la libreria dialogs per raccogliere l'input dell'utente.

Tipi di richieste

Dietro le quinte, le richieste sono un dialogo in due passaggi. Prima di tutto, il prompt chiede l'input; in secondo luogo, restituisce il valore valido o riparte dall'inizio con una riproposta. La libreria dialogs offre varie richieste di base, ognuna usata per raccogliere un tipo di risposta diverso. Le richieste di base possono interpretare l'input del linguaggio naturale, ad esempio "dieci" o "una dozzina" per un numero o "domani" o "venerdì alle 10:00" per una data e ora.

Rapido Descrizione Restituzioni
Prompt degli allegati Richiede uno o più allegati, ad esempio un documento o un'immagine. Raccolta di oggetti allegati .
Richiesta di scelta Richiede una scelta da un set di opzioni. Oggetto scelta trovata.
Conferma richiesta Richiede una conferma. Valore booleano.
Richiesta di data e ora Richiede una data/ora. Raccolta di oggetti di risoluzione di data e ora .
Richiesta di numero Chiede un numero. Valore numerico.
Richiesta di testo Richiede un input generico di testo. Una stringa.

Per richiedere input a un utente, definire una richiesta usando una delle classi predefinite, ad esempio la richiesta di testo e aggiungerla al set di dialoghi. I prompt hanno ID fissi che devono essere univoci all'interno di un set di dialoghi. È possibile avere un validator personalizzato per ogni richiesta e, per alcune richieste, è possibile specificare le impostazioni locali predefinite.

Impostazioni del prompt locale

Le impostazioni locali vengono usate per determinare il comportamento specifico della lingua delle richieste di scelta, conferma, data e numero . Per qualsiasi input specificato dall'utente, se il canale ha fornito una proprietà di locale nel messaggio dell'utente, viene utilizzata. In caso contrario, se le impostazioni locali predefinite del prompt sono impostate, fornendolo quando si chiama il costruttore del prompt o impostandolo in un secondo momento, tale impostazione viene usata. Se nessuna di queste impostazioni locali viene specificata, l'inglese ("en-us") viene usato come impostazioni locali.

Le impostazioni locali sono un codice ISO 639 a due, tre o quattro caratteri che rappresenta una lingua o una famiglia di lingue.

Opzioni prompt

Il secondo parametro del metodo prompt del contesto del passaggio accetta un oggetto opzioni prompt , con le proprietà seguenti.

Proprietà Descrizione
Suggerimento L'attività iniziale da inviare all'utente per chiedere il loro contributo.
Richiesta di ripetizione dei tentativi Attività da inviare all'utente se il primo input non è stato convalidato.
Scelte Elenco di scelte tra cui scegliere l'utente, da usare con una richiesta di scelta.
convalide Parametri aggiuntivi da usare con un validator personalizzato.
stile Definisce il modo in cui le scelte per un prompt di scelta o una richiesta di conferma verranno presentate a un utente.

È sempre necessario specificare l'attività di richiesta iniziale da inviare all'utente e una richiesta di ripetizione dei tentativi per le istanze quando l'input dell'utente non viene convalidato.

Se l'input dell'utente non è valido, la richiesta di ripetizione dei tentativi viene inviata all'utente; se non è stato specificato alcun nuovo tentativo, viene usato il prompt iniziale. Tuttavia, se un'attività viene inviata all'utente dall'interno del validator, non viene inviata alcuna richiesta di ripetizione dei tentativi.

Convalida immediata

È possibile convalidare una risposta rapida prima di restituire il valore al passaggio successivo del flusso a cascata. Una funzione validator ha un parametro di contesto del validator prompt e restituisce un valore Boolean, che indica se l'input supera la convalida. Il contesto del prompt del validatore include le seguenti proprietà:

Proprietà Descrizione
contesto Contesto del turno corrente per il bot.
Riconosciuto Risultato del riconoscimento prompt che contiene informazioni sull'input dell'utente, così come è stato elaborato dal riconoscitore.
Opzioni Contiene le opzioni del prompt fornite nella chiamata per avviare il prompt.

Il risultato del riconoscimento prompt ha le proprietà seguenti:

Proprietà Descrizione
Riuscito Indica se il riconoscitore è stato in grado di analizzare l'input.
Valore Valore restituito dal riconoscitore. Se necessario, il codice di convalida può modificare questo valore.

Uso di dialoghi

I dialoghi possono essere considerati come uno stack programmatico, che chiamiamo stack di dialoghi, con il gestore dei turni come quello che lo indirizza e funge da fallback se lo stack è vuoto. L'elemento più in alto in tale stack viene considerato il dialogo attivo e il contesto del dialogo indirizza tutti gli input al dialogo attivo.

Quando un dialogo inizia, viene inserito nello stack ed è ora il dialogo attivo. Rimane il dialogo attivo fino a quando non termina, viene rimosso dal metodo replace dialog oppure un altro dialogo viene inserito nello stack (dal gestore dei turni o dal dialogo attivo stesso) e diventa il dialogo attivo. Quando quel nuovo dialogo si conclude, viene rimosso dallo stack e il dialogo sottostante torna ad essere il dialogo attivo. In questo modo è possibile ripetere un dialogo o diramare una conversazione, descritta di seguito.

È possibile iniziare o continuare una finestra di dialogo radice usando il metodo di estensione run dialog. Dal codice del bot, la chiamata al metodo di estensione dell'esecuzione della finestra di dialogo continua la finestra di dialogo esistente oppure avvia una nuova istanza del dialogo se lo stack è attualmente vuoto. Il controllo e l'input dell'utente passa alla finestra di dialogo attiva nello stack.

Il metodo run richiede una funzione di accesso alle proprietà di stato per accedere allo stato del dialogo. La funzione di accesso viene creata e usata allo stesso modo di altre funzioni di accesso allo stato, ma viene creata come proprietà personalizzata in base allo stato della conversazione. I dettagli sulla gestione dello stato sono disponibili nell'argomento relativo alla gestione dello stato e l'utilizzo dello stato della finestra di dialogo è illustrato nel flusso di conversazione sequenziale .

Dall'interno di un dialogo è possibile accedere al contesto del dialogo e usarlo per avviare altre finestre di dialogo, terminare il dialogo corrente ed eseguire altre operazioni.

Per avviare una finestra di dialogo

Dall'interno di un dialogo a cascata, passa l'ID del dialogo che si desidera avviare nel contesto del dialogo a cascata usando un metodo begin dialog, prompt o replace dialog.

  • I metodi prompt e begin dialog eseguiranno il push di una nuova istanza della finestra di dialogo a cui si fa riferimento nella parte superiore dello stack.
  • Il metodo replace dialog rimuoverà il dialogo corrente dallo stack e aggiungerà il dialogo sostitutivo nello stack. La finestra di dialogo sostituita viene annullata e tutte le informazioni contenute nell'istanza vengono eliminate.

Usare il parametro options per passare informazioni alla nuova istanza del dialogo. È possibile accedere alle opzioni passate nella nuova finestra di dialogo tramite la proprietà options del contesto del passaggio in qualsiasi passaggio della finestra di dialogo. Per altre informazioni, vedere Come creare un flusso di conversazione avanzato usando rami e cicli.

Per continuare un dialogo

All'interno di un dialogo a cascata, usare la proprietà valori del contesto del passaggio per rendere persistente lo stato tra turni. Qualsiasi valore aggiunto a questa raccolta in un turno precedente è disponibile nei turni successivi. Per altre informazioni, vedere Come creare un flusso di conversazione avanzato usando rami e cicli.

Per terminare un dialogo

All'interno di un dialogo a cascata, usare il metodo end dialog per terminare un dialogo e rimuovendolo dallo stack. Il metodo end dialog può restituire un risultato facoltativo al contesto padre, ad esempio il dialogo che lo ha chiamato o il gestore dei turni del bot. Questa operazione viene spesso chiamata dall'interno del dialogo per terminare l'istanza corrente di se stessa.

È possibile chiamare il metodo del dialogo finale da qualsiasi punto in cui si dispone di un contesto di dialogo, ma sembra che il bot sia stato chiamato dal dialogo attivo corrente.

Suggerimento

È consigliabile chiamare in modo esplicito il metodo end dialog alla fine del dialogo.

Per cancellare tutti i dialoghi

Se si desidera visualizzare tutti i dialoghi dallo stack, è possibile cancellare lo stack di dialoghi chiamando il metodo annulla tutti i dialoghi del contesto del dialogo.

Ripetizione di un dialogo

È possibile sostituire un dialogo con se stesso, creando un ciclo, usando il metodo replace dialog . Si tratta di un ottimo modo per gestire interazioni complesse e una tecnica per la gestione dei menu.

Annotazioni

Se è necessario rendere persistente lo stato interno per la finestra di dialogo corrente, sarà necessario passare le informazioni alla nuova istanza del dialogo nella chiamata al metodo replace dialog e quindi inizializzare il dialogo in modo appropriato.

Creare un ramo di una conversazione

Il contesto del dialogo mantiene lo stack di dialoghi e per ogni dialogo nello stack, tiene traccia del passaggio successivo. Il metodo begin dialog crea un elemento figlio e inserisce tale finestra di dialogo nella parte superiore dello stack e il relativo metodo di dialogo finale apre la finestra di dialogo superiore dallo stack. La finestra di dialogo finale viene in genere chiamata dall'interno del dialogo che termina.

Un dialogo può avviare un nuovo dialogo all'interno dello stesso set di dialoghi chiamando il metodo begin dialog del contesto del dialogo e specificando l'ID del nuovo dialogo, che quindi rende il nuovo dialogo il dialogo attualmente attivo. Il dialogo originale è ancora nello stack, ma le chiamate al metodo continue dialog del contesto del dialogo vengono inviate solo al dialogo che si trova sopra lo stack, il dialogo attivo. Quando un dialogo viene estratto dallo stack, il contesto del dialogo riprenderà con il passaggio successivo della cascata nello stack in cui si è interrotto il dialogo originale.

Pertanto, è possibile creare un ramo all'interno del flusso di conversazione includendo un passaggio in un dialogo in grado di scegliere in modo condizionale un dialogo per avviare un set di dialoghi disponibili.

Informazioni aggiuntive