Oracle Cloud Infrastructureドキュメント

スキルへのコンポーネント・パッケージの追加

コンポーネント・パッケージをスキルに追加するには、コンポーネント・サービスを作成します。

外部サーバー、Oracle Cloud Infrastructure FunctionsまたはOracle Mobile Hubでホストするコンポーネント・パッケージの場合、コンポーネント・サービスはスキルからホスト・サーバーへのアクティブな接続です。あるいは、コンポーネント・パッケージをアップロードし、Oracle Digital Assistantインスタンスからホストすることもできます。これは、埋込みコンポーネント・サービスと呼ばれます。

コンポーネント・サービスには2つの機能があります:

  • コンポーネントに問い合せて、パッケージ・メタデータ(コンポーネントの名前、そのプロパティ、各コンポーネントで許可されるアクションなど)を取得します。サービスがスキルに追加されると、左側のナビゲーション・バーで「コンポーネント」(これは「コンポーネント」アイコンのイメージです。 )をクリックしてアクセスする「コンポーネント」タブにこの情報が表示されます。このページを参照して、ダイアログ・フローでコンポーネントを使用するために必要となるコンポーネント名、プロパティおよびアクションを取得できます。

  • スキルがコンポーネントを起動できるようにします。

    ダイアログ・エンジンによってコンポーネントに対して行われるコールのJSONペイロードには、入力パラメータ、変数値、ユーザーレベル・コンテキストおよびユーザーのメッセージ・テキストが含まれます。コンポーネントは、既存の変数の値を変更するか、新しいものを追加して(またはその両方により)、結果を返します。ダイアログ・エンジンは、返されたペイロードを解析し、処理を続行します。

カスタム・コンポーネント・パッケージをスキルに追加するには、スキルの「コンポーネント」タブ(これは「コンポーネント」アイコンのイメージです。 )に移動し、「サービスの追加」をクリックします。これにより、サービスを構成するためのダイアログが開きます。

サービスの構成方法は、コンポーネント・パッケージをホストする場所によって異なります。これらのトピックで、各タイプの手順について説明します:

サービスの作成後、カスタム・コンポーネントの説明に従って、ダイアログ・フローからカスタム・コンポーネントを起動できます。

パッケージが埋込みコンテナにアップロードされると、デジタル・アシスタントは、パッケージが有効であることを検証し、次の理由によりパッケージを拒否できます:

  • JavaScriptエラーがあります。

  • パッケージにノード・モジュール依存関係の一部が含まれていません。

  • コンポーネント名が100文字を超えているか、System.で始まるか、英数字およびアンダースコア以外の文字を含む場合、サービスの作成は失敗します。

  • インスタンスに、すでに埋込みコンポーネント・サービスの最大数が含まれています。

  • TGZファイルが大きすぎます。これは通常、.npmignoreファイルに*.tgzエントリが含まれていないため、ファイルをパックするたびに、既存のTGZのネストされたコピーが追加される場合に発生します。

これらの検証チェックの詳細は、埋込みコンポーネント・サービスの追加を参照してください。

埋込みコンポーネント・サービスの追加

Oracle Digital Assistantインスタンスからカスタム・コンポーネント・パッケージをホストする場合は、次のステップを実行します:

  1. 埋込みコンテナ・サービスのパッケージの準備

  2. 埋込みコンポーネント・サービスを作成するためのパッケージのアップロード。

埋込みコンテナ・サービスのパッケージの準備

Oracle Digital Assistantからカスタム・コンポーネント・パッケージを埋込みコンポーネント・サービスとしてホストする場合は、まずカスタム・コンポーネントをTGZファイルにパックする必要があります。次に、埋込みコンポーネント・サービスを作成するときに、このファイルをアップロードします。

bots-node-sdk packを使用してパッケージ化したこのTGZファイルには、「カスタム・コンポーネントの実装」で説明したアセットと構造を含める必要があります。また、それが依存するすべてのノード・モジュールが含まれている必要もあります(bots-node-sdk packによって自動的に実行されます)。

ノート

インスタンスに含めることができる埋込みカスタム・コンポーネント・サービスの数には制限があります。制限が不明な場合は、インフラストラクチャ・コンソールでのサービス制限の表示の説明に従って、embedded-custom-component-service-countの取得をサービス管理者に依頼してください。この制限に達した後にコンポーネント・サービスを追加しようとすると、サービスの作成に失敗します。

