Session class

Pacchetto:

botbuilder

Gestisce la conversazione dei bot con un utente.

Costruttori

Session(ISessionOptions)

Crea un'istanza della sessione.

Proprietà

connector	Connettore utilizzato per questa sessione.
conversationData	Dati di conversazione condivisi visibili a tutti i membri della conversazione.
dialogData	Dati visibili solo alla finestra di dialogo corrente.
library	Libreria radice dei bot di dialoghi.
localizer	Localizzatore per la sessione corrente.
message	Messaggio ricevuto dall'utente. Per i messaggi originati dal bot, questo può contenere solo i campi "to" & "from".
privateConversationData	Dati di conversazione privati visibili solo all'utente.
sessionState	Sessioni informazioni sullo stato corrente.
userData	Dati per l'utente persistente in tutte le conversazioni con il bot.

Metodi

activeDialogStackEntry(IDialogState[])	Restituisce un dialogo attivo stack o null.
beginDialog<T>(string, T)	Passa il controllo della conversazione a un nuovo dialogo. Il dialogo corrente verrà sospeso fino al completamento del dialogo figlio. Al termine del dialogo corrente, l'elemento figlio riceverà una chiamata a dialogResumed() in cui può esaminare i risultati restituiti dall'elemento figlio.
cancelDialog(string | number, string, any)	Annulla una finestra di dialogo esistente e, facoltativamente, ne avvia una nuova posizione. A differenza di endDialog() e replaceDialog() che influiscono sul dialogo corrente, questo metodo consente di terminare una finestra di dialogo padre in qualsiasi punto dello stack. L'elemento padre della finestra di dialogo annullata verrà continuato come se il dialogo avesse chiamato endDialog(). Verrà restituito uno speciale ResumeReason.canceled per indicare che la finestra di dialogo è stata annullata.
clearDialogStack()	Cancella lo stack di dialoghi corrente.
delay(number)	Inserisce un ritardo tra i messaggi in uscita.
dialogStack(IDialogState[])	Ottiene/imposta lo stack di dialoghi corrente. Viene restituita una copia della finestra di dialogo corrente in modo che, se vengono apportate modifiche allo stack restituito, sarà necessario copiarla nuovamente nella sessione tramite una seconda chiamata a session.dialogStack().
dispatch(ISessionState, IMessage, Function)	Finalizza l'inizializzazione dell'oggetto sessione e quindi indirizza la sessione attraverso tutto il middleware installato. La funzione passata in next() verrà chiamata come ultimo passaggio della catena middleware.
endConversation(TextOrMessageType, any[])	Termina la conversazione corrente e, facoltativamente, invia un messaggio all'utente.
endDialog(TextOrMessageType, any[])	Termina la finestra di dialogo corrente e, facoltativamente, invia un messaggio all'utente. L'elemento padre verrà ripreso con un IDialogResult.resumed motivo di completato.
endDialogWithResult(IDialogResult<any>)	Termina la finestra di dialogo corrente e, facoltativamente, restituisce un risultato all'elemento padre dei dialoghi.
error(Error)	Segnala che si è verificato un errore. Il bot segnalerà l'errore tramite un evento on('error', err).
findDialogStackEntry(IDialogState[], string, boolean)	Cerca uno stack di dialoghi specifico, in direzione in avanti o inversa, restituendo il relativo indice.
forEachDialogStackEntry(IDialogState[], boolean, (entry: IDialogState, index: number) => void)	Enumera tutte le voci di una finestra di dialogo in pila in una direzione in avanti o inversa.
gettext(string, any[])	Carica una stringa localizzata per la lingua dei messaggi. Se gli argomenti vengono passati, la stringa localizzata verrà considerata come un modello e formattata usando sprintf-js (vedere la documentazione relativa ai dettagli).
isReset()	Restituisce true se la sessione è stata reimpostata.
messageSent()	Restituisce true se per questa sessione è stato inviato un messaggio.
ngettext(string, string, number)	Carica la forma plurale di una stringa localizzata per la lingua dei messaggi. La stringa di output verrà formattata per includere il conteggio sostituendo %d nella stringa con il conteggio.
on(string, (data: any) => void)	Registra un listener di eventi.
popDialogStackEntry(IDialogState[])	Rimuove il dialogo attivo da uno stack e restituisce quello nuovo se lo stack non è vuoto.
preferredLocale(string, (err: Error) => void)	Restituisce le impostazioni locali preferite quando non viene specificato alcun parametro. In caso contrario, imposta le impostazioni locali preferite.
pruneDialogStack(IDialogState[], number)	Elimina tutte le voci dello stack di dialoghi che iniziano con l'indice specificato e restituisce il nuovo dialogo attivo.
pushDialogStackEntry(IDialogState[], IDialogState)	Inserisce un nuovo dialogo in uno stack e lo restituisce come finestra di dialogo attiva.
replaceDialog<T>(string, T)	Termina il dialogo corrente e ne avvia uno nuovo. La finestra di dialogo padre non verrà ripresa fino al completamento del nuovo dialogo.
reset(string, any)	Cancella lo stack di chiamate delle sessioni e riavvia la conversazione con il dialogId configurato.
routeToActiveDialog(IRecognizeResult)	Invia la sessione alla finestra di dialogo attiva o alla finestra di dialogo predefinita per l'elaborazione.
save()	Attiva il salvataggio delle modifiche apportate alla finestra di dialogo Data, userData, conversationdatao [privateConversationData'(#privateconversationdata).
say(TextType, IMessageOptions)
say(TextType, TextType, IMessageOptions)	Invia un testo e un messaggio SSML facoltativo all'utente.
sayLocalized(string, TextType, TextType, IMessageOptions)	Invia un testo e un messaggio SSML facoltativo all'utente usando uno spazio dei nomi di localizzazione specifico.
send(TextOrMessageType, any[])	Invia un messaggio all'utente.
sendBatch((err: Error, addresses?: IAddress[]) => void)	Termina immediatamente il batch corrente e recapita tutti i messaggi in coda.
sendLocalized(string, TextOrMessageType, any[])	Invia un messaggio a un utente usando uno spazio dei nomi di localizzazione specifico.
sendTyping()	Invia all'utente un'indicazione che il bot sta digitando. Per le operazioni a esecuzione prolungata, questa operazione deve essere chiamata ogni pochi secondi.
toRecognizeContext()	Restituisce l'oggetto sessione come oggetto di contesto di sola lettura.
validateDialogStack(IDialogState[], Library)	Assicura che tutte le voci di uno stack di dialoghi facciano riferimento a dialoghi validi all'interno di una gerarchia di libreria.
watch(string, boolean)	Abilita/disabilita un'espressione di controllo per la sessione corrente.
watchable(string, IWatchableHandler)	Aggiunge o recupera una variabile che può essere osservata.
watchableList()	Restituisce un elenco di variabili controllabili.
watchList()	Restituisce l'elenco corrente di variabili di controllo per la sessione.

Dettagli costruttore

Session(ISessionOptions)

Crea un'istanza della sessione.

new Session(options: ISessionOptions)

Parametri

options

ISessionOptions

Opzioni di configurazione delle sessioni.

Dettagli proprietà

connector

Connettore utilizzato per questa sessione.

connector: IConnector

Valore della proprietà

IConnector

conversationData

Dati di conversazione condivisi visibili a tutti i membri della conversazione.

conversationData: any

Valore della proprietà

any

dialogData

Dati visibili solo alla finestra di dialogo corrente.

dialogData: any

Valore della proprietà

any

library

Libreria radice dei bot di dialoghi.

library: Library

Valore della proprietà

Library

localizer

Localizzatore per la sessione corrente.

localizer: ILocalizer

Valore della proprietà

ILocalizer

message

Messaggio ricevuto dall'utente. Per i messaggi originati dal bot, questo può contenere solo i campi "to" & "from".

message: IMessage

Valore della proprietà

IMessage

privateConversationData

Dati di conversazione privati visibili solo all'utente.

privateConversationData: any

Valore della proprietà

any

sessionState

Sessioni informazioni sullo stato corrente.

sessionState: ISessionState

Valore della proprietà

ISessionState

userData

Dati per l'utente persistente in tutte le conversazioni con il bot.

userData: any

Valore della proprietà

any

Dettagli metodo

activeDialogStackEntry(IDialogState[])

Restituisce un dialogo attivo stack o null.

static function activeDialogStackEntry(stack: IDialogState[])

Parametri

stack

IDialogState[]

Stack di dialoghi per cui restituire la voce.

Restituisce

IDialogState

beginDialog<T>(string, T)

Passa il controllo della conversazione a un nuovo dialogo. Il dialogo corrente verrà sospeso fino al completamento del dialogo figlio. Al termine del dialogo corrente, l'elemento figlio riceverà una chiamata a dialogResumed() in cui può esaminare i risultati restituiti dall'elemento figlio.

function beginDialog<T>(id: string, args?: T)

Parametri

id

string

ID univoco della finestra di dialogo da avviare.

args

T

(Facoltativo) argomenti da passare ai dialoghi metodo begin().

Restituisce

Session

cancelDialog(string | number, string, any)

Annulla una finestra di dialogo esistente e, facoltativamente, ne avvia una nuova posizione. A differenza di endDialog() e replaceDialog() che influiscono sul dialogo corrente, questo metodo consente di terminare una finestra di dialogo padre in qualsiasi punto dello stack. L'elemento padre della finestra di dialogo annullata verrà continuato come se il dialogo avesse chiamato endDialog(). Verrà restituito uno speciale ResumeReason.canceled per indicare che la finestra di dialogo è stata annullata.

function cancelDialog(dialogId: string | number, replaceWithId?: string, replaceWithArgs?: any)

Parametri

dialogId

string | number

• dialogId:{string} - ID della finestra di dialogo da terminare. Se sono presenti più occorrenze del dialogo nello stack di dialoghi, l'ultima occorrenza verrà annullata.
• dialogId:{number} - Indice della finestra di dialogo nello stack da annullare. Si tratta del modo preferito per annullare una finestra di dialogo da un gestore azioni, in quanto garantisce che l'istanza corretta venga annullata.

replaceWithId

string

(Facoltativo) specifica un ID da avviare nella posizione delle finestre di dialogo annullate. In questo modo si impedisce la ripresa dei dialoghi padre.

replaceWithArgs

any

(Facoltativo) argomenti da passare alla nuova finestra di dialogo.

Restituisce

Session

clearDialogStack()

Cancella lo stack di dialoghi corrente.

function clearDialogStack()

Restituisce

Session

delay(number)

Inserisce un ritardo tra i messaggi in uscita.

function delay(delay: number)

Parametri

delay

number

Numero di millisecondi per cui sospendere.

Restituisce

Session

dialogStack(IDialogState[])

Ottiene/imposta lo stack di dialoghi corrente. Viene restituita una copia della finestra di dialogo corrente in modo che, se vengono apportate modifiche allo stack restituito, sarà necessario copiarla nuovamente nella sessione tramite una seconda chiamata a session.dialogStack().

function dialogStack(newStack?: IDialogState[])

Parametri

newStack

IDialogState[]

(Facoltativo) stack di dialoghi da assegnare alla sessione. Le sessioni dialogData verranno aggiornate in modo da riflettere lo stato del nuovo dialogo attivo.

Restituisce

IDialogState[]

dispatch(ISessionState, IMessage, Function)

Finalizza l'inizializzazione dell'oggetto sessione e quindi indirizza la sessione attraverso tutto il middleware installato. La funzione passata in next() verrà chiamata come ultimo passaggio della catena middleware.

function dispatch(sessionState: ISessionState, message: IMessage, next: Function)

Parametri

sessionState

ISessionState

Stato sessione corrente. Se null verrà avviata una nuova conversazione a partire dal dialogId configurato.

message

IMessage

Messaggio da instradare attraverso il middleware.

next

Function

Funzione da richiamare come ultimo passaggio della catena middleware.

Restituisce

Session

endConversation(TextOrMessageType, any[])

Termina la conversazione corrente e, facoltativamente, invia un messaggio all'utente.

function endConversation(message?: TextOrMessageType, args: any[])

Parametri

message

TextOrMessageType

(Facoltativo) testo/messaggio per inviare l'utente prima di terminare la conversazione.

args

any[]

(Facoltativo) argomenti utilizzati per formattare il testo di output finale quando messaggio è un {string|string[]}.

Restituisce

Session

endDialog(TextOrMessageType, any[])

Termina la finestra di dialogo corrente e, facoltativamente, invia un messaggio all'utente. L'elemento padre verrà ripreso con un IDialogResult.resumed motivo di completato.

function endDialog(message?: TextOrMessageType, args: any[])

Parametri

message

TextOrMessageType

(Facoltativo) testo/messaggio per inviare l'utente prima di terminare la finestra di dialogo.

args

any[]

(Facoltativo) argomenti utilizzati per formattare il testo di output finale quando messaggio è un {string|string[]}.

Restituisce

Session

endDialogWithResult(IDialogResult<any>)

Termina la finestra di dialogo corrente e, facoltativamente, restituisce un risultato all'elemento padre dei dialoghi.

function endDialogWithResult(result?: IDialogResult<any>)

Parametri

result

IDialogResult<any>

(Facoltativo) risultato per inviare l'utente. Il valore che si desidera restituire deve trovarsi nel campo risposta.

Restituisce

Session

error(Error)

Segnala che si è verificato un errore. Il bot segnalerà l'errore tramite un evento on('error', err).

function error(err: Error)

Parametri

err

Error

Errore che si è verificato.

Restituisce

Session

findDialogStackEntry(IDialogState[], string, boolean)

Cerca uno stack di dialoghi specifico, in direzione in avanti o inversa, restituendo il relativo indice.

static function findDialogStackEntry(stack: IDialogState[], dialogId: string, reverse?: boolean)

Parametri

stack

IDialogState[]

Stack di dialoghi da cercare.

dialogId

string

ID univoco della finestra di dialogo, in formato <namespace>:<dialog>, da cercare.

reverse

boolean

(Facoltativo) se true lo stack verrà cercato a partire dal dialogo attivo e funziona fino alla radice.

Restituisce

number

forEachDialogStackEntry(IDialogState[], boolean, (entry: IDialogState, index: number) => void)

Enumera tutte le voci di una finestra di dialogo in pila in una direzione in avanti o inversa.

static function forEachDialogStackEntry(stack: IDialogState[], reverse: boolean, fn: (entry: IDialogState, index: number) => void)

Parametri

stack

IDialogState[]

Stack di dialoghi da enumerare.

reverse

boolean

Se true, le voci verranno enumerate a partire dal dialogo attivo e verranno elaborate fino al dialogo radice.

fn

(entry: IDialogState, index: number) => void

Funzione da richiamare con ogni voce nello stack.

gettext(string, any[])

Carica una stringa localizzata per la lingua dei messaggi. Se gli argomenti vengono passati, la stringa localizzata verrà considerata come un modello e formattata usando sprintf-js (vedere la documentazione relativa ai dettagli).

function gettext(msgid: string, args: any[])

Parametri

msgid

string

Stringa da usare come chiave nella tabella di stringhe localizzata. In genere questa sarà solo la versione inglese della stringa.

args

any[]

(Facoltativo) argomenti utilizzati per formattare la stringa di output finale.

Restituisce

string

isReset()

Restituisce true se la sessione è stata reimpostata.

function isReset()

Restituisce

boolean

messageSent()

Restituisce true se per questa sessione è stato inviato un messaggio.

function messageSent()

Restituisce

boolean

ngettext(string, string, number)

Carica la forma plurale di una stringa localizzata per la lingua dei messaggi. La stringa di output verrà formattata per includere il conteggio sostituendo %d nella stringa con il conteggio.

function ngettext(msgid: string, msgid_plural: string, count: number)

Parametri

msgid

string

Forma singolare della stringa da usare come chiave nella tabella di stringhe localizzata. Usare %d per specificare dove deve andare il conteggio.

msgid_plural

string

Forma plurale della stringa da usare come chiave nella tabella di stringhe localizzata. Usare %d per specificare dove deve andare il conteggio.

count

number

Conteggio da utilizzare per determinare se deve essere utilizzata la forma singolare o plurale della stringa.

Restituisce

string

on(string, (data: any) => void)

Registra un listener di eventi.

function on(event: string, listener: (data: any) => void)

Parametri

event

string

Nome dell'evento. Tipi di evento:

• errore: Si è verificato un errore. Passa un oggetto Error JavaScript.

listener

(data: any) => void

Funzione da richiamare.

popDialogStackEntry(IDialogState[])

Rimuove il dialogo attivo da uno stack e restituisce quello nuovo se lo stack non è vuoto.

static function popDialogStackEntry(stack: IDialogState[])

Parametri

stack

IDialogState[]

Stack di dialoghi da aggiornare.

Restituisce

IDialogState

preferredLocale(string, (err: Error) => void)

Restituisce le impostazioni locali preferite quando non viene specificato alcun parametro. In caso contrario, imposta le impostazioni locali preferite.

function preferredLocale(locale?: string, callback?: (err: Error) => void)

Parametri

locale

string

(Facoltativo) Impostazioni locali da usare per la localizzazione dei messaggi.

callback

(err: Error) => void

(Facoltativo) funzione chiamata quando la tabella di localizzazione è stata caricata per le impostazioni locali fornite.

Restituisce

string

pruneDialogStack(IDialogState[], number)

Elimina tutte le voci dello stack di dialoghi che iniziano con l'indice specificato e restituisce il nuovo dialogo attivo.

static function pruneDialogStack(stack: IDialogState[], start: number)

Parametri

stack

IDialogState[]

Stack di dialoghi da aggiornare.

start

number

Indice del primo elemento da rimuovere.

Restituisce

IDialogState

pushDialogStackEntry(IDialogState[], IDialogState)

Inserisce un nuovo dialogo in uno stack e lo restituisce come finestra di dialogo attiva.

static function pushDialogStackEntry(stack: IDialogState[], entry: IDialogState)

Parametri

stack

IDialogState[]

Stack di dialoghi da aggiornare.

entry

IDialogState

Voce della finestra di dialogo da inserire nello stack.

Restituisce

IDialogState

replaceDialog<T>(string, T)

Termina il dialogo corrente e ne avvia uno nuovo. La finestra di dialogo padre non verrà ripresa fino al completamento del nuovo dialogo.

function replaceDialog<T>(id: string, args?: T)

Parametri

id

string

ID univoco della finestra di dialogo da avviare.

args

T

(Facoltativo) argomenti da passare ai dialoghi metodo begin().

Restituisce

Session

reset(string, any)

Cancella lo stack di chiamate delle sessioni e riavvia la conversazione con il dialogId configurato.

function reset(dialogId?: string, dialogArgs?: any)

Parametri

dialogId

string

(Facoltativo) ID della finestra di dialogo da avviare.

dialogArgs

any

(Facoltativo) argomenti da passare ai dialoghi metodo begin().

Restituisce

Session

routeToActiveDialog(IRecognizeResult)

Invia la sessione alla finestra di dialogo attiva o alla finestra di dialogo predefinita per l'elaborazione.

function routeToActiveDialog(recognizeResult?: IRecognizeResult)

Parametri

recognizeResult

IRecognizeResult

(Facoltativo) risultati restituiti dalla chiamata Library.findRoutes(), Library.findActiveDialogRoutes(), * o Dialog.recognize().

save()

Attiva il salvataggio delle modifiche apportate alla finestra di dialogo Data, userData, conversationdatao [privateConversationData'(#privateconversationdata).

function save()

Restituisce

Session

say(TextType, IMessageOptions)

function say(text: TextType, options?: IMessageOptions)

Parametri

text

TextType

options

IMessageOptions

Restituisce

Session

say(TextType, TextType, IMessageOptions)

Invia un testo e un messaggio SSML facoltativo all'utente.

function say(text: TextType, speak?: TextType, options?: IMessageOptions)

Parametri

text

TextType

Testo da inviare all'utente. Può essere Null per inviare solo SSML o allegati.

speak

TextType

(Facoltativo) messaggio che deve essere pronunciato all'utente. Il messaggio deve essere formattato come Speech Synthesis Markup Language (SSML). Se viene passata una matrice, verrà scelta una risposta in modo casuale.

options

IMessageOptions

(Facoltativo) proprietà che devono essere incluse nel messaggio in uscita.

Restituisce

Session

sayLocalized(string, TextType, TextType, IMessageOptions)

Invia un testo e un messaggio SSML facoltativo all'utente usando uno spazio dei nomi di localizzazione specifico.

function sayLocalized(libraryNamespace: string, text: TextType, speak?: TextType, options?: IMessageOptions)

Parametri

libraryNamespace

string

Namespace da usare per la localizzazione del messaggio.

text

TextType

Testo da inviare all'utente. Può essere Null per inviare solo SSML o allegati.

speak

TextType

(Facoltativo) messaggio che deve essere pronunciato all'utente. Il messaggio deve essere formattato come Speech Synthesis Markup Language (SSML). Se viene passata una matrice, verrà scelta una risposta in modo casuale.

options

IMessageOptions

(Facoltativo) proprietà che devono essere incluse nel messaggio in uscita.

Restituisce

Session

send(TextOrMessageType, any[])

Invia un messaggio all'utente.

function send(message: TextOrMessageType, args: any[])

Parametri

message

TextOrMessageType

Testo/messaggio da inviare all'utente. Se viene passata una matrice, verrà scelta una risposta in modo casuale.

args

any[]

(Facoltativo) argomenti utilizzati per formattare il testo di output finale quando messaggio è un {string|string[]}.

Restituisce

Session

sendBatch((err: Error, addresses?: IAddress[]) => void)

Termina immediatamente il batch corrente e recapita tutti i messaggi in coda.

function sendBatch(done?: (err: Error, addresses?: IAddress[]) => void)

Parametri

done

(err: Error, addresses?: IAddress[]) => void

(Facoltativo) funzione chiamata quando il batch è stato eliminato correttamente o non riuscito per qualche motivo.

sendLocalized(string, TextOrMessageType, any[])

Invia un messaggio a un utente usando uno spazio dei nomi di localizzazione specifico.

function sendLocalized(libraryNamespace: string, message: TextOrMessageType, args: any[])

Parametri

libraryNamespace

string

Namespace da usare per la localizzazione del messaggio.

message

TextOrMessageType

Testo/messaggio da inviare all'utente.

args

any[]

(Facoltativo) argomenti utilizzati per formattare il testo di output finale quando messaggio è un {string|string[]}.

Restituisce

Session

sendTyping()

Invia all'utente un'indicazione che il bot sta digitando. Per le operazioni a esecuzione prolungata, questa operazione deve essere chiamata ogni pochi secondi.

function sendTyping()

Restituisce

Session

toRecognizeContext()

Restituisce l'oggetto sessione come oggetto di contesto di sola lettura.

function toRecognizeContext()

Restituisce

IRecognizeContext

validateDialogStack(IDialogState[], Library)

Assicura che tutte le voci di uno stack di dialoghi facciano riferimento a dialoghi validi all'interno di una gerarchia di libreria.

static function validateDialogStack(stack: IDialogState[], root: Library)

Parametri

stack

IDialogState[]

Stack di dialoghi da convalidare.

root

Library

Radice della gerarchia di libreria, in genere il bot.

Restituisce

boolean

watch(string, boolean)

Abilita/disabilita un'espressione di controllo per la sessione corrente.

function watch(variable: string, enable?: boolean)

Parametri

variable

string

Nome della variabile da controllare/annullare il controllo.

enable

boolean

(Facoltativo) Se true la variabile verrà osservata, in caso contrario non verrà osservata. Il valore predefinito è true.

Restituisce

Session

watchable(string, IWatchableHandler)

Aggiunge o recupera una variabile che può essere osservata.

static function watchable(variable: string, handler?: IWatchableHandler)

Parametri

variable

string

Nome della variabile che può essere osservata. La distinzione tra maiuscole e minuscole viene utilizzata solo per la visualizzazione.

handler

IWatchableHandler

(Facoltativo) Funzione utilizzata per recuperare il valore corrente delle variabili. Se viene specificato un nuovo gestore verrà registrato, altrimenti verrà recuperato il gestore esistente.

Restituisce

IWatchableHandler

watchableList()

Restituisce un elenco di variabili controllabili.

static function watchableList()

Restituisce

string[]

watchList()

Restituisce l'elenco corrente di variabili di controllo per la sessione.

function watchList()

Restituisce

string[]