Library class

Pacchetto:

botbuilder

Libreria di dialoghi correlati utilizzati a scopo di routing. Le librerie possono essere concatenate per consentire lo sviluppo di bot complessi. La classe UniversalBot è una libreria che costituisce la radice di questa catena. Le librerie di parti riutilizzabili possono essere sviluppate creando una nuova istanza della libreria e aggiungendo finestre di dialogo esattamente come si farebbe con un bot. La libreria deve avere un nome univoco che corrisponde al sito Web delle librerie o al nome del modulo NPM. I bot possono quindi riutilizzare la libreria semplicemente aggiungendo l'istanza della libreria di parti al bot usando UniversalBot.library(). Se la libreria stessa dipende da altre librerie, è necessario aggiungerle alla libreria come dipendenza usando Library.library(). È possibile gestire facilmente più versioni della libreria aggiungendo un numero di versione al nome della libreria.

Per richiamare i dialoghi all'interno dei bot della libreria, sarà necessario chiamare session.beginDialog() con un ID di dialogo completo sotto forma di ':'. In genere, lo sviluppatore verrà nascosto esponendo una funzione dal modulo che avvia la finestra di dialogo per loro. Quindi chiamare qualcosa come myLib.someDialog(session, { arg: '' }); finirebbe per chiamare session.beginDialog('myLib:someDialog', args); sotto le quinte.

Vale la pena notare che i dialoghi vengono sempre richiamati all'interno del dialogo corrente, quindi una volta che all'interno di una finestra di dialogo dalla libreria non è necessario anteporre ogni beginDialog() chiamare con il nome delle librerie. È solo quando si passa da un contesto di libreria a un altro che è necessario includere il prefisso del nome della libreria.

Costruttori

Library(string)

Crea una nuova istanza della libreria.

Proprietà

name	Spazio dei nomi univoco delle librerie. Viene usato per risolvere le finestre di dialogo delle librerie e le richieste localizzate.
RouteTypes	Valori routeType supportati restituiti per impostazione predefinita da findRoutes().

Metodi

