ボットのしくみHow bots work

適用対象: 対象 SDK v4 対象外 SDK v3 APPLIES TO: yesSDK v4 no SDK v3

ボットとは、テキスト、グラフィックス (カード、画像など)、または音声を使用してユーザーが会話形式で対話するアプリです。A bot is an app that users interact with in a conversational way, using text, graphics (such as cards or images), or speech. ユーザーとボットとの間で行われるすべての対話では、"アクティビティ" が発生します。Every interaction between the user and the bot generates an activity. Facebook、Skype など、ボットに接続されたユーザーのアプリ ("チャネル") とボットとの間でやり取りされる情報は、Azure Bot Service のコンポーネントである Bot Framework Service によって送信されます。The Bot Framework Service, which is a component of the Azure Bot Service, sends information between the user's bot-connected app (such as Facebook, Skype, etc. which we call the channel) and the bot. それらによって送信されるアクティビティには、それぞれのチャネルによって付加的な情報が追加される場合があります。Each channel may include additional information in the activities they send. ボットを作成する前に、ユーザーと通信するためにアクティビティ オブジェクトがボットでどのように使用されているかを理解しておくことが大切です。Before creating bots, it is important to understand how a bot uses activity objects to communicate with its users. まずは、単純なエコー ボットを実行するときにやり取りされるアクティビティを見てみましょう。Let's first take a look at activities that are exchanged when we run a simple echo bot.

アクティビティの図

ここには、"会話の更新" と "メッセージ" の 2 種類のアクティビティが示されています。Two activity types illustrated here are: conversation update and message.

会話の更新は、当事者が会話に参加したときに Bot Framework サービスによって送信されます。The Bot Framework Service may send a conversation update when a party joins the conversation. たとえば、Bot Framework Emulator による会話の開始時には、(会話に参加するユーザーとボットに 1 つずつ) 会話の更新アクティビティが 2 つ生じます。For example, on starting a conversation with the Bot Framework Emulator, you will see two conversation update activities (one for the user joining the conversation and one for the bot joining). これらの会話の更新アクティビティを見分けるには、"追加されたメンバー" プロパティに、ボット以外のメンバーが含まれているかどうかを確認します。To distinguish these conversation update activities, check whether the members added property includes a member other than the bot.

メッセージ アクティビティは、当事者間の会話情報を伝達します。The message activity carries conversation information between the parties. エコー ボットの例では、メッセージ アクティビティによって単純なテキストが伝達され、そのテキストがチャネルによってレンダリングされます。In an echo bot example, the message activities are carrying simple text and the channel will render this text. また、メッセージ アクティビティでは、読み上げられるテキスト、推奨されるアクション、または表示されるカードが伝達される場合があります。Alternatively, the message activity might carry text to be spoken, suggested actions or cards to be displayed.

この例では、インバウンド メッセージ アクティビティに応じるメッセージ アクティビティがボットによって作成され、送信されました。In this example, the bot created and sent a message activity in response to the inbound message activity it had received. しかし、受信されたメッセージ アクティビティに対するボットの応答には、他にもさまざまな形態が考えられます。たとえば、会話の更新アクティビティに対し、何らかのウェルカム テキストをメッセージ アクティビティで送信することによってボットが応答することも珍しくありません。However, a bot can respond in other ways to a received message activity; it’s not uncommon for a bot to respond to a conversation update activity by sending some welcome text in a message activity. 詳細については、「新規ユーザーへのメッセージ」を参照してください。More information can be found in welcoming the user.

HTTP の詳細HTTP Details

アクティビティは、Bot Framework サービスから HTTP POST 要求を介してボットに送信されます。Activities arrive at the bot from the Bot Framework Service via an HTTP POST request. ボットは、インバウンド POST 要求に対し、200 HTTP 状態コードで応答します。The bot responds to the inbound POST request with a 200 HTTP status code. ボットからチャネルに送信されるアクティビティは、別の HTTP POST で Bot Framework サービスに送信されます。Activities sent from the bot to the channel are sent on a separate HTTP POST to the Bot Framework Service. それに対する肯定応答が 200 HTTP の状態コードで返されます。This, in turn, is acknowledged with a 200 HTTP status code.

