Mit dem CLI-Befehl init component des SDK können Sie eine JavaScript- oder TypeScript-Datei mit dem Framework erstellen. Dann können Sie mit dem Node.js-SDK von Oracle Digital Assistant eine benutzerdefinierte Komponente schreiben. Die Sprache, die Sie beim Ausführen des init-Befehls zum Erstellen des Komponentenpackages angegeben haben, bestimmt, ob eine JavaScript- oder TypeScript-Datei erstellt wird.

bots-node-sdk init component <component name> c components

Die benutzerdefinierte Komponente muss zwei Objekte exportieren:

• metadata: Gibt die folgenden Komponenteninformationen für den Skill an.
  • Komponentenname
  • Unterstützte Eigenschaften
  • Unterstützte Übergangsaktionen

  Bei YAML-basierten Dialogabläufen unterstützt die benutzerdefinierte Komponente standardmäßig die folgenden Eigenschaften. Diese Eigenschaften sind für Skills, die im visuellen Dialogmodus entworfen wurden, nicht verfügbar.

  • autoNumberPostbackActions: Boolescher Wert. Nicht erforderlich. Bei true werden Schaltflächen und Listenoptionen automatisch nummeriert. Der Standardwert ist false. Siehe Automatische Nummerierung von Nur-Text-Kanälen in YAML-Dialogabläufen.
  • insightsEndConversation: Boolescher Wert. Nicht erforderlich. Bei true wird die Aufzeichnung der Unterhaltung für Insight-Berichte gestoppt. Der Standardwert ist false. Siehe Dialogablauf modellieren.
  • insightsInclude: Boolescher Wert. Nicht erforderlich. Bei true wird der Status in Insight-Berichte einbezogen. Der Standardwert ist true. Siehe Dialogablauf modellieren.
  • translate: Boolescher Wert. Nicht erforderlich. Bei true ist die automatische Übersetzung für diese Komponente aktiviert. Der Standardwert ist der Wert der Kontextvariablen autotranslation. Siehe Übersetzungsservices in Skills.
• invoke: Enthält die auszuführende Logik. Bei dieser Methode können Sie Skillkontextvariablen lesen und schreiben, Unterhaltungsnachrichten erstellen, Statusübergänge festlegen, REST-Aufrufe tätigen usw. Normalerweise würden Sie das Schlüsselwort async mit dieser Funktion verwenden, um Promises zu verarbeiten. Die Funktion invoke akzeptiert das folgende Argument:
  • context mit Angabe der Referenz zum Objekt CustomComponentContext im Node.js-SDK von Digital Assistant. Diese Klasse wird in der SDK-Dokumentation unter https://oracle.github.io/bots-node-sdk/ beschrieben. In früheren Versionen des SDK lautete der Name conversation. Sie können einen der beiden Namen verwenden.
  Hinweis
  
  Wenn Sie eine JavaScript-Bibliothek verwenden, die keine Promises unterstützt (und daher nicht das Schlüsselwort async verwendet), können Sie auch ein done-Argument als Callback hinzufügen, das die Komponente aufruft, wenn die Verarbeitung abgeschlossen ist.

Beispiel:

'use strict';

module.exports = {

  metadata: {
    name: 'helloWorld',
    properties: {
      human: { required: true, type: 'string' }
    },
    supportedActions: ['weekday', 'weekend']
  },

  invoke: async(context) => {
    // Retrieve the value of the 'human' component property.
    const { human } = context.properties();
    // determine date
    const now = new Date();
    const dayOfWeek = now.toLocaleDateString('en-US', { weekday: 'long' });
    const isWeekend = [0, 6].indexOf(now.getDay()) > -1;
    // Send two messages, and transition based on the day of the week
    context.reply(`Greetings ${human}`)
      .reply(`Today is ${now.toLocaleDateString()}, a ${dayOfWeek}`)
      .transition(isWeekend ? 'weekend' : 'weekday');   
  }
}

Weitere Informationen und einige Codebeispiele finden Sie unter Benutzerdefinierte Komponenten schreiben in der Dokumentation zum Bots Node-SDK.

Sie verwenden verschiedene Kombinationen der Bots Node SDK-Funktionen keepTurn und transition, um zu definieren, wie die benutzerdefinierte Komponente mit einem Benutzer interagiert und wie die Unterhaltung fortgesetzt wird, nachdem die Komponente die Ablaufsteuerung wieder an den Skill übergeben hat.

• keepTurn(boolean) gibt an, ob die Unterhaltung in einen anderen Status übergehen soll, ohne den Benutzer zuerst zur Eingabe aufzufordern.

  Wenn Sie keepTurn auf "true" setzen möchten, sollten Sie keepTurn nach reply aufrufen, weil reply die keepTurn-Funktion implizit auf false setzt.

