Microsoft Bot Frameworkの基本

適用対象: SDK v4

ボットとは、テキスト、グラフィックス (カード、画像など)、または音声を使用してユーザーが会話形式で対話するアプリです。 Azure Bot Service はクラウド プラットフォームです。 ボットをホストし、Microsoft Teams、Facebook、Slack などの チャネルで利用できるようにします。

Azure Bot Serviceのコンポーネントである Bot Framework Service は、ユーザーのボットに接続されたアプリとボットの間で情報を送信します。 各チャネルには、送信するアクティビティに追加情報を含めることができます。 ボットを作成する前に、ボットがアクティビティ オブジェクトを使用してそのユーザーと通信する方法を理解することが重要です。

この図は、ユーザーがエコー ボットと通信するときに交換される可能性がある、 会話の更新メッセージの 2 つのアクティビティの種類を示しています。

アクティビティの図

Bot Framework Service は、パーティーが会話に参加したときに 会話の更新を 送信します。 たとえば、Bot Framework Emulatorとの会話を開始すると、2 つの会話更新アクティビティ (会話に参加するユーザー用とボット参加用のアクティビティ) が表示される場合があります。 これらの会話更新アクティビティを区別するには、アクティビティの 追加されたメンバー プロパティに含まれているユーザーを確認します。

メッセージ アクティビティは、パーティ間で会話情報を送信します。 エコー ボットの例では、メッセージ アクティビティによって単純なテキストが伝達され、そのテキストがチャネルによってレンダリングされます。 また、メッセージ アクティビティでは、読み上げられるテキスト、推奨されるアクション、または表示されるカードが伝達される場合があります。

ヒント

Bot Framework プロトコルを実装するのは各チャネルにかかっており、各チャネルの実装方法は少し異なる可能性があります。 たとえば、一部のチャネルは会話更新アクティビティを最初に送信し、一部のチャネルは最初のメッセージ アクティビティを送信した後に会話更新アクティビティを送信します。 チャネルには、1 つの会話更新アクティビティにボットとユーザーの両方が含まれる場合があり、もう 1 つは 2 つの会話更新アクティビティを送信する場合があります。

この例では、インバウンド メッセージ アクティビティに応じるメッセージ アクティビティがボットによって作成され、送信されました。 ただし、ボットは受信したメッセージ アクティビティに対して他の方法で応答できます。ボットは、ウェルカム メッセージを含むメッセージ アクティビティを送信することで、会話更新アクティビティに応答するのが一般的です。 詳細については、ユーザーを歓迎する方法 に関するページを参照してください

The Bot Framework SDK

Bot Framework SDK を使用すると、Azure Bot Serviceでホストできるボットを構築できます。 このサービスは、ボットとチャネルまたはユーザーが対話する方法に関する REST API とアクティビティ プロトコルを定義します。 SDK は、この REST API に基づいて構築され、会話ロジックに集中できるようにサービスの抽象化を提供します。 SDK を使用するために REST サービスを理解する必要はありませんが、その機能の一部を理解すると役立ちます。

ボットは、会話インターフェイスを持つアプリです。 もう人が直接介入する必要がないような、ディナーの予約やプロファイル情報の収集などの繰り返し発生する単純なタスクを自動化されたシステムに移行するために使用できます。 ユーザーは、テキスト、インタラクティブ カード、および音声を使ってボットと会話します。 ボットとの対話では、簡単な質問と回答や、サービスへのアクセスをインテリジェントに提供する洗練された会話などが可能です。

Note

SDK と REST API によって提供される機能のサポートは、チャネルによって異なります。 Bot Framework Emulatorを使用してボットをテストできますが、ボットを使用できるようにする各チャネルでボットのすべての機能をテストする必要もあります。

相互作用には、順番に処理される アクティビティの交換が含 まれます

Activities

ユーザー (またはチャネル) とボットの間のすべての相互作用は 、アクティビティとして表されます。 Bot Framework アクティビティ スキーマ は、ユーザーまたはチャネルとボットの間で交換できるアクティビティを定義します。 アクティビティは、人間のテキストや音声、アプリ間通知、他のメッセージへの反応などを表すことができます。

ターン

人が会話するときは、通常、代わる代わる順番に話します。 ボットの場合、一般的には、ボットがユーザー入力に反応します。 Bot Framework SDK では、"ターン" は、ボットがユーザーから受信するアクティビティと、ボットが即時応答としてユーザーに送り返すアクティビティで構成されています。 ターンは、特定のアクティビティを受け取るボットに関連付けられた処理と考えることができます。

