Mettre en oeuvre des composants personnalisés

Utilisez la commande init component de l'interface CLI de la trousse SDK pour créer un fichier JavaScript ou TypeScript avec la structure permettant de travailler avec la trousse SDK Oracle Digital Assistant Node.js pour écrire un composant personnalisé. Le langage que vous avez spécifié lorsque vous avez exécuté la commande init pour créer l'ensemble de composants détermine si un fichier JavaScript ou TypeScript est créé.

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

Votre composant personnalisé doit exporter deux objets :

• metadata : Cela fournit à la compétence les informations suivantes sur le composant.
  • Nom de composant
  • Propriétés prises en charge
  • Actions de transition prises en charge

  Pour les flux de dialogue basés sur YAML, le composant personnalisé prend en charge les propriétés suivantes par défaut. Ces propriétés ne sont pas disponibles pour les compétences conçues en mode de dialogue visuel.

  • autoNumberPostbackActions : Booléen. Facultative. Lorsqu'elle est réglée à true, les boutons et les options de liste sont numérotés automatiquement. La valeur par défaut est false. Voir Numérotation automatique pour les canaux textuels dans les flux de dialogue YAML.
  • insightsEndConversation : Booléen. Facultative. Lorsqu'elle est réglée à true, la session arrête l'enregistrement de la conversation pour le rapport de données clés. La valeur par défaut est false. Voir Modéliser le flux de dialogue.
  • insightsInclude : Booléen. Facultative. Lorsqu'elle est réglée à true, l'état est inclus dans le rapport de données clés. La valeur par défaut est true. Voir Modéliser le flux de dialogue.
  • translate : Booléen. Facultative. Lorsqu'elle est réglée à true, la traduction automatique est activée pour ce composant. La valeur par défaut est celle de la variable de contexte autotranslation. Voir Services de traduction dans les compétences.
• invoke : Contient la logique à exécuter. Dans cette méthode, vous pouvez lire et écrire des variables de contexte de compétence, créer des messages de conversation, définir des transitions d'état, effectuer des appels REST, etc. En général, vous utilisez le mot clé async avec cette fonction pour gérer les promesses. La fonction invoke prend l'argument suivant :
  • context, qui nomme la référence à l'objet CustomComponentContext dans la trousse SDK Node.js de Digital Assistant. Cette classe est décrite dans la documentation de la trousse SDK à l'adresse https://oracle.github.io/bots-node-sdk/. Dans les versions antérieures de la trousse SDK, le nom était conversation. Vous pouvez utiliser l'un ou l'autre nom.
  Note
  
  Si vous utilisez une bibliothèque JavaScript qui ne prend pas en charge les promesses (et n'utilise donc pas le mot clé async), il est également possible d'ajouter un argument done comme rappel que le composant appelle lorsqu'il a terminé le traitement.

Voici un exemple :

'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');   
  }
}

Pour en savoir plus et explorer des exemples de code, voir Écriture de composants personnalisés dans la documentation sur la trousse SDK de développement de robots.

Vous utilisez différentes combinaisons des fonctions de la trousse SDK Bots Node keepTurn et transition pour définir comment le composant personnalisé interagit avec un utilisateur et comment la conversation continue après que le composant retourne le contrôle de flux à la compétence.

• keepTurn(booléen) indique si la conversation doit passer à un autre état sans inviter d'entrée de l'utilisateur.

  Notez que si vous voulez régler keepTurn à true, vous devez appeler keepTurn après avoir appelé reply, car la reply règle implicitement keepTurn à false.

• transition(action) fait passer la boîte de dialogue à l'état suivant après l'envoi de toutes les réponses, le cas échéant. L'argument facultatif action nomme l'action (résultat) retournée par le composant.

  Si vous n'appelez pas transition(), la réponse est envoyée, mais la boîte de dialogue conserve l'état et l'entrée d'utilisateur suivante revient à ce composant. En d'autres termes, invoke() est appelé à nouveau.

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

Voici quelques cas d'utilisation courants de keepTurn et transition pour contrôler le flux de dialogue :

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

Vous utilisez les méthodes d'instance CustomComponentContext pour obtenir le contexte de l'appel, accéder aux variables et les modifier, et renvoyer les résultats au moteur de dialogue.

Vous trouverez plusieurs exemples de code pour utiliser ces méthodes dans Écriture de composants personnalisés et Messagerie de conversation dans la documentation sur la trousse SDK de développement de robots.

La documentation de référence sur la trousse SDK se trouve à l'adresse https://github.com/oracle/bots-node-sdk.

Lorsque vous concevez un composant personnalisé, vous devez déterminer si ce composant sera utilisé par une compétence qui prend en charge plusieurs langues.

Si le composant personnalisé doit prendre en charge les compétences multilingues, vous devez savoir si les compétences sont configurées pour la prise en charge linguistique native ou le service de traduction.

