SDKのCLI init componentコマンドを使用し、Oracle Digital Assistant Node.js SDKと連携するためのフレームワークを含むJavaScriptまたはTypeScriptファイルを作成し、カスタム・コンポーネントを記述します。initコマンドを実行してコンポーネント・パッケージを作成したときに指定した言語によって、JavaScriptファイルとTypeScriptファイルのどちらが作成されるかが決まります。

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

カスタム・コンポーネントは、2つのオブジェクトをエクスポートする必要があります:

• metadata: 次のコンポーネント情報をスキルに提供します。
  • コンポーネント名
  • サポートされるプロパティ
  • サポートされる遷移アクション

  YAMLベースのダイアログ・フローの場合、カスタム・コンポーネントではデフォルトで次のプロパティがサポートされます。これらのプロパティは、ビジュアル・ダイアログ・モードで設計されたスキルには使用できません。

  • autoNumberPostbackActions: ブール。必須ではありません。trueの場合、ボタンおよびリストのオプションに自動的に番号が付けられます。デフォルトはfalseです。「YAMLダイアログ・フローのテキストのみのチャネルの自動番号付け」を参照してください。
  • insightsEndConversation: ブール。必須ではありません。trueの場合、セッションがインサイト・レポート用の会話の記録を停止します。デフォルトはfalseです。ダイアログ・フローのモデリングを参照してください。
  • insightsInclude: ブール。必須ではありません。trueの場合、状態がインサイト・レポートに含まれます。デフォルトはtrueです。ダイアログ・フローのモデリングを参照してください。
  • translate: ブール。必須ではありません。trueの場合、このコンポーネントで自動翻訳が有効になります。デフォルトは、autotranslationコンテキスト変数の値です。スキルでの翻訳サービスを参照してください。
• invoke: 実行するロジックが含まれます。このメソッドで、スキル・コンテキスト変数の読取りと書込み、会話メッセージの作成、状態遷移の設定、RESTコールの実行などを行うことができます。通常は、この関数でasyncキーワードを使用してpromiseを処理します。invoke関数は、次の引数を取ります。
  • context: デジタル・アシスタントNode.js SDKのCustomComponentContextオブジェクトへの参照を指定します。このクラスについては、SDKのドキュメント(https://oracle.github.io/bots-node-sdk/)で説明しています。SDKの以前のバージョンでは、名前はconversationでした。いずれの名前も使用できます。
  ノート
  
  Promiseをサポートしていない(したがってasyncキーワードを使用していない)JavaScriptライブラリを使用している場合は、処理が終了したときにコンポーネントが起動するコールバックとしてdone引数を追加することもできます。

次に例を示します:

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

詳細およびいくつかのコード例は、Bots Node SDKドキュメントのカスタム・コンポーネントの記述を参照してください。

Bots Node SDKのkeepTurn関数とtransition関数の様々な組合せを使用して、カスタム・コンポーネントがユーザーとやり取りする方法およびコンポーネントがフロー制御をスキルに返した後の会話の続行方法を定義します。

• keepTurn(boolean)は、先にユーザー入力を要求せずに会話を別の状態に遷移するかどうかを指定します。

  keepTurnをtrueに設定する場合は、replyのコール後にkeepTurnをコールする必要があります。これは、replyが暗黙的にkeepTurnをfalseに設定するためです。

• transition(action)は、応答がある場合は、それらがすべて送信された後にダイアログを次の状態に遷移させます。オプションのaction引数は、コンポーネントが返すアクション(結果)を指定します。

  transition()を呼び出さない場合、レスポンスは送信されますが、ダイアログは状態のままで、後続のユーザー入力はこのコンポーネントに戻ります。つまり、invoke()が再度コールされます。

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

keepTurnおよびtransitionを使用してダイアログ・フローを制御する一般的なユースケースをいくつか次に示します:

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

CustomComponentContextインスタンス・メソッドを使用して、起動のコンテキストを取得し、変数にアクセスして変更し、結果をダイアログ・エンジンに返します。

これらのメソッドを使用するためのコード例は、Bots Node SDKドキュメントのカスタム・コンポーネントの作成および会話メッセージングを参照してください

SDKの参照ドキュメントは、https://github.com/oracle/bots-node-sdkにあります。

カスタム・コンポーネントを設計する際には、そのコンポーネントを複数の言語をサポートするスキルで使用するかどうかを考慮する必要があります。

カスタム・コンポーネントで多言語スキルをサポートする必要がある場合は、スキルがネイティブ言語サポートまたは翻訳サービス用に構成されているかどうかを知る必要があります。

翻訳サービスを使用すると、スキルからテキストを翻訳できます。次のオプションがあります。

• 「レスポンスを翻訳サービスに直接送信」の説明に従って、カスタム・コンポーネントの状態のtranslateプロパティをtrueに設定して、コンポーネントの応答を翻訳します。

• RAWデータを変数内のスキルに戻し、出力を構成するシステム・コンポーネントで変数の値を使用します。そのコンポーネントのtranslateプロパティをtrueに設定します。「翻訳サービスにメッセージを渡すためのシステム・コンポーネントの使用」を参照してください。

• RAWデータを変数でスキルに戻し、その言語にリソース・バンドル・キーを使用するシステム・コンポーネントで変数の値を使用します。システム・コンポーネントを使用したリソース・バンドルの参照を参照してください。

母国語スキルには、次のオプションがあります。

• データを変数内のスキルに戻し、変数の値をリソース・バンドル・キーに渡してシステム・コンポーネントからテキストを出力します(「システム・コンポーネントを使用したリソース・バンドルの参照」を参照)。このオプションでは、データを格納する変数の名前を渡すには、カスタム・コンポーネントにスキルのメタデータ・プロパティが必要です。

• 「カスタム・コンポーネントからのリソース・バンドルの参照」の説明に従って、カスタム・コンポーネントのリソース・バンドルを使用してカスタム・コンポーネントの応答を構成します。conversation.translate()メソッドを使用して、context.reply()へのコールに使用するリソース・バンドル文字列を取得します。このオプションは、位置(番号付き)パラメータを使用するリソースバンドル定義でのみ有効です。名前付きパラメータでは機能しません。このオプションでは、カスタム・コンポーネントにリソース・バンドル・キーの名前のメタデータ・プロパティが必要であり、名前付きリソース・バンドル・キーのパラメータは、context.reply()のコールで使用されるパラメータと一致する必要があります。

カスタム・コンポーネントのリソース・バンドルを使用する例を次に示します。この例では、fmTemplateは${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();  
  }
};