これらの POST 要求とその肯定応答の順序は、プロトコルでは規定されていません。The protocol doesn’t specify the order in which these POST requests and their acknowledgments are made. しかし、一般的な HTTP サービスのフレームワークに合わせるため、これらの要求は入れ子にするのが通常です。つまり、アウトバウンド HTTP 要求は、ボットからインバウンド HTTP 要求のスコープ内で行われます。However, to fit with common HTTP service frameworks, typically these requests are nested, meaning that the outbound HTTP request is made from the bot within the scope of the inbound HTTP request. 上の図には、このパターンが示されています。This pattern is illustrated in the diagram above. 2 つの異なる HTTP 接続が連続して存在するため、セキュリティ モデルには、その両方に対する手立てが必要となります。Since there are two distinct HTTP connections back to back, the security model must provide for both.

注意

Bot は、ほとんどのチャネルでステータス200を使用して呼び出しを確認するのに15秒かかります。The bot has 15 seconds to acknowledge the call with a status 200 on most channels. Bot が15秒以内に応答しなかった場合は、HTTP GatewayTimeout エラー (504) が発生します。If the bot does not respond within 15 seconds, an HTTP GatewayTimeout error (504) occurs.

ターンの定義Defining a turn

人が会話するときは、通常、代わる代わる順番に話します。In a conversation, people often speak one-at-a-time, taking turns speaking. ボットの場合、一般的には、ボットがユーザー入力に反応します。With a bot, it generally reacts to user input. Bot Framework SDK では、"ターン" は、ボットがユーザーから受信するアクティビティと、ボットが即時応答としてユーザーに送り返すアクティビティで構成されています。Within the Bot Framework SDK, a turn consists of the user's incoming activity to the bot and any activity the bot sends back to the user as an immediate response. ターンは、特定のアクティビティの到着に関連付けられた処理として考えることができます。You can think of a turn as the processing associated with the arrival of a given activity.

"ターン コンテキスト" オブジェクトは、アクティビティに関する情報 (送信者と受信者やチャネル、アクティビティの処理に必要なその他のデータなど) を提供します。The turn context object provides information about the activity such as the sender and receiver, the channel, and other data needed to process the activity. また、ターン中に、ボットの各種レイヤーの境界を越えて情報を追加することもできます。It also allows for the addition of information during the turn across various layers of the bot.

ターン コンテキストは、SDK の中で最も重要なアブストラクションの 1 つです。The turn context is one of the most important abstractions in the SDK. インバウンド アクティビティをすべてのミドルウェア コンポーネントおよびアプリケーション ロジックに伝達するだけでなく、ミドルウェア コンポーネントとアプリケーション ロジックからアウトバウンド アクティビティを送信するためのメカニズムも備えています。Not only does it carry the inbound activity to all the middleware components and the application logic but it also provides the mechanism whereby the middleware components and the application logic can send outbound activities.

アクティビティの処理スタックThe activity processing stack

前の図について、メッセージ アクティビティの到着に注目し、さらに詳しく見ていきましょう。Let's drill into the previous diagram with a focus on the arrival of a message activity.

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

上の例では、ボットがメッセージ アクティビティに対して、同じテキスト メッセージが含まれた別のメッセージ アクティビティで応答しました。In the example above, the bot replied to the message activity with another message activity containing the same text message. 処理は、HTTP POST 要求で始まります。このとき、アクティビティ情報は JSON ペイロードとして伝達されて、Web サーバーに届きます。Processing starts with the HTTP POST request, with the activity information carried as a JSON payload, arriving at the web server. C# では、これは通常 ASP.NET プロジェクトになります。また、JavaScript Node.js プロジェクトでは多くの場合、これはいずれかの一般的なフレームワーク (Express、Restify など) です。In C# this will typically be an ASP.NET project, in a JavaScript Node.js project this is likely to be one of the popular frameworks such as Express or Restify.