• transition(action) bewirkt, dass der Dialog nach dem Senden aller etwaiger Antworten in den nächsten Status übergeht. Das optionale action-Argument benennt die jeweilige von der Komponente zurückgegebene Aktion (Ergebnis).

  Wenn Sie transition() nicht aufrufen, wird die Antwort gesendet, der Dialog bleibt jedoch im Status, und die nachfolgende Benutzereingabe kehrt zu dieser Komponente zurück. Das bedeutet, dass invoke() erneut aufgerufen wird.

invoke: async (context) ==> {
   ...
   context.reply(payload);
   context.keepTurn(true);
   context.transition ("success"); 
}

Im Folgenden finden Sie einige häufige Anwendungsfälle, in denen Sie den Dialogablauf mit keepTurn und transition steuern können:

invoke: async (context) => {
    const listVariableName = context.properties().variableName;
    ...
    // Write list of options to a context variable
    context.variable(listVariableName, list);
   // Navigate to next state without 
   // first prompting for user interaction.
   context.keepTurn(true);
   context.transition();
 }

context.keepTurn(false);
context.transition("success");

  invoke: async (context) => {
    // Perform conversation tasks.
    const tracking_token = "a2VlcHR1cm4gZXhhbXBsZQ==";    
    const quotes = require("./json/Quotes.json");
    const quote = quotes[Math.floor(Math.random() * quotes.length)];
    
    // Check if postback action is issued. If postback action is issued, 
    // check if postback is from this component rendering. This ensures
    // that the component only responds to its own postback actions.     
    if (context.postback() && context.postback().token == tracking_token && context.postback().isNo) {
      context.keepTurn(true);
      context.transition();
    } else {
      // Show the quote of the day.
      context.reply("'" + quote.quote + "'");
      context.reply(" Quote by: " + quote.origin);
      // Create a single message with two buttons to 
      // request another quote or not.
      const mf = context.getMessageFactory();
      const message = mf.createTextMessage('Do you want another quote?')
        .addAction(mf.createPostbackAction('Yes', { isNo: false, token: tracking_token }))
        .addAction(mf.createPostbackAction('No', { isNo: true, token: tracking_token })); 
      context.reply(message);
      // Although reply() automatically sets keepTurn to false, 
      // it's good practice to explicitly set it so that it's
      // easier to see how you intend the component to behave.
      context.keepTurn(false);
    };
  }

invoke: async (context) => {

  const quotes = require("./json/Quotes.json");
  const quote = quotes[Math.floor(Math.random() * quotes.length)];
  
  // Check if postback action is issued and postback is from this component rendering. 
  // This ensures that the component only responds to its own postback actions.     
  const um = context.getUserMessage()
  if (um instanceof PostbackMessage && um.getPostback() && um.getPostback()['system.state'] === context.getRequest().state && um.getPostback().isNo) {
    context.keepTurn(true);
    context.transition();
  } else {
    // Show the quote of the day.
    context.reply(`'${quote.quote}'`);
    context.reply(`Quote by: ${quote.origin}`);
    // Create a single message with two buttons to request another quote or not.
    let actions = [];

    const mf = context.getMessageFactory();
    const message = mf.createTextMessage('Do you want another quote?')
      .addAction(mf.createPostbackAction('Yes', { isNo: false }))
      .addAction(mf.createPostbackAction('No', { isNo: true }));
    context.reply(message);
    // Although reply() automatically sets keepTurn to false, it's good practice to explicitly set it so that it's
    // easier to see how you intend the component to behave.
    context.keepTurn(false);
  }
}

Mit CustomComponentContext-Instanzmethoden können Sie den Kontext für den Aufruf abrufen, Variablen anzeigen und ändern und Ergebnisse an die Dialog-Engine zurücksenden.

Codebeispiele zur Verwendung dieser Methoden finden Sie unter Benutzerdefinierte Komponenten schreiben und Unterhaltungsmessaging in der Dokumentation des Bots Node-SDK.

Die SDK-Referenzdokumentation finden Sie unter https://github.com/oracle/bots-node-sdk.

Wenn Sie eine benutzerdefinierte Komponente entwerfen, sollten Sie überlegen, ob die Komponente von einem Skill verwendet wird, der mehrere Sprachen unterstützt.

Wenn die benutzerdefinierte Komponente mehrsprachige Skills unterstützen muss, müssen Sie wissen, ob die Skills für die native Sprachunterstützung oder den Übersetzungsservice konfiguriert sind.