デジタル・アシスタントの会話では、ユーザーは主題を変更することで会話フローを中断できます。たとえば、ユーザーが購入を行うためのフローを開始した場合、そのフローを中断してギフト・カードの残高を確認できます。これは無関係な発言と呼ばれます。デジタル・アシスタントが無関係な発言を識別して処理できるようにするには、ユーザーの発話のレスポンスがコンポーネントのコンテキストで認識されない場合にcontext.invalidInput(payload)メソッドをコールします。

デジタル会話では、ランタイムは、すべてのスキルでレスポンスの一致を検索することにより、無効な入力が無関係な発言であるかどうかを判断します。一致するものが見つかった場合は、フローを再ルーティングします。見つからなかった場合は、メッセージを表示し、指定されていれば、ユーザーに入力を求めた後、コンポーネントを再度実行します。新しい入力は、textプロパティでコンポーネントに渡されます。

スタンドアロン・スキル会話では、ランタイムはメッセージを表示し、指定されていれば、ユーザーに入力を求めた後、コンポーネントを再度実行します。新しい入力は、textプロパティでコンポーネントに渡されます。

次のサンプル・コードでは、入力が数値に変換されない場合は常にcontext.invalidInput(payload)がコールされます。

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

次に、デジタル・アシスタントが実行時に無効な入力をどのように処理するかの例を示します。年齢に関する最初のレスポンス(twentyfive)については、デジタル・アシスタントに登録されているどのスキルにも一致するものがないため、指定されたcontext.invalidUserInputメッセージが会話に表示されます。年齢に関する2番目のレスポンス(send money)では、デジタル・アシスタントは一致するものを見つけたため、そのフローに再ルーティングするかどうかを尋ねます。

context.invalidInput()またはcontext.transition()をコールする必要があります。両方の操作をコールする場合は、追加メッセージが送信される場合にsystem.invalidUserInput変数が引き続き設定された状態になるようにしてください。また、ユーザー入力コンポーネント(共通レスポンス・コンポーネントやエンティティの解決コンポーネントなど)がsystem.invalidUserInputをリセットすることに注意してください。

たとえば、次に示すようにAgeCheckerコンポーネントを変更し、context.invalidInput()の後にcontext.transition()をコールするとします。

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

この場合は、データ・フローが遷移してaskageに戻り、ユーザーが2つの出力メッセージを取得するようにする必要があります – 「Age input not understood.Please try again」と、その後に続く「How old are you?」。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"