Non esiste un campo per fornire descrizioni per i componenti personalizzati che spiegano cosa fanno e quali informazioni devono essere trasmesse loro. Quindi i modi migliori per aiutare gli sviluppatori di abilità con l'uso del componente sono utilizzare buoni nomi per i parametri di componente e input e scegliere attentamente le stringhe di azione restituite dal componente.

• I componenti YAML integrati utilizzano System.<name> come nome. Pertanto, soprattutto per i flussi di dialogo basati su YAML, è possibile utilizzare Custom.<name> per consentire ai revisori degli skill di comprendere che si tratta di un componente personalizzato a cui fa riferimento il flusso della finestra di dialogo. In alternativa, è possibile utilizzare uno spazio dei nomi per fornire il contesto. Per i nostri componenti personalizzati di esempio utilizziamo spesso oracle.sample.<name> per indicare che tali componenti non sono destinati alla qualità di produzione.

• I parametri di input forniscono dati al componente personalizzato da elaborare. Spesso i dati passati a un componente personalizzato non sono il valore effettivo da utilizzare, ma piuttosto il nome di una variabile che contiene i valori dei dati da elaborare o in cui devono essere scritti i dati sottoposti a query da un servizio remoto. Esaminando i componenti incorporati, utilizzano variable come nome della proprietà per contenere il nome della variabile in cui verrà scritto il risultato del componente oppure <name>Var (ad esempio nlpResultVar) per indicare le proprietà che fanno riferimento a un nome di riferimento di variabile. È possibile migliorare ulteriormente questo aspetto utilizzando i prefissi _in e _out per indicare se una variabile fa riferimento a una variabile che contiene dati o prevede dati dal componente.

• Le stringhe di azione sono facoltative e possono essere utilizzate dallo sviluppatore delle competenze per determinare lo stato successivo del flusso della finestra di dialogo a cui passare. L'uso di success o failure come stringa di azione non fornisce molto contesto, pertanto si consiglia di utilizzare qualcosa come orderSubmitted, orderRejected o userUnauthorized.

La realtà è che spesso lo sviluppatore di un componente personalizzato è anche lo sviluppatore di abilità che lo utilizza. Per questo motivo, molti sviluppatori semplificano il loro lavoro con componenti personalizzati facendo ipotesi sulle variabili che sono presenti nell'abilità. Quindi, invece di passare il nome di una variabile al componente, si riferiscono direttamente al nome nella logica del componente personalizzato. Si sconsiglia questo perché tali ipotesi possono facilmente rompere un componente personalizzato. Si consiglia di definire un contratto chiaro e completo tra il componente personalizzato e le competenze che lo utilizzano.

Una domanda comune riguarda il numero di componenti personalizzati da aggiungere a un pacchetto di servizi componente personalizzato. In generale è sempre una buona idea pensare ai servizi di componenti personalizzati e ai componenti che contiene, come librerie. Pertanto, tutti i componenti correlati a un'attività potrebbero essere salvati in un singolo servizio di componenti personalizzati. Tuttavia, le raccomandazioni devono essere in grado di affrontare la realtà. Pertanto, la domanda su come imballare i componenti personalizzati deve essere risolta in base all'uso previsto dei componenti personalizzati.

• Riutilizzo non è un'opzione per molti sviluppatori di componenti personalizzati. Quando i componenti personalizzati vengono sviluppati e utilizzati in una competenza specifica, è opportuno raggrupparli in un'unica distribuzione di servizi di componenti personalizzati. L'eccezione a questo è per i componenti che vengono effettivamente riutilizzati in altre competenze.

• Le Distribuzioni di container di componenti incorporati sono limitate dal numero di servizi di componenti personalizzati per ogni istanza di Oracle Digital Assistant. Pertanto, dovrai utilizzare un singolo servizio di componenti personalizzati per competenza o cercare una distribuzione remota dei componenti personalizzati.

• Utilizza la distribuzione remota di servizi di componenti personalizzati a Kubernetes in Oracle Cloud Infrastructure, per i seguenti motivi:

  • Per non divulgare informazioni riservate contenute nel codice del componente personalizzato. I servizi di componenti personalizzati distribuiti nel contenitore incorporato possono essere scaricati da chiunque disponga dell'accesso completo all'istanza di Oracle Digital Assistant.

  • Per implementare una migliore segmentazione del codice. I componenti personalizzati devono contenere solo codice necessario per interagire con il bot e per richiamare i servizi REST. Tutti gli altri codici devono essere memorizzati in file JavaScript esterni (se si utilizza un contenitore incorporato) o in livelli di integrazione (servizi REST). I componenti personalizzati includono codice che effettua le operazioni riportate di seguito.

    • leggi parametri di input

    • leggi/imposta valori variabili

    • gestire i messaggi ricevuti da un componente

    • visualizza l'interfaccia utente del componente personalizzato

    • determinare la transizione a uno stato successivo

    • gestire lo stato del componente

    • accedere ai servizi REST

  • Migliorare le prestazioni. Il contenitore incorporato per la distribuzione di componenti personalizzati alle competenze utilizza le funzioni OCI, che hanno un ritardo di avvio a freddo. Per evitare questo ritardo, così come il limite del numero di servizi che possono essere distribuiti, una distribuzione remota di componenti personalizzati fornisce un'alternativa senza preoccupazioni.

  • Condividere componenti comuni. Anche se la nostra esperienza è che il riutilizzo non è altamente classificato tra gli sviluppatori di componenti personalizzati, ha senso creare e distribuire componenti personalizzati comunemente utilizzati su un server remoto. Potresti avere componenti comuni per cose come la gestione degli errori e l'escalation, la gestione delle autorizzazioni OAuth2 a 2 fasi e altro ancora.