Wenn Sie einen Übersetzungsservice verwenden, können Sie den Text aus dem Skill übersetzen. Sie haben folgende Optionen:

• Setzen Sie die Eigenschaft translate im Status der benutzerdefinierten Komponente auf "true", um die Antwort der Komponente zu übersetzen, wie unter Antworten direkt an den Übersetzungsservice senden beschrieben.

• Senden Sie Rohdaten an den Skill in Variablen zurück, und verwenden Sie die Werte der Variablen in einer Systemkomponente, aus der die Ausgabe besteht. Setzen Sie die Eigenschaft translate dieser Komponente auf "true". Siehe Systemkomponente zum Übergeben der Nachricht an den Übersetzungsservice verwenden.

• Senden Sie Rohdaten an den Skill in Variablen zurück, und verwenden Sie die Variablenwerte in einer Systemkomponente, die den Resource Bundle-Schlüssel für die Sprache verwendet. Siehe Resource Bundle mit einer Systemkomponente referenzieren.

Für Sprachkenntnisse in Muttersprache stehen Ihnen folgende Optionen zur Verfügung:

• Übergeben Sie die Daten an den Skill in Variablen, und geben Sie dann den Text aus einer Systemkomponente aus, indem Sie die Werte der Variablen an einen Resource Bundle-Schlüssel übergeben, wie unter Systemkomponente zum Referenzieren eines Resource Bundles verwenden beschrieben. Mit dieser Option muss die benutzerdefinierte Komponente Metadateneigenschaften aufweisen, damit der Skill die Namen der Variablen zum Speichern der Daten übergeben kann.

• Verwenden Sie das Resource Bundle aus der benutzerdefinierten Komponente, um die Antwort der benutzerdefinierten Komponente zu verfassen, wie unter Resource Bundles aus der benutzerdefinierten Komponente referenzieren beschrieben. Mit der Methode conversation.translate() rufen Sie die Resource Bundle-Zeichenfolge ab, die für Ihren Aufruf von context.reply() verwendet werden soll. Diese Option ist nur für Resource Bundle-Definitionen gültig, die positionale (nummerierte) Parameter verwenden. Es funktioniert nicht für benannte Parameter. Bei dieser Option muss die benutzerdefinierte Komponente eine Metadateneigenschaft für den Namen des Resource Bundle-Schlüssels aufweisen, und die Parameter des benannten Resource Bundle-Schlüssels müssen mit denen übereinstimmen, die beim Aufruf von context.reply() verwendet werden.

Im Folgenden finden Sie ein Beispiel für die Verwendung des Resource Bundles aus der benutzerdefinierten Komponente. In diesem Beispiel würde fmTemplate auf ${rb('date.dayOfWeekMessage', 'lundi', '19 juillet 2021')} gesetzt.

'use strict';

var IntlPolyfill    = require('intl');
Intl.DateTimeFormat = IntlPolyfill.DateTimeFormat;

module.exports = {
  metadata: () => ({
    name: 'Date.DayOfWeek',
    properties: {
      rbKey:   { required: true,  type: 'string'    }
    },
    supportedActions: []
  }),
  invoke: (context, done) => {
    const { rbKey } = context.properties();
    if (!rbKey || rbKey.startsWith('${')){
      context.transition();
            done(new Error('The state is missing the rbKey property or it uses an invalid expression to pass the value.'));
    }
    //detect user locale. If not set, define a default
    const locale  = context.getVariable('profile.locale') ? 
      context.getVariable('profile.locale') : 'en-AU';  
    const jsLocale     = locale.replace('_','-');
    //when profile languageTag is set, use it. If not, use profile.locale
    const languageTag = context.getVariable('profile.languageTag')?
                      context.getVariable('profile.languageTag') : jslocale;
   /* =============================================================
      Determine the current date in local format and 
      the day name for the locale
      ============================================================= */
    var now          = new Date();
    var dayTemplate  = new Intl.DateTimeFormat(languageTag,
      { weekday: 'long' });
    var dayOfWeek    = dayTemplate.format(now);
    var dateTemplate = new Intl.DateTimeFormat(languageTag, 
      { year: 'numeric', month: 'long', day: 'numeric'});
    var dateToday    = dateTemplate.format(now);

   /* =============================================================
      Use the context.translate() method to create the ${Freemarker} 
      template that's evaluated when the reply() is flushed to the 
      client.
      ============================================================= */
    const fmTemplate = context.translate(rbKey, dateToday, dayOfWeek );

    context.reply(fmTemplate)
                .transition()
                .logger().info('INFO : Generated FreeMarker => ' 
                + fmTemplate);
    done();  
  }
};

