💬

Echo Botから始めるBot Frameworkでボット開発

2021/01/11に公開

MicrosoftのBot Frameworkを使ってシンプルなEcho Bot（チャットした内容を繰り返すボット）を動かすまでの手順を紹介します。

Microsoftのドキュメントは用意されているのですが日本語がわかりにくかったりしたので、自分なりの理解でまとめてみました。
特に、開発周りの用語がいまいちわからなかったため、できるかぎり自分の言葉で説明していますが、理解が間違っているところなどありましたら、コメントください。

対象読者

これからBot Frameworkでボット開発を始める人

ゴール

Bot Frameworkとは何かわかる
Echo Botの仕組みがわかる
ボットをローカルで動かせる

環境

Mac OS X

❯ dotnet --version
5.0.101

❯ dotnet list package
   > Microsoft.Bot.Builder.Integration.AspNet.Core      4.11.1

Bot Frameworkとは

まずは、そもそもBot Frameworkとはどんなものなのかから説明します。

Bot Frameworkは、ボット開発をするためのSDKです。
現在使われているのはBot Framework SDK v4となります。

SDKに含まれているもの

Bot FrameworkはSDKなので、ボット開発に必要ないろいろな物が詰め込まれています。

以下のものが含まれています。

ボット構築のためのパッケージ
ドキュメント
ボットのテンプレートやサンプルコード
自然言語処理などのAIサービス

Bot Builder

ボットを実装するためのパッケージ（SDK）がBot Builderになります。
ボットの実装する時は、このパッケージを活用して実装していきます。

以下の言語で使うことができます。

ボットの仕組み

ここからは、ボットがどういう仕組みで動いているのかを紹介していきます。

基本的には、ASP.NET CoreのWebアプリケーションの仕組みがベースとなっています。

用語

まずはボット開発で出てくる用語をまとめます。

最初、この辺の用語の意味がよくわからず苦労しました。

アクティビティ(activity)
- ユーザとボット間でのイベントを表すもの（会話やリアクションなど）
ターン(turn)
- ボットもしくはユーザからアクティビティを送ること
ターンコンテキスト(turn context)
- アクティビティに関する情報
ダイアログ(dialog)
- 対話の一連の流れを管理するもの
ボットアダプター(bot adapter)
- アクティビティを受け取ってターンコンテキストを作成して応答を送るもの
ミドルウェア(middleware)
- アダプターとボットロジックの間で行う処理

処理の流れ

続いて、メッセージを受け取ってから、返答するまでの処理の流れについて説明します。
ここでは、Message Activityを受け取るというチャットでメッセージを受けた時の処理を具体例として使用します。

公式ドキュメントより

エンドポイントからHTTPリクエストでメッセージが送られる
Bot Framework ServiceからProcessActivityが実行される
AdapterよりTurnContextが作成されOnTurnが実行される
ボットから返信用のSendActivityを実行する
応答のメッセージが送信される

Bot Framework Serviceとは、Azure Bot Serviceのコンポーネントになります。
チャネル(LINEやslack, Teamsなど)とボットの間で情報のやりとりをします。

実装する上で主に触るのは、手順3, 4部分の処理になります。

Echo Bot

ここからは、Echo Botを作成して、実行する手順について紹介してきます。

テンプレートから作成

Echo Botについては、テンプレートが用意されているため、テンプレートから作成します。

まずは、テンプレートをインストールします。

dotnet new -i Microsoft.Bot.Framework.CSharp.EchoBot

次に、プロジェクト名を指定してEcho Botを作成します。

dotnet new echobot -n EchoBot

テンプレートのディレクトリ構造

.NETで作成されるテンプレートのファイルについて説明します。

テンプレートからEcho Botを作成すると以下のようなファイルが生成されます。

EchoBot
├── AdapterWithErrorHandler.cs # アダプターで例外を処理
├── Bots
│   └── EchoBot.cs # Botのメインロジック
├── Controllers
│   └── BotController.cs # webアプリとしてのエンドポイントを実装
├── DeploymentTemplates
├── EchoBot.csproj # プロジェクトファイル
├── Program.cs
├── Properties
├── README.md
├── Startup.cs # 必要なサービスを構成
├── appsettings.Development.json # 設定ファイル
├── appsettings.json # 設定ファイル
└── wwwroot

処理

メインロジックを実装しているEchoBot.csの処理は以下のようになります。

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

OnMessageActivityAsyncメソッドをオーバーライドすることでMessage Activityを受け付けた時の処理を記述します。
Echoボットとして、送られてきた内容をそのまま返す処理はここで実装されています。

まずは、turn contextの中から送られてきたメッセージテキストを取得して、応答メッセージを作成します。

var replyText = $"Echo: {turnContext.Activity.Text}";

次に、SendActivityAsyncメソッドを利用して、応答メッセージをMessage Activityとして送信します。

await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);

OnMembersAddedAsyncメソッドはオーバーライドすることで、ボットと初めて会話した時の処理を実装できます。
ここでは、「Hello and welcome」というメッセージを送信しています。

ローカルで動かす

最後に、作成したボットをローカルで動かしてみます。

まずは、ローカルで動かすためのツールであるBot Framework Emulatorをインストールします。

ダウンロードはこちらから

次に、ボットをローカルで実行します。

dotnet run

ローカルでボットの実行ができたら、Bot Framework Emulatorを起動して、ボットと接続します。
接続する時のURLはhttp://localhost:3978/api/messagesとなる。

ボットと接続することでローカルでのテストができるようになります。
ボットとの会話が始まると、まずはOnMembersAddedAsyncメソッドの処理が実行され、メッセージが送られてきます。

ボットにチャットメッセージを送ると、OnMessageActivityAsyncの処理が実行され、同じメッセージがボットから送られてきます。

まとめ

Bot Frameworkはボット開発のためのSDK
Messageアクティビティを受け取った処理を実装することでEchoボットが作成できる
Bot Framework Emulatorでローカルでテストが可能