たとえば、ユーザーがボットに特定のタスクの実行を求める場合があります。 ボットは、タスクに関する詳細情報を取得するために質問で応答する場合があります。この時点で、このターンは終了します。 次のターンでは、ボットは、ボットの質問に対する回答を含む可能性のある新しいメッセージをユーザーから受信します。または、タスクを実行するための最初の要求を無視する件名または要求の変更を表している可能性があります。

ボット アプリケーションの構造

SDK は、 ボット アプリの会話推論を処理するボット クラスを定義します。 ボット クラス:

  • ユーザーの入力を認識して解釈します。
  • 入力に関する理由と関連するタスクを実行します。
  • ボットの実行内容または実行内容に関する応答を生成します。

SDK では、チャネルとの接続を処理する アダプター クラスも定義されます。 アダプター:

  • ユーザーのチャネルに対する要求を生成するための要求とメソッドを処理するためのメソッドを提供します。
  • ボットのターン ハンドラーの外部でのターン処理を含むミドルウェア パイプラインが含まれます。
  • ボットのターン ハンドラーを呼び出し、ターン ハンドラーで特に処理されないエラーをキャッチします。

さらに、ボットでは、多くの場合、各ターンの状態を取得して格納する必要があります。 状態は、 ストレージボットの状態およびプロパティ アクセサー クラスによって処理されます。 SDK は組み込みのストレージを提供しませんが、ストレージとストレージ レイヤーのいくつかの実装の抽象化を提供します。 状態の管理に関するトピックでは、これらの状態とストレージの機能について説明します。

ボットには接続性と推論要素があり、状態の抽象化

