スキル コンシューマーについて

  • [アーティクル]

この記事の対象: SDK v4

"スキル コンシューマー" は、1 つ以上のスキルを呼び出すことができるボットです。 スキルに関しては、"ルート ボット" がユーザー向けボットとスキル コンシューマーを兼ねています。

ユーザーにとってルート ボットは、対話の相手であるボットです。 スキルにとってスキル コンシューマーは、ユーザーとの通信に使用するチャネルです。 (詳細については、「スキルの概要」をご覧ください。)

スキル コンシューマーでもあるルート ボットには、スキルとの間のトラフィックを管理するためのロジックが追加されています。

  • ルートが使用する各スキルの構成情報。
  • ルートがユーザーとの会話とスキルとの会話を切り替えるために使用する 会話 ID ファクトリ。
  • アクティビティをパッケージ化してスキル ボットに転送する "スキル クライアント"。
  • スキル ボットからアクティビティを受信してアンパックする "スキル ハンドラー"。

スキルの管理

1 つのスキルの開始から実行、完了までは、スキル コンシューマーに追加されたいくつかの機能で管理されます。 複数のスキルや会話スレッドを使用する、より複雑なシナリオもあり得ます。

スキル コンシューマーは、少なくとも 2 つの HTTP エンドポイントを実装します。

  • メッセージング エンドポイントは、ユーザーまたはチャネルからアクティビティを受信します。 これは、すべてのボットが実装する通常のメッセージング エンドポイントです。
  • スキルからアクティビティを受信するためのスキル ホスト エンドポイント。 これは、スキルが応答する先のサービス URL であるコールバック URL として機能します。 (スキル コンシューマーでは、スキルからの HTTP メソッド要求を受信するコードと、スキル ハンドラーを組み合わせる必要があります。)

スキルの説明

スキルごとに、"Bot Framework スキル" オブジェクトをスキル コンシューマーの構成ファイルに追加します。 それぞれに、そのスキルの ID、アプリ ID、およびエンドポイントを指定します。

プロパティ 説明
ID スキルの ID またはキー (スキル コンシューマーに固有)。
App ID スキルが Azure に登録されたときにボット リソースに割り当てられた appId。
Skill endpoint スキルのメッセージング エンドポイント。 コンシューマーがスキルとの通信に使用する URL です。

スキル クライアントとスキル ハンドラー

スキル コンシューマーは、スキル クライアントを使用してアクティビティをスキルに送信します。 クライアントは次のことを行います。

  • ユーザーのアクティビティまたはコンシューマーによって生成されたアクティビティを取得し、スキルに送信します。
  • スキルに送信されたアクティビティのサービス URL を、コンシューマーのスキル ホスト エンドポイントに設定します。
  • 元の会話リファレンスをコンシューマー/スキル間の会話リファレンスで置換します。
  • ボット間認証トークンを追加します。
  • 更新されたアクティビティをスキルに送信します。

スキル コンシューマーは、スキル ハンドラーを使用してスキルからアクティビティを受信します。 ハンドラーは次のことを行います。

  • チャネル サービスの REST API メソッドを処理します。
  • 認証と要求検証を実施します。
  • 元の会話の参照を取得します。
  • コンシューマーのアダプターに対してアクティビティを生成します。 このアクティビティは、スキルが完了したことを通知するか、またはユーザーに転送されます。

スキルを直接管理する

アクティブなスキルを追跡するには、スキル コンシューマーにロジックを追加する必要があります。 スキルの一般的な管理方法、複数のアクティブなスキルを並行して維持できるかどうかなどは、コンシューマー次第です。 検討の対象となるシナリオは次のとおりです。

  • コンシューマー/スキル間の会話を新規に開始する。 (特定のコンシューマーとユーザー間の会話に関連付けられます。)
    • スキルにパラメーターを渡すには、初期アクティビティの value プロパティをそのスキルに設定します。
  • 既存のコンシューマ/スキル間の会話を続行する。
  • スキルからの endOfConversation アクティビティを、コンシューマー/スキル間の会話終了の通知として認識する。
    • スキルからの戻り値を取得するには、アクティビティの value プロパティを確認します。
    • スキルが終了する理由を確認するには、アクティビティの code パラメーターを確認します (スキルでエラーが発生したことを示している可能性があります)。
  • endOfConversation アクティビティをスキルに送信して、コンシューマーからスキルをキャンセルする。

スキルを直接管理するコンシューマーのためにスキル コンシューマーを実装する方法を参照してください。

スキル ダイアログを使用してスキルを管理する

ダイアログ ライブラリを使用している場合は、スキル ダイアログ を使用してスキルを管理できます。 スキル ダイアログはアクティブなダイアログである間、関連付けられているスキルにアクティビティを転送します。

  • スキル ダイアログを作成するときに、dialog options パラメーターを使用して、ダイアログでスキルを管理するために必要なすべての情報 (コンシューマーのアプリ ID とコールバック URL、使用する会話 ID ファクトリ、スキルのプロパティなど) を指定します。
    • 複数のスキルをダイアログとして管理する場合は、スキルごとに個別のスキル ダイアログを作成する必要があります。
    • 多くの場合、コンポーネント ダイアログにスキル ダイアログを追加します。
  • スキル ダイアログを開始するには、ダイアログ コンテキストの begin メソッドを使用して、スキル ダイアログの ID を指定します。 options パラメーターを使用して、コンシューマーが最初のアクティビティとしてスキルに送信するアクティビティを指定します。
  • 他のダイアログの場合と同じように、スキル ダイアログを取り消したり、中断したりできます。 例については、ユーザーによる割り込みを処理する方法を参照してください。

ダイアログを使用してスキルを管理するコンシューマーについては、ダイアログを使用してスキルを使用する方法に関するページを参照してください。

予想される応答の配信モードを使用する

ボットとスキルは、HTTPS 経由で業界標準の REST と JSON を通信に使用します。 通常のアクティビティ処理フローは、ルート ボットがメッセージング エンドポイントでチャネルからのポストを受信したときに開始されます。 その後、ルート ボットはアクティビティを処理のためにスキルに送信します。 スキルからの応答は、メッセージング エンドポイントではなく、ルート ボットの スキル ホスト エンドポイントにポスト バックされます。 最後に、ルート ボットによって応答がさらに処理されるか、チャネルにポスト バックされます。 この通常のフローは、スキルに送信されるアクティビティの配信モードを変更することで変更できます。 配信モードが "ExpectReplies" に設定されている場合、スキルはスキル ホスト エンドポイントにポスト バックされません。 その代わりに、すべての応答アクティビティが応答の本文にシリアル化されます。 その後、ルート ボットはこれらのアクティビティを反復処理し、スキル ホスト エンドポイントによる処理方法と同様に処理します。

詳細については、アクティビティの仕様で「Delivery mode」を参照してください。