Il logger predefinito implementato per i componenti personalizzati è il logger della console. È possibile accedere al logger tramite una chiamata a context.logger(). È possibile utilizzare le funzioni di registrazione delle chiamate disponibili per il logger della console come ".info('…') o ".warn('…')".

Nota: l'uso di context.logger() è particolarmente appropriato quando si esegue la distribuzione nel contenitore incorporato, poiché il contenitore incorporato è in grado di visualizzare correttamente questi log. Per i componenti personalizzati distribuiti esternamente, è preferibile utilizzare una libreria di log diversa, ad esempio log4js.

I componenti di flusso della finestra di dialogo personalizzati possono avere un'interazione più lunga con un utente prima che la navigazione passi a uno stato di flusso della finestra di dialogo successivo. Per questa interazione è necessario assicurarsi che il componente gestisca il suo stato interno in modo che possa distinguere tra una chiamata iniziale e le chiamate successive. Sono disponibili due opzioni per eseguire questa operazione:

• Aggiungere un token al payload del messaggio di postback. Quando il componente personalizzato visualizza un'interfaccia utente in cui gli utenti possono premere un elemento azione, viene inviato un messaggio di postback al componente personalizzato. Il componente personalizzato deve valutare i messaggi di postback ricevuti per determinare se il postback proviene dall'interfaccia utente che sta visualizzando o da un altro componente. Per questo può controllare il messaggio di postback se contiene un token aggiunto dal componente personalizzato durante il rendering dell'elemento azione.

• Utilizzare una variabile di flusso della finestra di dialogo. Se è necessario gestire uno stato più complesso tra i richiami dei componenti personalizzati, ad esempio per tenere traccia dei valori estratti dai messaggi utente, è possibile utilizzare una variabile di flusso della finestra di dialogo per questo. I componenti personalizzati possono creare variabili di flusso della finestra di dialogo in fase di esecuzione in una chiamata a context.variable('variable name', value). Se una variabile del nome specificato non esiste, verrà creata. L'oggetto "valore" può essere tutto ciò di cui hai bisogno per tenere traccia.

Per avere contenuto, è necessario convalidare i parametri di input definiti per un componente personalizzato. Ciò vale anche per i parametri impostati in base alle esigenze. È necessario verificare i seguenti casi:

• Il parametro di input ha un set di valori.

• Il valore non inizia con '$ {', in quanto indica un'espressione per la lettura del valore del parametro di input da una variabile o che un oggetto non viene risolto correttamente nel flusso della finestra di dialogo.

Tutte le risposte ai bot inviate da un componente personalizzato devono utilizzare la classe MessageFactory. La classe MessageFactory può essere utilizzata per creare lo stesso tipo di messaggi utente avanzati del componente Risposta comune, che include l'elenco di valori, allegati, layout scheda e messaggi di testo.

Inoltre, i messaggi definiti con la classe MessageFactory sono indipendenti dal canale. Ciò significa che si crea un singolo messaggio di componente, che viene quindi convertito dai connettori specifici del canale nel formato richiesto dal rispettivo canale client.

Per accedere alla classe MessageFactory da un componente personalizzato, utilizzare il riferimento seguente:

let MessageFactory = context.MessageFactory();

• ☑ Assicurati che i servizi backend siano ottimizzati o astratti per l'uso con le competenze.
• ☑ I componenti personalizzati devono contenere solo codice relativo ai bot. Tutti gli altri codici devono essere spostati in classi o librerie di utility oppure distribuiti come singoli servizi REST in un server remoto o in un servizio cloud.
• ☑ Crea un contratto chiaro e completo tra i componenti personalizzati e le competenze in cui vengono utilizzati.
• ☑ Utilizzare componenti personalizzati per valutazioni complesse. Evitare Apache FreeMarker in questi casi.
• ☑ Gestire lo stato dei componenti per le interazioni utente con più richieste.
• ☑ Convalidare tutti i parametri di input dei componenti personalizzati.
• ☑ Gestire gli errori restituendo una stringa di azione per consentire allo sviluppatore di skill di gestire i problemi.

• Esercitazione: Sviluppo di componenti personalizzati per l'integrazione backend
• Esercitazione: Debug dei componenti personalizzati
• Limiti container incorporati per servizi componenti personalizzati
• Documentazione SDK nodo bot: Codice di esempio MessageFactory per varie risposte UI