addRouteResult(IRouteResult, IRouteResult[])	Metodo helper chiamato dai vari metodi di ricerca di route per gestire l'aggiunta di una route candidata al set di risultati. Se il punteggio è maggiore, la corrispondenza migliore corrente nel set verrà restituito un nuovo set di risultati contenente solo la nuova corrispondenza. Se il punteggio è uguale alla corrispondenza migliore corrente, verrà aggiunto al set esistente. Se il punteggio è minore della corrispondenza migliore corrente, verrà ignorato.
beginDialogAction(string, string, IDialogActionOptions)	Registra un'azione globale che avvierà un'altra finestra di dialogo ogni volta che viene attivata. Il nuovo dialogo verrà inserito nello stack in modo da non terminare automaticamente alcuna attività corrente. L'attività corrente verrà continuata al termine della nuova finestra di dialogo. Le richieste predefinite richiederanno automaticamente all'utente una volta che ciò si verifica, ma tale comportamento può essere disabilitato impostando il flag promptAfterAction quando si chiama un prompt predefinito.
bestRouteResult(IRouteResult[], IDialogState[], string)	Trova la route migliore da usare all'interno di un set di risultati contenente più route ambigue. Verrà usata la strategia di ambiguità seguente: : i tipi di route personalizzati sono la priorità più alta e saranno preferiti. Ciò consente allo sviluppatore di eseguire l'override del routing all'interno di un bot in modo molto potente. ActiveDialog: la finestra di dialogo attiva è la priorità più alta successiva. StackAction: le azioni stack sono la priorità più alta successiva e l'azione con la posizione dello stack più profonda verrà restituita. GlobalAction: le azioni globali sono la priorità più bassa. Se un dialogStack è passato nelle azioni della libreria più a fondo nello stack, verrà favorito. In caso contrario, verrà restituito il primo.
clone(Library, string)	Restituisce un clone di una libreria esistente.
customAction(IDialogActionOptions)	Registra un'azione globale personalizzata che chiamerà l'oggetto passato onSelectAction gestore quando viene attivato.
dialog(string, Dialog | IDialogWaterfallStep[] | IDialogWaterfallStep, boolean)	Registra o restituisce una finestra di dialogo dalla libreria.
endConversationAction(string, TextOrMessageType, ICancelActionOptions)	Registra un'azione globale che terminerà la conversazione con l'utente quando viene attivata.
findActiveDialogRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void, IDialogState[])	Ottiene l'attendibilità dei dialoghi attivi che riconosce il messaggio corrente. Il dialogo deve essere un membro della libreria corrente. In caso contrario, verrà restituito un punteggio pari a 0,0.
findDialog(string, string)	Cerca nella libreria e in tutte le relative dipendenze una finestra di dialogo specifica. Restituisce la finestra di dialogo se trovata; in caso contrario, null.
findGlobalActionRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void)	Cerca nella libreria per verificare se sono state attivate azioni globali.
findRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void)	Cerca le route candidate per gestire il messaggio corrente. Per avviare effettivamente la gestione del messaggio, è necessario chiamare selectRoute() con uno dei risultati restituiti. È possibile eseguire l'override della logica di ricerca predefinita usando onFindRoute() e viene eseguita solo la ricerca della libreria corrente in modo da chiamare findRoutes() seperately per ogni libreria all'interno della gerarchia.
findStackActionRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void, IDialogState[])	Cerca nello stack di finestre di dialogo delle sessioni per verificare se sono state attivate azioni.
forEachDialog((dialog: Dialog, id: string) => void)	Enumera tutte le finestre di dialogo delle librerie.
forEachLibrary((library: Library) => void)	Enumera tutte le librerie figlio delle librerie. Il chiamante deve eseguire i passaggi appropriati per evitare riferimenti circolari durante l'enumerazione della gerarchia. Nella maggior parte dei casi la chiamata di libraryList() è una scelta migliore perché contiene già la logica per evitare cicli.
library(Library | string)	Registra o restituisce una dipendenza di libreria.
libraryList(boolean)	Restituisce un elenco di librerie univoche all'interno della gerarchia. Deve essere chiamato nella radice della gerarchia di libreria ed evita i cicli creati quando due librerie figlio fanno riferimento alla stessa libreria dipendente.
localePath(string)	Ottiene o imposta il percorso della cartella "/locale/" delle librerie contenente le richieste localizzate. I prompt per la libreria devono essere archiviati in un file "/locale/<IETF_TAG>/.json" in questo percorso dove "<IETF_TAG>" rappresenta il tag di lingua di 2-3 cifre per le impostazioni locali e "" è un nome file corrispondente allo spazio dei nomi delle librerie.
onFindRoutes(IFindRoutesHandler)	Sostituisce findRoutes() logica di ricerca di route predefinita con un'implementazione personalizzata.
onSelectRoute(ISelectRouteHandler)	Sostituisce la logica predefinita per selectRoute() con un'implementazione personalizzata.
recognize(IRecognizeContext, (err: Error, result: IIntentRecognizerResult) => void)	Tenta di associare un'espressione di testo di un utente a una finalità usando i riconoscitori delle librerie. Per informazioni dettagliate, vedere IIntentRecognizer.recognize().
recognizer(IIntentRecognizer)	Aggiunge un nuovo plug-in di riconoscimento alla libreria.
selectActiveDialogRoute(Session, IRouteResult, IDialogState[])	Indirizza il messaggio corrente alla finestra di dialogo attiva.
selectGlobalActionRoute(Session, IRouteResult, IDialogState[])	Indirizza il messaggio corrente a un'azione globale attivata.
selectRoute(Session, IRouteResult)	Attiva la gestione del messaggio corrente usando la route selezionata. È possibile eseguire l'override della logica predefinita usando onSelectRoute().
selectStackActionRoute(Session, IRouteResult, IDialogState[])	Indirizza il messaggio corrente a un'azione dello stack attivata.

