Es gibt kein Feld zum Bereitstellen von Beschreibungen für benutzerdefinierte Komponenten, in dem erläutert wird, was sie tun und welche Informationen an sie übergeben werden müssen. Die besten Möglichkeiten, Skillentwicklern bei der Verwendung Ihrer Komponente zu helfen, sind daher, gute Namen für die Komponente und Eingabeparameter zu verwenden und die Aktionszeichenfolgen, die Ihre Komponente zurückgibt, sorgfältig auszuwählen.

• Integrierte YAML-Komponenten verwenden System.<name> als Namen. Vor allem für YAML-basierte Dialogabläufe können Sie Custom.<name> für Skillprüfer verwenden, um zu verstehen, dass es sich um eine benutzerdefinierte Komponente handelt, die der Dialogablauf referenziert. Sie können auch einen Namensraum verwenden, um Kontext bereitzustellen. Für unsere kundenspezifischen Musterkomponenten verwenden wir oft oracle.sample.<name>, um anzugeben, dass diese Komponenten nicht als Produktionsqualität gedacht sind.

• Eingabeparameter stellen Daten für die zu verarbeitende benutzerdefinierte Komponente bereit. Häufig sind die an eine benutzerdefinierte Komponente übergebenen Daten nicht der tatsächliche Wert, mit dem gearbeitet werden soll, sondern der Name einer Variablen, die entweder die zu verarbeitenden Datenwerte enthält oder in die Daten geschrieben werden sollen, die von einem Remote-Service abgefragt wurden. Beim Betrachten der integrierten Komponenten verwenden sie variable als Eigenschaftsnamen, um den Namen der Variablen zu speichern, in die das Komponentenergebnis geschrieben wird, oder <name>Var (z.B. nlpResultVar), um Eigenschaften anzugeben, die auf einen Variablenreferenznamen verweisen. Sie können dies weiter verbessern, indem Sie die Postfixe _in und _out verwenden, um anzugeben, ob eine Variable auf eine Variable verweist, die Daten enthält oder Daten von der Komponente erwartet.

• Aktionszeichenfolgen sind optional und können vom Skillentwickler verwendet werden, um den nächsten Dialogablaufstatus für die Navigation zu bestimmen. Wenn Sie success oder failure als Aktionszeichenfolge verwenden, wird nicht viel Kontext bereitgestellt. Daher wird empfohlen, stattdessen orderSubmitted, orderRejected oder userUnauthorized zu verwenden.

Die Realität ist, dass oft der Entwickler einer benutzerdefinierten Komponente auch der Skillentwickler ist, der sie verwendet. Aus diesem Grund vereinfachen viele Entwickler ihre Arbeit mit benutzerdefinierten Komponenten, indem sie Annahmen über Variablen treffen, die im Skill vorhanden sind. Anstatt den Namen einer Variablen an die Komponente zu übergeben, verweisen sie direkt auf den Namen in der benutzerdefinierten Komponentenlogik. Wir empfehlen dies nicht, da solche Annahmen eine benutzerdefinierte Komponente leicht brechen können. Es wird empfohlen, einen klaren und vollständigen Vertrag zwischen der benutzerdefinierten Komponente und den verwendeten Skills zu definieren.

Eine allgemeine Frage ist, wie viele benutzerdefinierte Komponenten einem benutzerdefinierten Komponentenservicepaket hinzugefügt werden sollen. Im Allgemeinen ist es immer eine gute Idee, benutzerdefinierte Komponentenservices und die darin enthaltenen Komponenten als Bibliotheken zu betrachten. Daher können alle Komponenten, die sich auf eine Aufgabe beziehen, in einem einzelnen benutzerdefinierten Komponentenservice gespeichert werden. Empfehlungen müssen sich der Realität stellen können. Daher muss die Frage, wie benutzerdefinierte Komponenten verpackt werden sollen, basierend auf der beabsichtigten Verwendung der benutzerdefinierten Komponenten beantwortet werden.

• Wiederverwendung ist keine Option für viele Entwickler benutzerdefinierter Komponenten. Wenn benutzerdefinierte Komponenten für einen bestimmten Skill entwickelt und verwendet werden, ist es sinnvoll, alle diese Komponenten in einem einzelnen benutzerdefinierten Komponentenservice-Deployment zu gruppieren. Die Ausnahme ist für Komponenten, die tatsächlich in anderen Fähigkeiten wiederverwendet werden.