"アダプター" は SDK の統合コンポーネントで、SDK ランタイムのコアです。The adapter, an integrated component of the SDK, is the core of the SDK runtime. アクティビティは、HTTP POST 本文で JSON として渡されます。The activity is carried as JSON in the HTTP POST body. この JSON は逆シリアル化されて Activity オブジェクトが作成され、これが "アクティビティの処理" メソッドへの呼び出しによってアダプターに渡されます。This JSON is deserialized to create the Activity object that is then handed to the adapter with a call to process activity method. アクティビティを受け取ったアダプターにより、"ターン コンテキスト" が作成され、ミドルウェアが呼び出されます。On receiving the activity, the adapter creates a turn context and calls the middleware.

上述したように、ターン コンテキストは、アウトバウンド アクティビティを送信するメカニズムをボットに提供します。この送信処理は、多くの場合、インバウンド アクティビティに対する応答として実行されます。As mentioned above, the turn context provides the mechanism for the bot to send outbound activities, most often in response to an inbound activity. これを実現するために、ターン コンテキストは、"アクティビティの送信、更新、および削除" 応答メソッドを備えています。To achieve this, the turn context provides send, update, and delete activity response methods. 各応答メソッドは、非同期プロセスで実行されます。Each response method runs in an asynchronous process.

重要

プライマリ ボット ターンが完了すると、それを処理していたスレッドによってコンテキスト オブジェクトの破棄処理が行われます。The thread handling the primary bot turn deals with disposing of the context object when it is done. いずれのアクティビティ呼び出しに対しても必ず await を実行します。これにより、プライマリ スレッドでは生成されたアクティビティで待機してから、その処理が終了され、ターン コンテキストの破棄が行われます。Be sure to await any activity calls so the primary thread will wait on the generated activity before finishing its processing and disposing of the turn context. そうしないと、応答 (そのハンドラーも含まれる) にかなりの時間がかかり、コンテキスト オブジェクトに基づいた処理が試みられた場合、"コンテキスト破棄済み" エラーが返されることがあります。Otherwise, if a response (including its handlers) takes any significant amount of time and tries to act on the context object, it may get a context was disposed error.

アクティビティ ハンドラーActivity handlers

アクティビティを受信したボットは、それを自身の "アクティビティ ハンドラー" に渡します。When the bot receives an activity, it passes it on to its activity handlers. 実際には "ターン ハンドラー" と呼ばれる基本ハンドラーが 1 つあり、Under the covers, there is one base handler called the turn handler. すべてのアクティビティがそこを介してルーティングされます。All activities get routed through there. その後、ターン ハンドラーは、受信したアクティビティの種類に関係なく、個別のアクティビティ ハンドラーを呼び出します。That turn handler then calls the individual activity handler for whatever type of activity it received.

たとえば、ボットがメッセージ アクティビティを受信すると、ターン ハンドラーはその受信アクティビティを確認して、OnMessageActivityAsync アクティビティ ハンドラーに送信します。For example, if the bot receives a message activity, the turn handler would see that incoming activity and send it to the OnMessageActivityAsync activity handler.

ご自身のボットを構築するとき、メッセージを処理し、これに応答するためのボット ロジックはこの OnMessageActivityAsync ハンドラーに格納されます。When building your bot, your bot logic for handling and responding to messages will go in this OnMessageActivityAsync handler. 同様に、会話に追加されたメンバーを処理するロジックは、会話にメンバーが追加されると必ず呼び出される OnMembersAddedAsync ハンドラーに格納されます。Likewise, your logic for handling members being added to the conversation will go in your OnMembersAddedAsync handler, which is called whenever a member is added to the conversation.

これらのハンドラーのロジックを実装するには、以下の「ボット ロジック」セクションで示すように、お使いのボットでこれらのメソッドをオーバーライドします。To implement your logic for these handlers, you will override these methods in your bot as seen in the Bot logic section below. これらのハンドラーそれぞれに基本実装はありません。このため、必要なロジックをご自身のオーバーライドに追加するだけです。For each of these handlers, there is no base implementation, so just add the logic that you want in your override.