Dettagli costruttore

Library(string)

Crea una nuova istanza della libreria.

new Library(name: string)

Parametri

name

string

Spazio dei nomi univoco per la libreria.

Dettagli proprietà

name

Spazio dei nomi univoco delle librerie. Viene usato per risolvere le finestre di dialogo delle librerie e le richieste localizzate.

name: string

Valore della proprietà

string

RouteTypes

Valori routeType supportati restituiti per impostazione predefinita da findRoutes().

static RouteTypes: Object

Valore della proprietà

Object

Dettagli metodo

addRouteResult(IRouteResult, IRouteResult[])

Metodo helper chiamato dai vari metodi di ricerca di route per gestire l'aggiunta di una route candidata al set di risultati.

• Se il punteggio è maggiore, la corrispondenza migliore corrente nel set verrà restituito un nuovo set di risultati contenente solo la nuova corrispondenza.
• Se il punteggio è uguale alla corrispondenza migliore corrente, verrà aggiunto al set esistente.
• Se il punteggio è minore della corrispondenza migliore corrente, verrà ignorato.

static function addRouteResult(route: IRouteResult, current?: IRouteResult[])

Parametri

route

IRouteResult

Route candidata da aggiungere al set.

current

IRouteResult[]

(Facoltativo) set di risultati per aggiungere anche la route. Se manca, verrà restituito un nuovo set con solo la route.

Restituisce

IRouteResult[]

beginDialogAction(string, string, IDialogActionOptions)

Registra un'azione globale che avvierà un'altra finestra di dialogo ogni volta che viene attivata. Il nuovo dialogo verrà inserito nello stack in modo da non terminare automaticamente alcuna attività corrente. L'attività corrente verrà continuata al termine della nuova finestra di dialogo. Le richieste predefinite richiederanno automaticamente all'utente una volta che ciò si verifica, ma tale comportamento può essere disabilitato impostando il flag promptAfterAction quando si chiama un prompt predefinito.

function beginDialogAction(name: string, id: string, options?: IDialogActionOptions)

Parametri

name

string

Nome univoco per assegnare l'azione.

id

string

ID della finestra di dialogo da avviare.

options

IDialogActionOptions

(Facoltativo) opzioni usate per configurare l'azione. Se corrisponde viene specificata, l'azione ascolterà l'utente di pronunciare una parola o una frase che attiva l'azione. In caso contrario, l'azione deve essere associata a un pulsante usando CardAction.dialogAction() per attivare l'azione. È anche possibile usare dialogArgs per passare parametri aggiuntivi alla finestra di dialogo avviata.

Restituisce

Dialog

bestRouteResult(IRouteResult[], IDialogState[], string)

Trova la route migliore da usare all'interno di un set di risultati contenente più route ambigue. Verrà usata la strategia di ambiguità seguente:

1. : i tipi di route personalizzati sono la priorità più alta e saranno preferiti. Ciò consente allo sviluppatore di eseguire l'override del routing all'interno di un bot in modo molto potente.
2. ActiveDialog: la finestra di dialogo attiva è la priorità più alta successiva.
3. StackAction: le azioni stack sono la priorità più alta successiva e l'azione con la posizione dello stack più profonda verrà restituita.
4. GlobalAction: le azioni globali sono la priorità più bassa. Se un dialogStack è passato nelle azioni della libreria più a fondo nello stack, verrà favorito. In caso contrario, verrà restituito il primo.

static function bestRouteResult(routes: IRouteResult[], dialogStack?: IDialogState[], rootLibraryName?: string)

Parametri

routes

IRouteResult[]

Matrice di route candidate da filtrare.

dialogStack

IDialogState[]

(Facoltativo) stack di dialoghi usato per determinare quali librerie sono azioni globali da favorire.

rootLibraryName

string

(Facoltativo) Spazio dei nomi della libreria da preferire quando si disambiguano le azioni globali e non sono presenti dialoghi nello stack.