埋込みコンテナ・サービスにアップロードできるようにパッケージを準備するには:

  1. Bots Node.jsコマンド行ツールの最新バージョンがあることを確認します。

    埋込みコンテナを使用するには、TGZファイルにすべてのdependenciesが含まれている必要があります。以前のバージョンでは、dependenciesがファイルにバンドルされませんでした。TGZファイルの作成に使用するコマンドにより、TGZファイルに含める必要があるすべての依存モジュールをリストするbundledDependenciesノードがpackage.jsonファイルに必ず含まれるようになりました。

  2. main.jsファイルが含まれているディレクトリで、パッケージが依存するモジュールごとに次のコマンドを実行します。Bots Node SDKなどのdevDependenciesについてはこれを行う必要はありません。

    このコマンドでは、モジュールがnode_modulesフォルダに追加され、それが依存関係としてpackage.jsonに追加されます。 

    npm install <module>

    package.jsonですべての依存性をすでに指定している場合は、かわりにnpm installを実行できます。

  3. 最上位フォルダに、*.tgzエントリが含まれる.npmignoreファイルがあることを確認します。例: 

    *.tgz
spec
service-*

    そうでない場合、ファイルをTGZファイルにパックする際に、最上位フォルダにすでに存在するTGZファイルを含めるので、TGZファイルのサイズが倍増します。ファイルを数回パックすると、TGZファイルはコンテナにアップロードするには大きくなりすぎます。

  4. 次のコマンドを実行します:

    bots-node-sdk pack

    このコマンドは、コンポーネント・パッケージを検証し、必要に応じてdevDependenciesを含むように更新してTGZファイルを作成します。このファイルは、スキルの「コンポーネント」タブから埋込みコンポーネント・サービスを作成するときにアップロードします。dependenciesとしてリストしたファイルはbundledDependenciesとして含まれますが、Bots Node SDKおよびExpressは例外で、これらはdevDependenciesです。

パッケージはノード14.17.0と互換性がある必要があります。

packコマンドの詳細は、https://github.com/oracle/bots-node-sdk/blob/master/bin/CLI.mdを参照してください。

埋込みコンポーネント・サービスを作成するためのパッケージのアップロード

カスタム・コンポーネント・パッケージをTGZファイルにパックしたら、アップロードしてスキルの「コンポーネント」タブから埋込みコンポーネント・サービスを作成できます。

TGZファイルの作成方法を学習するには、埋込みコンテナ・サービスのパッケージの準備を参照してください。

ノート

パッケージを埋込みコンポーネント・サービスにアップロードすると、Oracle Functions Serviceにデプロイされます。インスタンスがOracle Cloud Platformにプロビジョニングされている場合(バージョン19.4.1のすべてのインスタンスと同様に)、サービスはかわりにデジタル・アシスタント内にデプロイされます。

埋込みコンポーネント・サービスを作成するには:

  1. スキルで、「コンポーネント」 「コンポーネント」アイコンをクリックします。

  2. クリック +「サービスの追加」ボタン。

  3. 「埋込みコンテナ」を選択します。

  4. 「コンポーネント・パッケージ・ファイルのアップロード」をクリックしてアップロードするTGZファイルを指すか、ファイルを「パッケージ・ファイル」ボックスにドラッグします。

  5. (オプション)カスタム・コンポーネントのcontext.logger()文をサービスのログに送信する場合は、「コンポーネント・ロギングの有効化」を「オン」に切り替えます。このスイッチは、Oracle Cloud Infrastructure (Generation 2クラウド・インフラストラクチャとも呼ばれる)にプロビジョニングされたOracle Digital Assistantのインスタンスでのみ使用できます。

    「コンポーネント」タブからログを表示するには、「診断」→「ログの表示」をクリックします。

    ノート

    スキルはログ・エントリを2日間保持します。埋込みカスタム・コンポーネント・サービスを削除すると、そのサービスのスキルのログ・エントリが削除されます。

  6. 「作成」をクリックします。

    デジタル・アシスタントはTGZファイルをアップロードし、埋込みコンポーネント・サービスを作成します。アップロード時に、デジタル・アシスタントはパッケージが有効であることを検証し、この項で後述する理由でパッケージを拒否できます。

    TGZファイルをアップロードすると、カスタム・コンポーネント・サービスがビルドされ、そのコンポーネントがデプロイされます。TGZファイルをアップロードした後、「コンポーネント」ページに待機中のデプロイメント・メッセージが表示される場合は、サービスが作成されてはいるものの、まだ使用可能でないことを意味します。サービスが使用可能になると、待機中のデプロイメント・メッセージのかわりにデプロイメント・メタデータが表示されます。

  7. 「サービス有効」が「オン」に切り替えられていることを確認します。