• Eingebettete Komponentencontainer-Deployments sind durch die Anzahl der benutzerdefinierten Komponentenservices pro Oracle Digital Assistant-Instanz eingeschränkt. Daher möchten Sie einen einzelnen benutzerdefinierten Komponentenservice pro Skill verwenden oder nach einem Remote-Deployment Ihrer benutzerdefinierten Komponenten suchen.

• Verwenden Sie das Remote-Deployment benutzerdefinierter Komponentenservices in Kubernetes in Oracle Cloud Infrastructure aus den folgenden Gründen:

  • So geben Sie vertrauliche Informationen nicht weiter, die in Ihrem benutzerdefinierten Komponentencode enthalten sind. Benutzerdefinierte Komponentenservices, die im eingebetteten Container bereitgestellt werden, können von allen Personen heruntergeladen werden, die vollständigen Zugriff auf Ihre Oracle Digital Assistant-Instanz haben.

  • Bessere Segmentierung des Codes. Benutzerdefinierte Komponenten dürfen nur Code enthalten, der zur Interaktion mit dem Bot und zum Aufrufen von REST-Services erforderlich ist. Der gesamte andere Code muss in externen JavaScript-Dateien (wenn ein eingebetteter Container verwendet wird) oder in Integrationslayer (REST-Services) gespeichert werden. Benutzerdefinierte Komponenten umfassen Code, der Folgendes ausführt:

    • Eingabeparameter lesen

    • Variablenwerte lesen/festlegen

    • von einer Komponente empfangene Nachrichten verarbeiten

    • Benutzeroberfläche der benutzerdefinierten Komponente wiedergeben

    • Übergang zu einem nächsten Status bestimmen

    • Komponentenstatus verwalten

    • auf REST-Services zugreifen

  • Um die Leistung zu verbessern. Der eingebettete Container für das Deployment benutzerdefinierter Komponenten in Skills verwendet OCI-Funktionen, die eine Kaltstartverzögerung aufweisen. Um diese Verzögerung zu vermeiden und die Anzahl der Services, die bereitgestellt werden können, zu begrenzen, bietet Ihnen eine Remote-Bereitstellung benutzerdefinierter Komponenten eine sorgenfreie Alternative.

  • Gemeinsame Komponenten gemeinsam verwenden. Obwohl unsere Erfahrung darin besteht, dass die Wiederverwendung unter den Entwicklern von benutzerdefinierten Komponenten nicht sehr hoch eingestuft wird, ist es sinnvoll, häufig verwendete benutzerdefinierte Komponenten zu erstellen und auf einem Remoteserver bereitzustellen. Möglicherweise sind allgemeine Komponenten für Fehlerbehandlung und Eskalation, 2-beinige OAuth2-Autorisierungsverarbeitung und mehr vorhanden.

Der Standardlogger, der für benutzerdefinierte Komponenten implementiert ist, ist der Konsolenlogger. Sie greifen über einen Aufruf an context.logger() auf den Logger zu. Sie können die für den Konsolenlogger verfügbaren Aufrufloggingfunktionen wie ".info('…') oder ".warn('…')" verwenden.

Hinweis: Die Verwendung von context.logger() ist bei der Bereitstellung im eingebetteten Container am sinnvollsten, da der eingebettete Container weiß, wie diese Logs ordnungsgemäß angezeigt werden. Für benutzerdefinierte Komponenten, die Sie extern bereitstellen, sollten Sie eine andere Logging-Library verwenden, wie log4js.

Benutzerdefinierte Dialogablaufkomponenten können eine längere Interaktion mit einem Benutzer haben, bevor die Navigation in einen nächsten Dialogablaufstatus übergeht. Für diese Interaktion müssen Sie sicherstellen, dass die Komponente ihren internen Status verarbeitet, damit sie zwischen einem Erstaufruf und nachfolgenden Aufrufen unterscheiden kann. Dazu gibt es zwei Möglichkeiten:

• Fügen Sie ein Token zur Payload der Postback-Nachricht hinzu. Wenn die benutzerdefinierte Komponente eine Benutzeroberfläche wiedergibt, auf der Benutzer einen Aktionspunkt drücken können, wird eine Postback-Nachricht an die benutzerdefinierte Komponente zurückgesendet. Die benutzerdefinierte Komponente muss die empfangenen Postback-Nachrichten auswerten, um zu bestimmen, ob dieses Postback von der Benutzeroberfläche stammt, die es wiedergibt, oder von einer anderen Komponente. Hierfür kann die Postback-Nachricht geprüft werden, ob sie ein Token enthält, das die benutzerdefinierte Komponente beim Rendern des Aktionspunkts hinzugefügt hat.