Restituisce

IRouteResult

clone(Library, string)

Restituisce un clone di una libreria esistente.

function clone(copyTo?: Library, newName?: string)

Parametri

copyTo

Library

(Facoltativo) Istanza in cui copiare l'oggetto corrente. Se manca una nuova istanza verrà creata.

newName

string

(Facoltativo) se specificata la copia restituita verrà rinominata in un nuovo nome.

Restituisce

Library

customAction(IDialogActionOptions)

Registra un'azione globale personalizzata che chiamerà l'oggetto passato onSelectAction gestore quando viene attivato.

function customAction(options: IDialogActionOptions)

Parametri

options

IDialogActionOptions

Opzioni utilizzate per configurare l'azione. Se corrisponde viene specificata l'azione ascolterà l'utente per pronunciare una parola o una frase che attiva l'azione. È possibile fornire logica di corrispondenza personalizzata usando onFindAction.

Restituisce

Library

dialog(string, Dialog | IDialogWaterfallStep[] | IDialogWaterfallStep, boolean)

Registra o restituisce una finestra di dialogo dalla libreria.

function dialog(id: string, dialog?: Dialog | IDialogWaterfallStep[] | IDialogWaterfallStep, replace?: boolean)

Parametri

id

string

ID univoco del dialogo in fase di regsitering o recupero.

dialog

Dialog | IDialogWaterfallStep[] | IDialogWaterfallStep

(Facoltativo) finestra di dialogo o cascata da registrare.

• finestra di dialogo:{Dialog} - Finestra di dialogo da aggiungere.
• finestra di dialogo:{IDialogWaterfallStep[]} - Cascata di passaggi da eseguire. Per informazioni dettagliate, vedere IDialogWaterfallStep.
• finestra di dialogo:{IDialogWaterfallStep} - Cascata a passaggio singolo. La chiamata di un prompt predefinito o l'avvio di un nuovo dialogo comporterà la fine della finestra di dialogo corrente al termine della richiesta/finestra di dialogo figlio.

replace

boolean

(Facoltativo) se true, la finestra di dialogo deve sostituire la finestra di dialogo esistente se già registrata.

Restituisce

Dialog

endConversationAction(string, TextOrMessageType, ICancelActionOptions)

Registra un'azione globale che terminerà la conversazione con l'utente quando viene attivata.

function endConversationAction(name: string, msg?: TextOrMessageType, options?: ICancelActionOptions)

Parametri

name

string

Nome univoco per assegnare l'azione.

msg

TextOrMessageType

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

options

ICancelActionOptions

(Facoltativo) opzioni usate per configurare l'azione. Se corrisponde viene specificata, l'azione ascolterà l'utente di pronunciare una parola o una frase che attiva l'azione. In caso contrario, l'azione deve essere associata a un pulsante usando CardAction.dialogAction() per attivare l'azione.

Restituisce

Dialog

findActiveDialogRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void, IDialogState[])

Ottiene l'attendibilità dei dialoghi attivi che riconosce il messaggio corrente. Il dialogo deve essere un membro della libreria corrente. In caso contrario, verrà restituito un punteggio pari a 0,0.

function findActiveDialogRoutes(context: IRecognizeContext, callback: (err: Error, routes: IRouteResult[]) => void, dialogStack?: IDialogState[])

Parametri

context

IRecognizeContext

Contesto di riconoscimento di sola lettura per la conversazione corrente.

callback

(err: Error, routes: IRouteResult[]) => void

Funzione che deve essere richiamata con le route trovate.

dialogStack

IDialogState[]

(Facoltativo) stack di dialoghi da cercare. Il comportamento predefinito consiste nel cercare nello stack di dialoghi corrente delle sessioni.

findDialog(string, string)

Cerca nella libreria e in tutte le relative dipendenze una finestra di dialogo specifica. Restituisce la finestra di dialogo se trovata; in caso contrario, null.