アップロード時に、デジタル・アシスタントがパッケージを拒否することがあります。拒否の理由と問題を解決する方法を次に示します。

  • JavaScriptに構文エラーが含まれている: コンポーネントのJavaScriptに構文エラーが含まれている場合、そのコンポーネントはコンテナに追加されず、次のエラー・メッセージが表示されます: 

    Error Message: failed to start service built: Invalid component
      path:

    構文エラーを検出するエディタでコンポーネント・ファイルを表示します。また、エラー・メッセージをコンソール・ログに送信するローカル・サーバーでパッケージをホストしてみます。

    このメッセージのもう1つの理由は、パッケージにノード・モジュールの依存関係の一部が含まれていないことです。このリストの次の項目を参照してください。

  • ノード・モジュールの欠落: パッケージにノード・モジュールの依存関係の一部が含まれていない場合、前述と同じエラー・メッセージが表示されます: 

    Error Message: failed to start service built: Invalid component
      path:

    ノード・モジュール依存関係を含める方法について学習するには、埋込みコンテナ・サービスのパッケージの準備を参照してください。

  • コンポーネント名が長すぎる: コンポーネント名が100文字を超えているか、System.で始まるか、英数字およびアンダースコア以外の文字を含む場合、サービスの作成は失敗します。

    コンポーネントのJavaScriptで名前を変更し、再パッケージ化してもう一度アップロードします。

  • コンポーネント・サービス制限の超過: インスタンスに、すでに埋込みカスタム・コンポーネント・サービスの最大数が含まれている場合、サービスの作成は失敗します。インフラストラクチャ・コンソールでのサービス制限の表示の説明に従って、embedded-custom-component-service-count制限をサービス管理者に問い合せます。

    制限を増やす必要がある場合は、引上げをリクエストできます。「サービス制限の引上げのリクエスト」を参照してください。

  • TGZファイルが大きすぎる: これは通常、.npmignoreファイルに*.tgzエントリが含まれていないため、ファイルをパックするたびに、既存のTGZのネストされたコピーが追加される場合に発生します。

    最上位フォルダに*.tgzを含む.npmignoreファイルがある場合、パッケージの更新時にTGZファイルの以前のバージョンは含まれません。

カスタム・コンポーネントのcontext.logger()文をサービスのログに送信する場合は、「コンポーネント・ロギングの有効化」を「オン」に切り替えます。このスイッチは、Oracle Cloud Infrastructure (Generation 2クラウド・インフラストラクチャとも呼ばれる)にプロビジョニングされたOracle Digital Assistantのインスタンスでのみ使用できます。

「コンポーネント・ロギングの有効化」を「オン」に切り替えると、サービスの「診断」ボタンをクリックしてビュー・ログおよびクラッシュ・レポートにアクセスし、問題を診断できます。

  • カスタム・コンポーネントがcontext.logger()に送信したメッセージを表示するには、「ログの表示」を選択します。この機能は、Oracle Cloud Infrastructure (Generation 2クラウド・インフラストラクチャとも呼ばれる)にプロビジョニングされたOracle Digital Assistantのインスタンスでのみ使用できます。ログにこれらのメッセージを含めるには、「コンポーネント・ロギングの有効化」スイッチを「オン」にする必要があります。
  • コンテナがクラッシュする原因となった可能性があるものについて詳細を表示するには、「クラッシュ・レポートの表示」を選択します。

サービスの作成後、カスタム・コンポーネントの説明に従って、ダイアログ・フローからカスタム・コンポーネントを起動できます。

Oracle Functionサービスの追加

カスタム・コンポーネントをOracle Cloud Infrastructure Functionsにデプロイし、Oracle Functionサービスとしてスキルに追加できます。

Oracle Functionサービスを追加するには:

  1. ファンクションのURLを知っている必要があります。ファンクション開発権限を持つユーザーが、統合コンソールからURLを取得できます。

    1. 統合コンソールにサインインします。

    2. 左上のナビゲーション・メニュー・アイコンをクリックしてナビゲーション・メニューを開き、「開発者サービス」→「ファンクション」をクリックして、ファンクション開発用に設定されているコンパートメントを選択します。

    3. アプリケーションをクリックします。

    4. 「ファンクション」セクションでファンクションの「詳細」アイコンをクリックし、「呼出しエンドポイントのコピー」をクリックします。スキル開発者が、カスタム・コンポーネント・パッケージをスキルのコンポーネント・サービスとして追加するためには、この値が必要です。

  2. スキル開発者は、コンポーネント・サービスをOracle Digital Assistantでスキルに追加します。Oracle Digital Assistantにサインインし、スキルを開いて、「コンポーネント」 「コンポーネント」アイコンをクリックします。

  3. クリック 「+サービス」ボタン。

  4. サービスの名前と説明を指定します。

  5. 「Oracle Function」を選択します。

  6. 「URL」テキスト・ボックスに呼出しエンドポイントURLを入力します。これは、Oracle Functionsのためのユーザー・アカウントの設定のステップを実行する際に、インフラストラクチャ・コンソールの「開発者サービス」→「ファンクション」ページからコピーしたものです。

  7. 「作成」をクリックします。

    「サービスを作成できません」というエラーが表示された場合は、インフラストラクチャ・コンソールで「開発者サービス」→「ファンクション」に移動し、コンパートメントを選択してアプリケーションをクリックし、「リソース」メニューの「ログ」をクリックします。次に、ファンクションのログを有効にしてデプロイメントを再試行し、ログを確認します(ログ名をクリックするとログが表示されます)。ログの詳細は、Oracle Cloud Infrastructureドキュメントのファンクション・ログの格納および表示を参照してください。

    このようなエラーが表示されるのは、フォルダに適切な権限がないためです。ローカル・マシンで、chmod 775を使用してフォルダの権限を変更してから、再デプロイします: 

    "Error: EACCES: permission denied, stat