• Dialogablaufvariable verwenden Wenn Sie einen komplexeren Status zwischen benutzerdefinierten Komponentenaufrufen verwalten müssen, z.B. um aus Benutzernachrichten extrahierte Werte zu verfolgen, können Sie dafür eine Dialogablaufvariable verwenden. Benutzerdefinierte Komponenten können Dialogablaufvariablen zur Laufzeit in einem Aufruf von context.variable('variable name', value) erstellen. Wenn eine Variable mit dem angegebenen Namen nicht vorhanden ist, wird sie erstellt. Das Objekt "Wert" kann alles sein, was Sie im Auge behalten müssen.

Eingabeparameter, die Sie für eine benutzerdefinierte Komponente definieren, müssen validiert werden, um Inhalt zu haben. Dies gilt auch für Parameter, die Sie bei Bedarf festlegen. Folgende Fälle müssen geprüft werden:

• Der Eingabeparameter hat ein Werteset.

• Der Wert beginnt nicht mit '$ {', da dies einen Ausdruck zum Lesen des Eingabeparameterwerts aus einer Variablen angibt oder ein Objekt im Dialogablauf nicht korrekt aufgelöst wird.

Alle Botantworten, die Sie von einer benutzerdefinierten Komponente senden, müssen die Klasse MessageFactory verwenden. Mit der Klasse MessageFactory kann derselbe Typ von Rich-User-Nachrichten erstellt werden wie die Komponente "Allgemeine Antwort", die Wertelisten, Anhänge, Kartenlayouts und Textnachrichten enthält.

Darüber hinaus sind Nachrichten, die mit der Klasse MessageFactory definiert sind, kanalunabhängig. Dies bedeutet, dass Sie eine einzelne Komponentenmeldung erstellen, die dann von den kanalspezifischen Connectors in das vom jeweiligen Clientkanal benötigte Format konvertiert wird.

Um von einer benutzerdefinierten Komponente auf die Klasse MessageFactory zuzugreifen, verwenden Sie die folgende Referenz:

let MessageFactory = context.MessageFactory();

• ☑ Stellen Sie sicher, dass Backend-Services für die Verwendung mit Skills optimiert oder abstrahiert sind.
• ☑ Benutzerdefinierte Komponenten dürfen nur botbezogenen Code enthalten. Der gesamte andere Code muss in Utilityklassen oder -bibliotheken verschoben oder als einzelne REST-Services auf einem Remoteserver oder Cloud-Service bereitgestellt werden.
• ☑ Erstellen Sie einen klaren und vollständigen Vertrag zwischen benutzerdefinierten Komponenten und den Skills, in denen sie verwendet werden.
• ☑ Verwenden Sie benutzerdefinierte Komponenten für komplexe Auswertungen. Vermeiden Sie in diesen Fällen Apache FreeMarker.
• ☑ Komponentenstatus für Benutzerinteraktionen mit mehreren Anforderungen verwalten.
• ☑ Validieren Sie alle Eingabeparameter für benutzerdefinierte Komponenten.
• ☑ Behandeln Sie Fehler, indem Sie eine Aktionszeichenfolge zurückgeben, damit der Skillentwickler Probleme lösen kann.

• Tutorial: Benutzerdefinierte Komponentenentwicklung für Backend-Integration
• Tutorial: Debugging von benutzerdefinierten Komponenten
• Grenzwerte für eingebettete Container für benutzerdefinierte Komponentenservices
• Bots Node-SDK-Dokumentation: MessageFactory Beispielcode für verschiedene UI-Antworten

Viele der Funktionen, die für die Komponente "Allgemeine Antwort" festgelegt werden können, wie globale Schaltflächen für Hilfe und Abbrechen, sind für die Komponente "Entitäten auflösen" nicht über die Konfiguration verfügbar.

Sie können jedoch fehlende Funktionen mit Entity Event Handlern hinzufügen. Auf diese Weise können Sie die Einfachheit der Komponente "Entitäten auflösen" im Dialogablauf nutzen, ohne die erweiterte Funktionalität zu beeinträchtigen.

Entity-Event-Handler-Funktionen werden von den Resolve-Entitys und Common-Response-Komponenten beim Auflösen einer Mischentity aufgerufen. Sie müssen nicht verfolgen, welcher Beutelartikel als Nächstes gelöst werden muss, da alles für Sie erledigt ist.

Dennoch können Sie einige Informationen für die spätere Verwendung speichern. Dazu stehen zwei Optionen zur Verfügung:

• Kontextauflösungseigenschaften sind Variablen, die Sie für das Kontextobjekt erstellen. Die Variablen und ihre Werte sind vorhanden, bis die Mischentity aufgelöst ist oder Sie den Dialogablaufstatus verlassen, der eine Mischentity auflöst. Der Vorteil der Verwendung der Eigenschaften für die Kontextauflösung besteht darin, dass Sie keinen Housekeeping-Service benötigen.

  • Zum Schreiben verwenden Sie: context.setCustomProperty(name, value);
  • Zum Lesen verwenden Sie: context.getCustomProperty(name);

• Dialogflussvariablen, die zur Laufzeit oder zur Entwurfszeit erstellt wurden, können verwendet werden, um Werte zu speichern, die über die Auflösung der Mischentity hinaus persistiert werden sollen. Auf Inhalt, der in Dialogablaufvariablen gespeichert ist, kann über Dialogablaufstatus (nur für zur Entwurfszeit definierte Variablen) und andere Entity-Event-Handler zugegriffen werden.

  • Zum Schreiben verwenden Sie: context.variable(name,value);
  • Zum Lesen verwenden Sie: context.variable(name);

Der für Entity Event Handler implementierte Standardlogger ist der Konsolenlogger.

Sie greifen über einen Aufruf an context.logger() auf den Logger zu.

Sie können die für den Konsolenlogger verfügbaren Aufrufloggingfunktionen wie .info('…') oder .warn('…') verwenden.

Benutzerdefinierte Benutzernachrichten werden über die Funktion context.addMessage() angezeigt. Wie bei benutzerdefinierten Dialogablaufkomponenten wird empfohlen, die Klasse MessageFactory zum Erstellen kanalagnostischer Nachrichten zu verwenden, anstatt kanalspezifische Payloads auszugeben. Entity-Event-Handler unterstützen auch Nachrichten vom Typ "Werteliste", "Kartenlayout" und "Anhang".

• ☑ Speichern Sie temporäre Werte im Lösungskontext, es sei denn, Sie benötigen sie in einem späteren Dialogablaufstatus.
• ☑ Verwenden Sie einen einzelnen benutzerdefinierten Komponentenservice für alle Entity-Event-Handler, die in einem Skill verwendet werden.
• ☑ Verwenden Sie die Klasse MessageFactory, damit Nachrichten für Benutzer angezeigt werden.

• Oracle Digital Assistant Design Camp-Video: Entity Event Handler

• Tutorial: Entity Event Handler im Browser entwickeln

• Tutorial: Entity Event Handler in externer IDE entwickeln
• Beispiel: Modellgesteuerte Unterhaltungen mit EEH nach Beispiel einer Spesenabrechnung
• Bots Node-SDK-Dokumentation: MessageFactory Beispielcode für verschiedene UI-Antworten
• Dokumentation: Entity Event Handler-Funktionen (im Kontextobjekt dargestellt)

So können Sie auf benannte Parameter in einem Resource Bundle zugreifen:

//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);

Die Verwendung von Resource Bundles überall ist ein allgemeines Thema in dieser Dokumentation. Die Verwendung von Resource Bundles, die in einem Skill gespeichert sind, schafft jedoch eine enge Kopplung zwischen der benutzerdefinierten Dialogablaufkomponente oder dem Ereignis-Handler und dem Skill. Wenn Sie mit dieser Abhängigkeit einverstanden sind und den Vorteil schätzen, dass Ressourcenzeichenfolgen an einem einzigen Ort verwaltet werden, anstatt das Problem der engen Kopplung zu vermeiden, sollten Sie dies tun. Für Event Handler ist die Wiederverwendungswahrscheinlichkeit ohnehin minimal, weshalb es keinen Zweifel an der Verwendung von Resource Bundle-Zeichenfolgen in Entity Event Handlern geben sollte.

Bei benutzerdefinierten Dialogablaufkomponenten, die in verschiedenen Skills wiederverwendet werden, funktioniert die Übersetzungsfunktion auch, wenn die Skills die Resource Bundle-Schlüsselnamen aufweisen, die von der benutzerdefinierten Komponente benötigt werden, die ihrem Resource Bundle hinzugefügt wurde.

Mit einer alternativen Lösung können Sie eine enge Kopplung benutzerdefinierter Komponenten an einen Skill vermeiden, indem Sie die aus einem Resource Bundle gelesenen Nachrichten als Eingabeparameter an eine benutzerdefinierte Dialogablaufkomponente übergeben.