基本ターン ハンドラーのオーバーライドが必要になる場合もあります。たとえば、ターンの最後に状態を保存するような状況です。There are certain situations where you will want to override the base turn handler, such as saving state at the end of a turn. これを行う場合は、最初に必ず await base.OnTurnAsync(turnContext, cancellationToken); を呼び出して、OnTurnAsync の基本実装がご自身の追加コードの前に実行されていることを確認します。When doing so, be sure to first call await base.OnTurnAsync(turnContext, cancellationToken); to make sure the base implementation of OnTurnAsync is run before your additional code. この実装は特に、OnMessageActivityAsync などの残りのアクティビティ ハンドラーを呼び出す役割を果たします。That base implementation is, among other things, responsible for calling the rest of the activity handlers such as OnMessageActivityAsync.

ミドルウェアMiddleware

ミドルウェアは、他のメッセージング ミドルウェアとよく似ています。連続する一連のコンポーネントで構成され、各コンポーネントが順に実行されるため、それぞれがアクティビティで動作できます。Middleware is much like any other messaging middleware, comprising a linear set of components that are each executed in order, giving each a chance to operate on the activity. ミドルウェア パイプラインの最終ステージは、アプリケーションがアダプターの process activity メソッドに登録したボット クラスのターン ハンドラーへのコールバックです。The final stage of the middleware pipeline is a callback to the turn handler on the bot class the application has registered with the adapter's process activity method. ターン ハンドラーは、通常、C# の場合は OnTurnAsync、JavaScript の場合は onTurn です。The turn handler is generally OnTurnAsync in C# and onTurn in JavaScript.

ターン ハンドラーはその引数としてターン コンテキストを受け取り、通常はターン ハンドラー関数の内部で実行されているアプリケーション ロジックによってインバウンド アクティビティの内容を処理して、1 つ以上のアクティビティを応答として生成し、ターン コンテキストの "アクティビティの送信" 関数を使用してそれらを送信します。The turn handler takes a turn context as its argument, typically the application logic running inside the turn handler function will process the inbound activity’s content and generate one or more activities in response, sending these out using the send activity function on the turn context. ターン コンテキストで "アクティビティの送信" を呼び出すと、ミドルウェア コンポーネントがアウトバウンド アクティビティで呼び出されます。Calling send activity on the turn context will cause the middleware components to be invoked on the outbound activities. ミドルウェア コンポーネントは、ボットのターン ハンドラー関数の前後で実行されます。Middleware components execute before and after the bot’s turn handler function. 実行は本質的に入れ子なっているため、マトリョーシカ人形のようであると言われることもあります。The execution is inherently nested and, as such, sometimes referred to being like a Russian Doll. ミドルウェアの詳細については、ミドルウェアに関するトピックを参照してください。For more in depth information about middleware, see the middleware topic.

ボットの構造Bot structure

以降のセクションでは、C# JavaScriptPython 用に提供されているテンプレートを使用して容易に作成できる、EchoBot の "主要部" について説明します。In the following sections, we examine key pieces of an EchoBot that you can easily create using the templates provided for CSharp or JavaScript or Python.

ボットは Web アプリケーションであり、各言語用のテンプレートが用意されています。A bot is a web application, and templates are provided for each language.

注意

.NET Core 2.1 と .NET Core 3.1 の両方のバージョンの C# VSIXテンプレートは、Visual Studio で使用できます。Both .NET Core 2.1 and .NET Core 3.1 versions of the C# VSIX templates are available in Visual Studio. Visual Studio 2019 で新しいボットを作成するときは、.NET Core 3.1 テンプレートを使用する必要があります。When creating new bots in Visual Studio 2019, you should use the .NET Core 3.1 templates. 現在のボット サンプルでは .NET Core 3.1 テンプレートを使用しています。The current bot samples use .NET Core 3.1 templates. .NET Core 2.1 テンプレートを使用するサンプルは、BotBuilder-Samples リポジトリの 4.7-archive ブランチにあります。You can find the samples that use .NET Core 2.1 templates in the 4.7-archive branch of the BotBuilder-Samples repository. .NET Core 3.1 ボットを Azure にデプロイする方法については、「ボットをデプロイする」を参照してください。For information about deploying .NET Core 3.1 bots to Azure, see Deploy your bot.