In einer Unterhaltung über den digitalen Assistenten kann ein Benutzer den Unterhaltungsablauf unterbrechen, indem er den Betreff ändert. Beispiel: Wenn ein Benutzer einen Ablauf zum Kauf startet, kann er diesen Ablauf unterbrechen, um abzufragen, wie viel Guthaben er noch auf einer Geschenkkarte hat. Wir bezeichnen dies als nicht sequenzielle Abfolge. Damit der digitale Assistent nicht folgerichtige Abfolgen identifizieren und verarbeiten kann, rufen Sie die context.invalidInput(payload)-Methode auf, wenn eine Benutzeräußerungsantwort im Kontext der Komponente nicht verstanden wird.

In einer digitalen Unterhaltung bestimmt die Laufzeit, ob eine ungültige Eingabe eine nicht sequenzielle Abfolge ist, indem in allen Skills nach Antwortübereinstimmungen gesucht wird. Wenn sie Übereinstimmungen findet, wird der Ablauf umgeleitet. Andernfalls wird die Meldung angezeigt (sofern vorhanden), der Benutzer wird zur Eingabe aufgefordert, und die Komponente wird erneut ausgeführt. Die neue Eingabe wird an die Komponente in der Eigenschaft text übergeben.

In einer Unterhaltung mit einem Standalone-Skill zeigt die Laufzeit die Nachricht an (sofern vorhanden), fordert den Benutzer zur Eingabe auf und führt die Komponente erneut aus. Die neue Eingabe wird an die Komponente in der Eigenschaft text übergeben.

Dieser Beispielcode ruft context.invalidInput(payload) auf, wenn die Eingabe keine Zahl ist.

"use strict"
 
module.exports = {
 
    metadata: () => ({
        "name": "AgeChecker",
        "properties": {
            "minAge": { "type": "integer", "required": true }
        },
        "supportedActions": [
            "allow",
            "block",
            "unsupportedPayload"
        ]
    }),
 
    invoke: (context, done) => {
        // Parse a number out of the incoming message
        const text = context.text();
        var age = 0;
        if (text){
          const matches = text.match(/\d+/);
          if (matches) {
              age = matches[0];
          } else {
              context.invalidUserInput("Age input not understood. Please try again");
              done();
              return;
          }
        } else {
          context.transition('unsupportedPayload");
          done();
          return;
        }
 
        context.logger().info('AgeChecker: using age=' + age);
 
        // Set action based on age check
        let minAge = context.properties().minAge || 18;
        context.transition( age >= minAge ? 'allow' : 'block' );
 
        done();
    }
};

Nachfolgend finden Sie ein Beispiel dafür, wie ein digitaler Assistent ungültige Eingaben zur Laufzeit verarbeitet. Für die erste Altersantwort (twentyfive) gibt es keine Übereinstimmungen in den Skills, die beim digitalen Assistenten registriert sind. Die Unterhaltung zeigt also die angegebene Nachricht context.invalidUserInput an. In der zweiten Altersantwort (Geld senden) findet der digitale Assistent eine Übereinstimmung, sodass er fragt, ob an diesen Ablauf umgeleitet werden soll.

Rufen Sie entweder context.invalidInput() oder context.transition() auf. Wenn Sie beide Vorgänge aufrufen, stellen Sie sicher, dass die Variable system.invalidUserInput noch festgelegt ist, wenn zusätzliche Nachrichten gesendet werden. Beachten Sie auch, dass Benutzereingabekomponenten (wie Common Response- und Resolve-Entity-Komponenten) system.invalidUserInput zurücksetzen.

Beispiel: Die AgeChecker-Komponente wird wie unten dargestellt geändert, und context.transition() wird nach context.invalidInput() aufgerufen.

if (matches) {  age = matches[0]; } else { 
      context.invalidUserInput("Age input not understood. Please try again"); 
      context.transition("invalid"); 
      context.keepTurn(true);
      done();
      return;
}

In diesem Fall muss der Datenfluss wieder zu askage übergehen, sodass der Benutzer zwei Ausgabenachrichten erhält: "Altersangabe nicht verstanden. Bitte versuchen Sie es erneut", gefolgt von "Wie alt sind Sie?". So kann das in einem Dialogablauf im YAML-Modus behandelt werden.

  askage:
    component: "System.Output"
    properties:
      text: "How old are you?"
    transitions:
      next: "checkage"
  checkage:
    component: "AgeChecker"
    properties:
      minAge: 18
    transitions:
      actions:
        allow: "crust"
        block: "underage"
        invalid: "askage"