function findDialog(libName: string, dialogId: string)

Parametri

libName

string

Nome della libreria contenente la finestra di dialogo.

dialogId

string

ID univoco della finestra di dialogo all'interno della libreria.

Restituisce

Dialog

findGlobalActionRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void)

Cerca nella libreria per verificare se sono state attivate azioni globali.

function findGlobalActionRoutes(context: IRecognizeContext, callback: (err: Error, routes: IRouteResult[]) => void)

Parametri

context

IRecognizeContext

Contesto di riconoscimento di sola lettura per la conversazione corrente.

callback

(err: Error, routes: IRouteResult[]) => void

Funzione che deve essere richiamata con le route trovate.

findRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void)

Cerca le route candidate per gestire il messaggio corrente. Per avviare effettivamente la gestione del messaggio, è necessario chiamare selectRoute() con uno dei risultati restituiti. È possibile eseguire l'override della logica di ricerca predefinita usando onFindRoute() e viene eseguita solo la ricerca della libreria corrente in modo da chiamare findRoutes() seperately per ogni libreria all'interno della gerarchia.

function findRoutes(context: IRecognizeContext, callback: (err: Error, routes: IRouteResult[]) => void)

Parametri

context

IRecognizeContext

Contesto di riconoscimento di sola lettura per la conversazione corrente.

callback

(err: Error, routes: IRouteResult[]) => void

Funzione che deve essere richiamata con le route trovate.

findStackActionRoutes(IRecognizeContext, (err: Error, routes: IRouteResult[]) => void, IDialogState[])

Cerca nello stack di finestre di dialogo delle sessioni per verificare se sono state attivate azioni.

function findStackActionRoutes(context: IRecognizeContext, callback: (err: Error, routes: IRouteResult[]) => void, dialogStack?: IDialogState[])

Parametri

context

IRecognizeContext

Contesto di riconoscimento di sola lettura per la conversazione corrente.

callback

(err: Error, routes: IRouteResult[]) => void

Funzione che deve essere richiamata con le route trovate.

dialogStack

IDialogState[]

(Facoltativo) stack di dialoghi da cercare. Il comportamento predefinito consiste nel cercare nello stack di dialoghi corrente delle sessioni.

forEachDialog((dialog: Dialog, id: string) => void)

Enumera tutte le finestre di dialogo delle librerie.

function forEachDialog(callback: (dialog: Dialog, id: string) => void)

Parametri

callback

(dialog: Dialog, id: string) => void

Funzione iteratore da chiamare con ogni dialogo.

forEachLibrary((library: Library) => void)

Enumera tutte le librerie figlio delle librerie. Il chiamante deve eseguire i passaggi appropriati per evitare riferimenti circolari durante l'enumerazione della gerarchia. Nella maggior parte dei casi la chiamata di libraryList() è una scelta migliore perché contiene già la logica per evitare cicli.

function forEachLibrary(callback: (library: Library) => void)

Parametri

callback

(library: Library) => void

Funzione iteratore da chiamare con ogni bilancia figlio.

library(Library | string)

Registra o restituisce una dipendenza di libreria.

function library(lib: Library | string)

Parametri

lib

Library | string

• lib:{Library} - Libreria da registrare come dipendenza.
• lib:{string} - Nome univoco della libreria da cercare. Verranno cercate anche tutte le dipendenze.

Restituisce

Library

libraryList(boolean)

Restituisce un elenco di librerie univoche all'interno della gerarchia. Deve essere chiamato nella radice della gerarchia di libreria ed evita i cicli creati quando due librerie figlio fanno riferimento alla stessa libreria dipendente.

function libraryList(reverse?: boolean)

Parametri

reverse

boolean

(Facoltativo) Se l'elenco true verrà generato dalle foglie, significa che la libreria radice verrà elencata per ultima. Il valore predefinito è false, il che significa che verrà generato dalle radici verso il basso e la libreria radice verrà elencata per prima.

Restituisce

Library[]

localePath(string)