SDK では、Web 要求の送受信に特定のアプリケーション レイヤーを使用する必要はありません。 Bot Framework には、ASP.NET (C#)、restify (JavaScript)、aiohttp (Python) のテンプレートとサンプルがあります。 ただし、アプリに別のアプリケーション レイヤーを使用することもできます。

SDK を使用してボットを作成するときは、HTTP トラフィックを受信してアダプターに転送するコードを指定します。 Bot Framework には、独自のボットの開発に使用できるいくつかのテンプレートとサンプルが用意されています。

ボット ロジック

ボット オブジェクトには、ターンの会話推論またはロジックが含まれており、 ターン ハンドラーが公開されます。これは、ボット アダプターからの受信アクティビティを受け入れるメソッドです。

SDK には、ボット ロジックを管理するためのいくつかの異なるパラダイムが用意されています。

  • アクティビティ ハンドラーは、 受信アクティビティの種類とサブタイプがイベントであるイベント ドリブン モデルを提供します。 ユーザーとの短い操作が制限されているボットのアクティビティ ハンドラーを考えてみましょう。
    • アクティビティ ハンドラーを使用し、ボットが認識して反応するアクティビティの種類またはサブタイプごとにハンドラーを実装します。
    • Teams アクティビティ ハンドラーを使用して、Teams チャネルに接続できるボットを作成します。 (Teams チャネルでは、ボットがチャネル固有の動作を処理する必要があります)。
  • ダイアログ ライブラリには、ユーザーとの長時間の会話を管理するための状態ベースのモデルが用意されています。
  • 独自のボット クラスを実装し、ターンごとに処理するための独自のロジックを提供します。 例については、 ユーザー入力を収集する独自のプロンプトを作成する方法を参照してください。

ボット アダプター

アダプターには、ターンを開始するための プロセス アクティビティ メソッドがあります。

  • 要求本文 (要求ペイロード、アクティビティに変換) と要求ヘッダーを引数として受け取ります。
  • 認証ヘッダーが有効かどうかを確認します。
  • ターンの コンテキスト オブジェクトが作成されます。 コンテキスト オブジェクトには、アクティビティに関する情報が含まれます。
  • コンテキスト オブジェクトは 、そのミドルウェア パイプラインを介して送信されます。
  • 次に、コンテキスト オブジェクトをボット オブジェクトのターン ハンドラーに送信します。

アダプターも次のとおりです。

  • 応答アクティビティを書式設定して送信します。 通常、これらの応答はユーザーのメッセージですが、ユーザーのチャネルが直接使用する情報を含めることもできます。
  • メッセージの 更新やメッセージ の削除など、Bot Connector REST API によって提供される他のメソッドを 表示します
  • ターンでキャッチされないエラーまたは例外をキャッチします。

ターン コンテキスト

"ターン コンテキスト" オブジェクトは、アクティビティに関する情報 (送信者と受信者やチャネル、アクティビティの処理に必要なその他のデータなど) を提供します。 また、ターン中に、ボットの各種レイヤーの境界を越えて情報を追加することもできます。

ターン コンテキストは、SDK の中で最も重要なアブストラクションの 1 つです。 すべてのミドルウェア コンポーネントとアプリケーション ロジックに受信アクティビティを伝達するだけでなく、ミドルウェア コンポーネントとボット ロジックが送信アクティビティを送信できるメカニズムも提供します。

ミドルウェア

ミドルウェアは、他のメッセージング ミドルウェアとよく似ています。連続する一連のコンポーネントで構成され、各コンポーネントが順に実行されるため、それぞれがアクティビティで動作できます。 ミドルウェア パイプラインの最終ステージは、アプリケーションがアダプターの process activity メソッドに登録したボット クラスのターン ハンドラーへのコールバックです。 ミドルウェアは、アダプターが呼び出す オン ターン メソッドを実装します。

ターン ハンドラーはターン コンテキストを引数として受け取ります。通常、ターン ハンドラー関数内で実行されているアプリケーション ロジックは、受信アクティビティのコンテンツを処理し、応答で 1 つ以上のアクティビティを生成し、ターン コンテキストで 送信アクティビティ 関数を使用してこれらの送信アクティビティを送信します。 ターン コンテキストで "アクティビティの送信" を呼び出すと、ミドルウェア コンポーネントがアウトバウンド アクティビティで呼び出されます。 ミドルウェア コンポーネントは、ボットのターン ハンドラー関数の前後に実行されます。 実行は本質的に入れ子になり、タマネギのようなものと呼ばれることもあります。

ミドルウェアのトピックでは、ミドルウェアの詳細について説明します。

ボットの状態とストレージ

他の Web アプリと同様に、ボットは本質的にステートレスです。 ボット内の状態は、最新の Web アプリケーションと同じパラダイムに従います。Bot Framework SDK には、状態管理を容易にするストレージ レイヤーと状態管理の抽象化が用意されています。

状態の管理に関するトピックでは、これらの状態とストレージの機能について説明します。

メッセージング エンドポイントとプロビジョニング

通常、アプリケーションには、メッセージを受信する REST エンドポイントが必要です。 また、使用することを決定したプラットフォームに従って、ボットのリソースをプロビジョニングする必要もあります。

ボットの 作成 のクイックスタートに従って、単純なエコー ボットを作成してテストします。

HTTP の詳細

アクティビティは、Bot Framework サービスから HTTP POST 要求を介してボットに送信されます。 ボットは、インバウンド POST 要求に対し、200 HTTP 状態コードで応答します。 ボットからチャネルに送信されるアクティビティは、別の HTTP POST で Bot Framework サービスに送信されます。 それに対する肯定応答が 200 HTTP の状態コードで返されます。

プロトコルでは、これらの POST 要求とその受信確認の順序は指定されていません。 しかし、一般的な HTTP サービスのフレームワークに合わせるため、これらの要求は入れ子にするのが通常です。つまり、アウトバウンド HTTP 要求は、ボットからインバウンド HTTP 要求のスコープ内で行われます。 このパターンは、前の図に示されています。 2 つの異なる HTTP 接続が連続して存在するため、セキュリティ モデルには、その両方に対する手立てが必要となります。

Note

ボットは、ほとんどのチャネルで状態 200 の通話を確認するために 15 秒です。 ボットが 15 秒以内に応答しない場合は、HTTP GatewayTimeout エラー (504) が発生します。

アクティビティの処理スタック

メッセージ アクティビティの到着に焦点を当てて、前のシーケンス図を詳しく見てみましょう。

ボットによってアクティビティがどのように処理されるかを示すシーケンス図。

チャネルはユーザーのメッセージを Azure Bot Serviceに送信し、サービスはメッセージをボットのメッセージング エンドポイントに転送します。 ボットの応答は、ターンのスコープ内でユーザーに送信されます。

上の例では、ボットがメッセージ アクティビティに対して、同じテキスト メッセージが含まれた別のメッセージ アクティビティで応答しました。 処理は、HTTP POST 要求で始まります。このとき、アクティビティ情報は JSON ペイロードとして伝達されて、Web サーバーに届きます。 多くの場合、ASP.NET プロジェクトは C# ボットに使用され、JavaScript Node.js ボットには Express や restify などの一般的なフレームワークが使用されます。

"アダプター" は SDK の統合コンポーネントで、SDK ランタイムのコアです。 アクティビティは、HTTP POST 本文で JSON として渡されます。 この JSON は、プロセス アクティビティ メソッドを通じてアダプターに渡されるアクティビティ オブジェクトを作成するために逆シリアル化されます。 アクティビティを受け取ったアダプターにより、"ターン コンテキスト" が作成され、ミドルウェアが呼び出されます。

上述したように、ターン コンテキストは、アウトバウンド アクティビティを送信するメカニズムをボットに提供します。この送信処理は、多くの場合、インバウンド アクティビティに対する応答として実行されます。 ターン コンテキストは、 送信更新、および 削除アクティビティ の応答メソッドを提供します。 各応答メソッドは、非同期プロセスで実行されます。

重要

プライマリ ボット ターンを処理するスレッドは、完了時にコンテキスト オブジェクトの破棄を処理します。 いずれのアクティビティ呼び出しに対しても必ず await を実行します。これにより、プライマリ スレッドでは生成されたアクティビティで待機してから、その処理が終了され、ターン コンテキストの破棄が行われます。 そうしないと、応答 (そのハンドラーも含まれる) にかなりの時間がかかり、コンテキスト オブジェクトに基づいた処理が試みられた場合、"コンテキスト破棄済み" エラーが返されることがあります。

ボット テンプレート

アプリに使用するアプリケーション レイヤーを選択する必要があります。ただし、Bot Framework には、ASP.NET (C#)、restify (JavaScript)、および aiohttp (Python) 用のテンプレートとサンプルがあります。 このドキュメントは、これらのプラットフォームのいずれかを使用すると仮定して記述されていますが、SDK では必要ありません。 テンプレートにアクセスしてインストールする方法については、 ボットの作成 に関するクイックスタートを参照してください。

ボットは Web アプリケーションであり、SDK の言語バージョンごとにテンプレートが提供されます。 すべてのテンプレートは、既定のエンドポイント実装とアダプターを提供します。 各テンプレートには、次のものが含まれます。

  • リソースのプロビジョニング
  • 受信アクティビティをアダプターにルーティングする言語固有の HTTP エンドポイント実装。
  • アダプター オブジェクト
  • ボット オブジェクト

さまざまなテンプレートの種類の主な違いは、ボット オブジェクトにあります。 テンプレートは次のとおりです。

  • 空のボット
    • 会話の最初のターンで "hello world" メッセージを送信することで、ユーザーを会話に歓迎するアクティビティ ハンドラーが含まれます。
  • エコー ボット
    • アクティビティ ハンドラーを使用してユーザーを歓迎し、ユーザー入力をエコーバックします。
  • コア ボット
    • SDK の多くの機能をまとめ、ボットのベスト プラクティスを示します。
    • アクティビティ ハンドラーを使用してユーザーを歓迎します。
    • コンポーネント ダイアログと子ダイアログを使用して会話を管理します。
    • ダイアログでは、Language Understanding (LUIS) と QnA Maker の機能が使用されます。

Note

Azure QnA Maker は、2025 年 3 月 31 日に廃止される予定です。 2022 年 10 月 1 日から、新しい QnA Maker リソースやナレッジ ベースを作成することはできません。 新しいバージョンの質問応答機能が、Azure Cognitive Service for Language の一部として使用できるようになりました。

Azure Cognitive Service for Language の機能であるカスタムの質問への回答は、QnA Maker サービスの更新バージョンです。 Bot Framework SDK での質問と回答のサポートの詳細については、「 自然言語の理解」を参照してください。

関連情報

ボット リソースの管理

ボットのリソース (アプリ ID やパスワードなど) と、接続されているサービスの情報を管理する必要があります。 ボットをデプロイするときは、この情報への安全なアクセスが必要になります。 複雑さを回避するために、Bot Framework SDK の記事のほとんどは、この情報を管理する方法を説明していません。

チャネル アダプター

SDK では、チャネル アダプターを使用することもできます。このアダプター自体は、Bot Connector Service がチャネルに対して通常実行するタスクを追加で実行します。

SDK には、一部の言語でいくつかのチャネル アダプターが用意されています。 他のチャネル アダプターは、Botkit と Community リポジトリを通じて利用できます。 詳細については、Bot Framework SDK リポジトリの チャネルとアダプターの表を参照してください。

The Bot Connector REST API

Bot Framework SDK は、Bot Connector REST API をラップしてビルドします。 SDK をサポートする基になる HTTP 要求を理解する場合は、コネクタ 認証 と関連する記事を参照してください。 ボットが送受信するアクティビティは、 Bot Framework アクティビティ スキーマに準拠します。

次のステップ