VSIX テンプレートによって生成されるのは ASP.NET MVC Core Web アプリです。The VSIX template generates a ASP.NET MVC Core web app. ASP.NET の基礎に関する記事を見ると、Program.csStartup.cs などのファイルにあるのと同様のコードが確認できます。If you look at the ASP.NET fundamentals, you'll see similar code in files such as Program.cs and Startup.cs. これらのファイルはすべての Web アプリに必須で、ボット固有のものではありません。These files are required for all web apps and are not bot specific.

appsettings.json ファイルappsettings.json file

appsettings.json ファイルでは、アプリ ID、パスワードなど、お使いのボットの構成情報が指定されます。The appsettings.json file specifies the configuration information for your bot, such as the app ID, and password among other things. 特定のテクノロジを使用している場合、または運用環境でこのボットを使用している場合は、ご自身の特定のキーまたは URL をこの構成に追加する必要があります。If using certain technologies or using this bot in production, you will need to add your specific keys or URL to this configuration. ただし、このエコー ボットについては、今のところ、ここでは何も行う必要はありません。アプリ ID およびパスワードは、現時点では未定義のままにしておくことができます。For this Echo bot, however, you don't need to do anything here right now; the app ID and password may be left undefined at this time.

ボット ロジックBot logic

ボット ロジックは 1 つ以上のチャネルからの受信アクティビティを処理し、応答の送信アクティビティを生成します。The bot logic processes incoming activities from one or more channels and generates outgoing activities in response.

主なボット ロジックはボット コードで定義され、ここでは Bots/EchoBot.cs と呼ばれます。The main bot logic is defined in the bot code, here called Bots/EchoBot.cs. EchoBotActivityHandler から派生し、これは IBot インターフェイスから派生しています。EchoBot derives from ActivityHandler, which in turn derives from the IBot interface. ActivityHandler ではさまざまなハンドラーがさまざまな種類のアクティビティに対して定義されます。たとえば、ここでは OnMessageActivityAsync および OnMembersAddedAsync の 2 つが定義されます。ActivityHandler defines various handlers for different types of activities, such as the two defined here: OnMessageActivityAsync, and OnMembersAddedAsync. これらのメソッドは保護されていますが、ActivityHandler から派生しているため、上書きできます。These methods are protected, but can be overwritten since we're deriving from ActivityHandler.

ActivityHandler で定義されているハンドラーを次に示します。The handlers defined in ActivityHandler are:

EventEvent HandlerHandler 説明Description
任意のアクティビティの種類を受信したAny activity type received OnTurnAsync 受信したアクティビティの種類に基づいて、他のハンドラーのいずれかを呼び出します。Calls one of the other handlers, based on the type of activity received.
メッセージ アクティビティを受信したMessage activity received OnMessageActivityAsync これをオーバーライドして message アクティビティを処理します。Override this to handle a message activity.
会話の更新アクティビティを受信したConversation update activity received OnConversationUpdateActivityAsync conversationUpdate アクティビティで、ボット以外のメンバーが会話に参加した場合、または会話から退出した場合にハンドラーを呼び出します。On a conversationUpdate activity, calls a handler if members other than the bot joined or left the conversation.
ボットではないメンバーが会話に参加したNon-bot members joined the conversation OnMembersAddedAsync これをオーバーライドして、会話に参加するメンバーを処理します。Override this to handle members joining a conversation.
ボットではないメンバーが会話から退出したNon-bot members left the conversation OnMembersRemovedAsync これをオーバーライドして、会話から退出メンバーを処理します。Override this to handle members leaving a conversation.
イベント アクティビティを受信したEvent activity received OnEventActivityAsync event アクティビティで、イベントの種類に固有のハンドラーを呼び出します。On an event activity, calls a handler specific to the event type.
Token-response イベント アクティビティを受信したToken-response event activity received OnTokenResponseEventAsync これをオーバーライドして、トークン応答イベントを処理します。Override this to handle token response events.
Non-token-response イベント アクティビティを受信したNon-token-response event activity received OnEventAsync これをオーバーライドして、その他の種類のイベントを処理します。Override this to handle other types of events.
メッセージの反応アクティビティを受信したMessage reaction activity received OnMessageReactionActivityAsync messageReaction アクティビティで、メッセージに対して 1 つ以上の反応が追加または削除された場合にハンドラーを呼び出します。On a messageReaction activity, calls a handler if one or more reactions were added or removed from a message.
メッセージの反応がメッセージに追加されたMessage reactions added to a message OnReactionsAddedAsync これをオーバーライドして、メッセージに追加された反応を処理します。Override this to handle reactions added to a message.
メッセージの反応がメッセージから削除されたMessage reactions removed from a message OnReactionsRemovedAsync これをオーバーライドして、メッセージから削除された反応を処理します。Override this to handle reactions removed from a message.
他のアクティビティの種類を受信したOther activity type received OnUnrecognizedActivityTypeAsync これをオーバーライドして、他の方法では処理されない任意のアクティビティの種類を処理します。Override this to handle any activity type otherwise unhandled.