Ottiene o imposta il percorso della cartella "/locale/" delle librerie contenente le richieste localizzate. I prompt per la libreria devono essere archiviati in un file "/locale/<IETF_TAG>/.json" in questo percorso dove "<IETF_TAG>" rappresenta il tag di lingua di 2-3 cifre per le impostazioni locali e "" è un nome file corrispondente allo spazio dei nomi delle librerie.

function localePath(path?: string)

Parametri

path

string

(Facoltativo) percorso della cartella "/locale/" delle librerie. Se specificato, il percorso delle librerie verrà aggiornato.

Restituisce

string

onFindRoutes(IFindRoutesHandler)

Sostituisce findRoutes() logica di ricerca di route predefinita con un'implementazione personalizzata.

function onFindRoutes(handler: IFindRoutesHandler)

Parametri

handler

IFindRoutesHandler

Funzione che verrà richiamata ogni volta che viene chiamato findRoutes() per la libreria.

onSelectRoute(ISelectRouteHandler)

Sostituisce la logica predefinita per selectRoute() con un'implementazione personalizzata.

function onSelectRoute(handler: ISelectRouteHandler)

Parametri

handler

ISelectRouteHandler

Funzione che verrà richiamata ogni volta che viene chiamato selectRoute().

recognize(IRecognizeContext, (err: Error, result: IIntentRecognizerResult) => void)

Tenta di associare un'espressione di testo di un utente a una finalità usando i riconoscitori delle librerie. Per informazioni dettagliate, vedere IIntentRecognizer.recognize().

function recognize(context: IRecognizeContext, callback: (err: Error, result: IIntentRecognizerResult) => void)

Parametri

context

IRecognizeContext

Contesto di riconoscimento di sola lettura per la conversazione corrente.

callback

(err: Error, result: IIntentRecognizerResult) => void

Funzione che deve essere richiamata al completamento del riconoscimento.

recognizer(IIntentRecognizer)

Aggiunge un nuovo plug-in di riconoscimento alla libreria.

function recognizer(plugin: IIntentRecognizer)

Parametri

plugin

IIntentRecognizer

Riconoscitore da aggiungere.

Restituisce

IntentDialog

selectActiveDialogRoute(Session, IRouteResult, IDialogState[])

Indirizza il messaggio corrente alla finestra di dialogo attiva.

function selectActiveDialogRoute(session: Session, route: IRouteResult, newStack?: IDialogState[])

Parametri

session

Session

Oggetto sessione per la conversazione corrente.

route

IRouteResult

Risultato della route restituito da una chiamata precedente a findRoutes() o findActiveDialogRoutes().

newStack

IDialogState[]

selectGlobalActionRoute(Session, IRouteResult, IDialogState[])

Indirizza il messaggio corrente a un'azione globale attivata.

function selectGlobalActionRoute(session: Session, route: IRouteResult, newStack?: IDialogState[])

Parametri

session

Session

Oggetto sessione per la conversazione corrente.

route

IRouteResult

Risultato della route restituito da una chiamata precedente a findRoutes() o findGlobalActionRoutes().

newStack

IDialogState[]

selectRoute(Session, IRouteResult)

Attiva la gestione del messaggio corrente usando la route selezionata. È possibile eseguire l'override della logica predefinita usando onSelectRoute().

function selectRoute(session: Session, route: IRouteResult)

Parametri

session

Session

Oggetto sessione per la conversazione corrente.

route

IRouteResult

Risultato della route restituito da una chiamata precedente a findRoutes().

selectStackActionRoute(Session, IRouteResult, IDialogState[])

Indirizza il messaggio corrente a un'azione dello stack attivata.

function selectStackActionRoute(session: Session, route: IRouteResult, newStack?: IDialogState[])

Parametri

session

Session

Oggetto sessione per la conversazione corrente.

route

IRouteResult

Risultato della route restituito da una chiamata precedente a findRoutes() o findStackActionRoutes().

newStack

IDialogState[]