Lorsque vous utilisez un service de traduction, vous pouvez traduire le texte de la compétence. Vous disposez des options suivantes :

• Réglez la propriété translate à Vrai dans l'état du composant personnalisé pour traduire la réponse du composant, comme décrit dans Envoyer des réponses directement au service de traduction.

• Envoyez des données brutes à la compétence dans des variables et utilisez les valeurs des variables dans un composant système qui compose la sortie. Réglez la propriété translate de ce composant à Vrai. Voir Utiliser un composant système pour transmettre le message au service de traduction.

• Envoyez des données brutes à la compétence dans des variables et utilisez les valeurs des variables dans un composant système qui utilise la clé d'ensemble de ressources pour la langue. Voir Utiliser un composant de système pour référencer un ensemble de ressources.

Pour les compétences linguistiques natives, vous disposez des options suivantes :

• Transmettez les données à la compétence dans des variables, puis sortez le texte d'un composant de système en transmettant les valeurs des variables à une clé d'ensemble de ressources, comme décrit dans Utiliser un composant de système pour référencer un ensemble de ressources. Avec cette option, le composant personnalisé doit avoir des propriétés de métadonnées pour que la compétence transmette les noms des variables dans lesquelles stocker les données.

• Utilisez l'ensemble de ressources du composant personnalisé pour rédiger la réponse du composant personnalisé, comme décrit sous Reference Resource Bundles from the Custom Component (Ensembles de ressources de référence du composant personnalisé). Vous utilisez la méthode conversation.translate() pour obtenir la chaîne d'ensemble de ressources à utiliser pour votre appel à context.reply(). Cette option n'est valide que pour les définitions d'ensemble de ressources qui utilisent des paramètres positionnels (numérotés). Il ne fonctionne pas pour les paramètres nommés. Avec cette option, le composant personnalisé doit avoir une propriété de métadonnées pour le nom de la clé d'ensemble de ressources, et les paramètres de la clé d'ensemble de ressources nommée doivent correspondre à ceux utilisés dans l'appel à context.reply().

Voici un exemple d'utilisation de l'ensemble de ressources à partir du composant personnalisé. Dans cet exemple, fmTemplate serait réglé à quelque chose comme ${rb('date.dayOfWeekMessage', 'lundi', '19 juillet 2021')}.

'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();  
  }
};

Un utilisateur peut interrompre le flux d'une conversation avec l'assistant numérique en changeant de sujet. Par exemple, un utilisateur lance un flux pour faire un achat. Il peut l'interrompre pour demander le crédit restant sur une carte-cadeau. Nous appelons cela une incohérence. Pour permettre à l'assistant numérique d'identifier et de gérer les incohérences, appelez la méthode context.invalidInput(payload) lorsque la réponse à un énoncé d'un utilisateur n'est pas comprise dans le contexte du composant.

Dans une conversation numérique, le module d'exécution détermine si une entrée non valide est une incohérence en recherchant des correspondances de réponses dans toutes les compétences. S'il en trouve, le flux est redirigé. Sinon, il affiche le message, s'il est fourni, invite l'utilisateur à effectuer une entrée, puis exécute à nouveau le composant. La nouvelle entrée est transmise au composant dans la propriété text.

Dans une conversation de compétence autonome, le module d'exécution affiche le message, s'il est fourni, invite l'utilisateur à effectuer une entrée, puis exécute à nouveau le composant. La nouvelle entrée est transmise au composant dans la propriété text.

Cet exemple de code appellecontext.invalidInput(payload) chaque fois que l'entrée n'est pas convertie en nombre.

"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();
    }
};

Voici un exemple illustrant la façon dont un assistant numérique traite des entrées non valides lors de l'exécution. Pour la première réponse concernant l'âge (twentyfive), aucune correspondance n'est trouvée dans les compétences associées à l'assistant numérique. La conversation affiche donc le message context.invalidUserInput spécifié. Dans la deuxième réponse concernant l'âge (send money), l'assistant numérique trouve une correspondance. Il demande donc s'il doit effectuer un réacheminement vers ce flux.

Appelez context.invalidInput() ou context.transition(). Si vous appelez les deux opérations, assurez-vous que la variable system.invalidUserInput est toujours définie pour le cas où des messages supplémentaires sont envoyés. Notez également que les composants d'entrée utilisateur (tels que les composants Réponse commune et Résoudre les entités) réinitialisent system.invalidUserInput.

Par exemple, supposons que vous ayez modifié le composant AgeChecker comme présenté ci-dessous et que vous appeliez context.transition() après context.invalidInput().

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

Dans ce cas, le flux de données doit revenir à askage pour que l'utilisateur reçoive deux messages de sortie – "Age input not understood. Please try again" suivi de "How old are you?". Voici comment cela peut être traité dans un flux de dialogue en mode YAML.

  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"