このような各種ハンドラーにインバウンド アクティビティに関する情報を提供する turnContext があり、これはインバウンド HTTP 要求に対応しています。These different handlers have a turnContext that provides information about the incoming activity, which corresponds to the inbound HTTP request. アクティビティの種類もさまざまであるため、各ハンドラーが、そのターン コンテキスト パラメーターで厳密に型指定されたアクティビティを提供します。ほとんどの場合、OnMessageActivityAsync は常に処理され通常は最も一般的です。Activities can be of various types, so each handler provides a strongly-typed activity in its turn context parameter; in most cases, OnMessageActivityAsync will always be handled, and is generally the most common.

このフレームワークの以前の 4.x バージョンでは、パブリック メソッド OnTurnAsync を実装するオプションもあります。As in previous 4.x versions of this framework, there is also the option to implement the public method OnTurnAsync. 現在、このメソッドの基本実装はエラー チェックを処理し、各受信アクティビティの種類に応じて、特定のハンドラー (たとえば、このサンプルでは定義する 2 つのハンドラー) をそれぞれ呼び出します。Currently, the base implementation of this method handles error checking and then calls each of the specific handlers (like the two we define in this sample) depending on the type of incoming activity. ほとんどの場合、このメソッドはそのままにして、個別のハンドラーを使用できますが、OnTurnAsync のカスタム実装が必要な場合でも、これは引き続き使用できます。In most cases, you can leave that method alone and use the individual handlers, but if your situation requires a custom implementation of OnTurnAsync, it is still an option.

重要

OnTurnAsync メソッドをオーバーライドする場合は、base.OnTurnAsync を呼び出して、他のすべての On<activity>Async ハンドラーを呼び出すための基本実装を取得するか、ご自身でこれらのハンドラーを呼び出す必要があります。If you do override the OnTurnAsync method, you'll need to call base.OnTurnAsync to get the base implementation to call all the other On<activity>Async handlers or call those handlers yourself. それ以外の場合、これらのハンドラーは呼び出されず、そのコードは実行されません。Otherwise, those handlers won't be called and that code won't be run.

このサンプルでは、新しいユーザーを歓迎するか、SendActivityAsync 呼び出しを使用してユーザーが送信したメッセージをエコー バックします。In this sample, we welcome a new user or echo back the message the user sent using the SendActivityAsync call. アウトバウンド アクティビティは、アウトバウンド HTTP POST 要求に対応します。The outbound activity corresponds to the outbound HTTP POST request.

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

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        foreach (var member in membersAdded)
        {
            await turnContext.SendActivityAsync(MessageFactory.Text($"welcome {member.Name}"), cancellationToken);
        }
    }
}

アプリからボットへのアクセスAccess the bot from your app

サービスのセットアップSet up services