'/function/components/hello.world.js.js'"

    その後、このようなエラーが表示された場合は、ローカル・マシンでnode_modulesを削除し、npm installを実行して再デプロイします。 

    "Error: Cannot find module '@fnproject/fdk'"

  8. 「サービス有効」が「オン」に切り替えられていることを確認します。

サービスの作成後、カスタム・コンポーネントの説明に従って、ダイアログ・フローからカスタム・コンポーネントを起動できます。

外部コンポーネント・サービスの追加

カスタム・コンポーネントを独自のNode.jsサーバーでホストし、外部コンポーネント・サービスとしてスキルに追加できます。

ヒント:

開発環境でのコンポーネント・サービスの実行の説明に従って、開発中に外部サービス・オプションを使用できます。

外部コンポーネント・サービスを追加するには:

  1. スキルで、「コンポーネント」 「コンポーネント」アイコンをクリックします。

  2. クリック 「+サービス」ボタン。

  3. 「外部」を選択します。

  4. 「メタデータURL」テキスト・ボックスに、コンポーネントのリストを返すGETエンドポイントを指すURLを入力します。

  5. サービスのユーザー名およびパスワードを入力します。

  6. 「作成」をクリックします。

  7. 「サービス有効」が「オン」に切り替えられていることを確認します。

サービスの作成後、カスタム・コンポーネントの説明に従って、ダイアログ・フローからカスタム・コンポーネントを起動できます。

モバイル・ハブ・コンポーネント・サービスの追加

カスタム・コンポーネントをOracle Mobile Hubからホストし、Oracle Mobile Cloudコンポーネント・サービスとしてスキルに追加できます。モバイル・ハブでホストされているカスタム・コンポーネントは、モバイル・ハブ・バックエンドによって制御されるコネクタを使用してリモート・サービスと統合できるとともに、モバイル・ハブ・プラットフォームAPIにアクセスできます。

カスタム・コードをホストするバックエンドはカスタム・コンポーネントの認証を処理するため、バックエンドの「設定」ページを参照して、構成を完了するために必要な情報を取得する必要があります。

モバイル・ハブ・バックエンドのコンポーネント・サービスを追加するには:

  1. スキルで、「コンポーネント」 「コンポーネント」アイコンをクリックします。

  2. クリック 「+サービス」ボタン。

  3. 「Oracle Mobile Cloud」を選択します。

  4. 「バックエンドID」フィールドに、モバイル・ハブ・バックエンドに割り当てられた一意の識別子を入力します。このIDは、スキルからの各コールのRESTヘッダーで渡されます。

  5. 「MetadataURL」フィールドに、カスタム・コードAPIから/componentsエンドポイントを入力します。たとえば、http://<server>:<port>/mobile/custom/ccPackage/componentsです。

  6. サービスで匿名ログインを許可する場合、「匿名アクセスの使用」を選択します。このオプションを選択する場合は、エンコードされたユーザー名とパスワードを送信せずにアプリケーションが匿名APIにアクセスするための一意の文字列である匿名キーを入力します。それらのかわりに匿名キーが渡されます。匿名キーは、モバイル・ハブのバックエンドの「設定」ページにあります。(「表示」をクリックする必要がある場合があります。)

    コンポーネント・サービスでログインを要求する(匿名アクセスを使用しない)場合は、ユーザー名とパスワードを入力します。

  7. サービスに固有のパラメータが必要な場合、「HTTPヘッダーの追加」をクリックし、ヘッダーのキーと値のペアを定義します。

  8. 「作成」をクリックします。

  9. 「サービス有効」が「オン」に切り替えられていることを確認します。

サービスの作成後、カスタム・コンポーネントの説明に従って、ダイアログ・フローからカスタム・コンポーネントを起動できます。