Molte delle funzionalità che è possibile impostare per il componente Risposta comune, ad esempio i pulsanti globali per la Guida e l'annullamento, non sono disponibili per il componente Risolvi entità mediante la configurazione.

Tuttavia, è possibile aggiungere funzionalità mancanti utilizzando i gestori di eventi entità. Ciò consente di sfruttare la semplicità del componente Risolvi entità nel flusso della finestra di dialogo senza sacrificare le funzionalità avanzate.

Le funzioni del gestore eventi entità vengono richiamate dai componenti Risolvi entità e Risposta comune durante la risoluzione di un'entità bag composta. Non c'è bisogno di tenere traccia di quale articolo borsa deve essere risolto dopo, in quanto è tutto fatto per voi.

Tuttavia, potresti voler salvare alcune informazioni per un uso successivo. A tal fine sono disponibili due opzioni:

• Le proprietà di risoluzione del contesto sono variabili create nell'oggetto contesto. Le variabili e i relativi valori esistono finché l'entità bag composita non viene risolta o si lascia lo stato del flusso della finestra di dialogo che risolve un'entità bag composita. Il vantaggio di utilizzare le proprietà di risoluzione del contesto è che non è necessario eseguire operazioni di housekeeping.

  • Per scrivere, utilizzare: context.setCustomProperty(name, value);
  • Per leggere, utilizzare: context.getCustomProperty(name);

• Le variabili del flusso di dialogo create in runtime o in fase di progettazione possono essere utilizzate per memorizzare i valori che si desidera rendere persistenti oltre la risoluzione dell'entità sacchetto composito. È possibile accedere al contenuto memorizzato nelle variabili di flusso della finestra di dialogo dagli stati di flusso della finestra di dialogo (per le variabili definite solo al momento della progettazione) e da altri gestori di eventi entità.

  • Per scrivere, utilizzare: context.variable(name,value);
  • Per leggere, utilizzare: context.variable(name);

Il logger predefinito implementato per i gestori di eventi entità è il logger della console.

È possibile accedere al logger tramite una chiamata a context.logger().

È possibile utilizzare le funzioni di registrazione delle chiamate disponibili per il logger della console, ad esempio .info('…') o .warn('…').

I messaggi utente personalizzati vengono visualizzati tramite la funzione context.addMessage(). Come per i componenti del flusso di finestre di dialogo personalizzati, si consiglia di utilizzare la classe MessageFactory per creare messaggi indipendenti dal canale invece di eseguire l'output di payload specifici del canale. I gestori di eventi entità supportano anche messaggi di tipo elenco di valori, layout scheda e allegato.

• ☑ Memorizzare i valori temporanei nel contesto di risoluzione a meno che non sia necessario in uno stato di flusso della finestra di dialogo successivo.
• ☑ Utilizzare un singolo servizio di componenti personalizzati per tutti i gestori di eventi entità utilizzati in una skill.
• ☑ Utilizzare la classe MessageFactory per visualizzare i messaggi agli utenti.

• Video del Design Camp di Oracle Digital Assistant: Comprendere i gestori di eventi entità

• Esercitazione: Developing Entity Event Handler nel browser

• Esercitazione: Sviluppo del gestore eventi entità in un IDE esterno
• Esempio: conversazioni basate su modelli che utilizzano EEH mediante un esempio di nota spese
• Documentazione SDK nodo bot: MessageFactory codice di esempio per varie risposte UI
• Documentazione: Funzioni del gestore di eventi entità (esposte sull'oggetto contesto)

Di seguito viene descritto come accedere ai parametri denominati in un bundle di risorse.

//Entity event handler sample
let expression = "${rb('key_name','param_name1,param_name2',"+value1+","+value2+")}";
let message = messageFactory.createTextMessage(expression);
context.addMessage(message,true);

//Custom dialog flow component sample
let expression = "${rb('key_name','param_name1,param_name2',"+value1+","+value2+")}";
let message = messageFactory.createTextMessage(expression);
context.reply(message);

L'utilizzo di bundle di risorse ovunque è un tema comune in questa guida. Tuttavia, l'uso di bundle di risorse memorizzati in uno skill crea uno stretto accoppiamento tra il componente di flusso della finestra di dialogo personalizzata o il gestore di eventi e lo skill. Se stai bene con questa dipendenza e apprezzi il vantaggio di avere stringhe di risorse gestite in un unico posto più che evitare il problema dell'accoppiamento stretto, dovresti farlo. Per i gestori di eventi, la possibilità di riutilizzo è comunque minima, motivo per cui non dovrebbero esserci dubbi sull'uso delle stringhe di bundle di risorse nei gestori di eventi entità.

Per i componenti del flusso di finestre di dialogo personalizzati riutilizzati in skill diversi, la funzione di traduzione funzionerà anche se gli skill dispongono dei nomi delle chiavi del bundle di risorse richiesti dal componente personalizzato aggiunto al bundle di risorse.

Utilizzando una soluzione alternativa, è possibile evitare uno stretto accoppiamento di componenti personalizzati a uno skill passando i messaggi letti da un bundle di risorse come parametri di input a un componente flusso finestra di dialogo personalizzato.