Startup.cs ファイルの ConfigureServices メソッドは、接続済みサービス、appsettings.json または Azure Key Vault (存在する場合) のキー、接続状態などを読み込みます。The ConfigureServices method in the Startup.cs file loads the connected services, as well as their keys from appsettings.json or Azure Key Vault (if there are any), connects state, and so on. ここでは、MVC を追加し、サービスで互換性バージョンを設定した後、ボット コントローラーへの依存関係の挿入を使用して、アダプターとボットを使用できるように設定します。Here, we're adding MVC and setting the compatibility version on our services, then setting up the adapter and bot to be available through dependency injection to the bot controller.

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    // Create the credential provider to be used with the Bot Framework Adapter.
    services.AddSingleton<ICredentialProvider, ConfigurationCredentialProvider>();

    // Create the Bot Framework Adapter.
    services.AddSingleton<IBotFrameworkHttpAdapter, BotFrameworkHttpAdapter>();

    // Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
    services.AddTransient<IBot, EchoBot>();
}

Configure メソッドでご自身のアプリの構成を完了するには、そのアプリによって MVC とその他のいくつかのファイルが使用されることを指定します。The Configure method finishes the configuration of your app by specifying that the app use MVC and a few other files. Bot Framework を使用するすべてのボットに、その構成呼び出しが必要ですが、これはご自身のボットをビルドするときに、サンプルまたは VSIX テンプレートで定義されます。All bots using the Bot Framework will need that configuration call, however that will already be defined in samples or the VSIX template when you build your bot. ConfigureServicesConfigure は、アプリの起動時にランタイムによって呼び出されます。ConfigureServices and Configure are called by the runtime when the app starts.

ボット コントローラーBot Controller

標準の MVC 構造に従っているコントローラーを使用すると、メッセージおよび HTTP POST 要求のルーティングを決定できます。The controller, following the standard MVC structure, lets you determine the routing of messages and HTTP POST requests. このボットの場合、前の「アクティビティの処理スタック」セクションで説明したように、受信要求をアダプターの process async activity メソッドに渡します。For our bot, we pass the incoming request on to the adapter's process async activity method as explained in the activity processing stack section above. その呼び出しで、ボットと、必要になる可能性がある他の認証情報を指定します。In that call, we specify the bot and any other authorization information that may be required.

コントローラーは ControllerBase を実装し、Startup.cs で設定したアダプターとボットを保持して (ここでは依存関係の挿入を使用可能)、ボットが受信 HTTP POST を受信したときに、必要な情報をそのボットに渡します。The controller implements ControllerBase, holds the adapter and bot that we set in Startup.cs (that are available here through dependency injection), and passes the necessary information on to the bot when it receives an incoming HTTP POST.

ここでは、クラスはルートおよびコントローラー属性によって実行されます。Here, you'll see the class proceeded by route and controller attributes. これらはフレームワークがメッセージを適切にルーティングし、どのコントローラーを使用するかを認識するうえで役に立ちます。These assist the framework to route the messages appropriately and know which controller to use. ルート属性の値を変更すると、エンドポイント、エミュレーター、または他のチャネルによって使用されるその変更は、ご自身のボットにアクセスします。If you change the value in the route attribute, that changes the endpoint the emulator or other channels use access your bot.

// This ASP Controller is created to handle a request. Dependency Injection will provide the Adapter and IBot
// implementation at runtime. Multiple different IBot implementations running at different endpoints can be
// achieved by specifying a more specific type for the bot constructor argument.
[Route("api/messages")]
[ApiController]
public class BotController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter Adapter;
    private readonly IBot Bot;

    public BotController(IBotFrameworkHttpAdapter adapter, IBot bot)
    {
        Adapter = adapter;
        Bot = bot;
    }

    [HttpPost]
    public async Task PostAsync()
    {
        // Delegate the processing of the HTTP POST to the adapter.
        // The adapter will invoke the bot.
        await Adapter.ProcessAsync(Request, Response, Bot);
    }
}

ボット リソースの管理Manage bot resources

アプリ ID、パスワード、キーまたはシークレットなどのボット リソースは、適切に管理する必要があります。The bot resources, such as app ID, passwords, keys or secrets for connected services, will need to be managed appropriately. これを行う方法の詳細について、「ボットのリソースを管理」を参照してください。For more on how to do so, see Manage bot resources.

その他のリソースAdditional resources