JavaScript SDK v3 とv4 の違いDifferences between the v3 and v4 JavaScript SDK

適用対象: SDK v4APPLIES TO: SDK v4

Bot Framework SDK のバージョン 4 では、バージョン 3 と同じ基になる Bot Framework Service がサポートされています。Version 4 of the Bot Framework SDK supports the same underlying Bot Framework Service as version 3. ただし、v4 は、開発者がより柔軟にボットを制御できるように、以前のバージョンの SDK をリファクタリングしたものです。However, v4 is a refactoring of the previous version of the SDK to allow developers more flexibility and control over their bots. この SDK の主な変更点は次のとおりです。Major changes in the SDK include:

  • ボット アダプターの導入Introduction of a bot adapter
    • アクティビティ処理スタックに含まれていますIt is part of the activity processing stack
    • Bot Framework 認証が処理されますHandles Bot Framework authentication
    • Bot Framework Connector の呼び出しがカプセル化され、チャネルとボットのターン ハンドラー間の受信トラフィックと送信トラフィックが管理されますManages incoming and outgoing traffic between a channel and your bot's turn handler, encapsulating the calls to the Bot Framework Connector
    • ターンごとにコンテキストが初期化されますInitializes context for each turn
    • 詳細については、ボットのしくみに関する記事を参照してください。For more information, see how bots work.
  • 状態管理のリファクタリングRefactored state management
    • 状態データは、ボット内で自動的に使用できなくなりましたState data is no longer automatically available within a bot
    • 状態管理オブジェクトとプロパティ アクセサーを使用して管理されるようになりました。It is now managed via state management objects and property accessors
    • 詳細については、状態の管理に関する記事を参照してください。For more information, see managing state
  • 新しいダイアログ ライブラリA new Dialogs library
    • v3 ダイアログは、新しいダイアログ ライブラリ用に書き換える必要がありますv3 dialogs must be rewritten for the new dialog library
    • scoreable は存在しなくなりました。Scoreables no longer exist. ダイアログに制御を渡す前に、"グローバル" コマンドの有無を確認できます。You can check for "global" commands, before passing control to your dialogs. ご自身の v4 ボットの設計方法に応じて、これはメッセージ ハンドラーまたは親ダイアログに存在します。Depending on how you design your v4 bot, this could be in the message handler or a parent dialog. 例については、ユーザーによる割り込みを処理する方法を参照してください。For an example, see how to handle user interruptions.
    • 詳細については、ダイアログ ライブラリに関する記事を参照してください。For more information, see dialogs library.

アクティビティの処理Activity processing

ボットのアダプターを作成するときは、チャネルとユーザーからの受信アクティビティを受け取るメッセージ ハンドラー デリゲートも用意します。When you create the adapter for your bot, you also provide a message handler delegate that will receive incoming activities from channels and users. アダプターは、受け取ったアクティビティごとにターン コンテキスト オブジェクトを作成します。The adapter creates a turn context object for each received activity. ターン コンテキスト オブジェクトがボットのターン ハンドラーに渡され、ターンが完了するとオブジェクトは破棄されます。It passes the turn context object to the bot's turn handler, and then disposes the object when the turn completes.

ターン ハンドラーは、さまざまな種類のアクティビティを受け取ることができます。The turn handler can receive many types of activities. 一般に、ボットに含まれているダイアログには "メッセージ" アクティビティだけを転送します。In general, you will want to forward only message activities to any dialogs your bot contains. ご自身のボットを ActivityHandler から派生させると、すべてのメッセージ アクティビティがボットのターン ハンドラーによって OnMessage に転送されます。If you derive your bot from ActivityHandler, the bot's turn handler will forward all message activities to OnMessage. このメソッドをオーバーライドして、メッセージ処理ロジックを追加します。Override this method to add message handling logic. アクティビティの種類の詳細については、アクティビティ スキーマに関する記事を参照してください。For more information about activity types, see the activity schema.

ターンの処理Handling turns

メッセージを処理するときは、ターン コンテキストを使用して受信アクティビティに関する情報を取得し、アクティビティをユーザーに送信します。When handling a message, use the turn context to get information about the incoming activity and to send activities to the user:

アクティビティActivity 説明Description
受信アクティビティを取得するTo get the incoming activity ターン コンテキストの Activity プロパティを取得します。Get the turn context's Activity property.
アクティビティを作成してユーザーに送信するTo create and send an activity to the user ターン コンテキストの SendActivity メソッドを呼び出します。Call the turn context's SendActivity method.
詳細については、テキスト メッセージの送受信メッセージへのメディアの追加に関する記事を参照してください。For more information, see send and receive a text message and add media to messages.

MessageFactory クラスには、アクティビティを作成し、その形式を設定するためのヘルパー メソッドがいくつか用意されています。The MessageFactory class provides some helper methods for creating and formating activities.

割り込みInterruptions

これらはボットのメッセージ ループ内で処理します。Handle these in the bot's message loop. v4 ダイアログでこれを行う方法については、「ユーザーによる割り込みを処理する」をご覧ください。For a description of how to do this with v4 dialogs, see how to handle user interruptions.

状態管理State management

v3 では、会話データを、Bot Framework によって提供される大規模なサービス スイートの一部である Bot State Service に格納できました。In v3, you could store conversation data in the Bot State Service, part of the larger suite of services provided by the Bot Framework. ただし、このサービスは、2018 年 3 月 31 日に廃止されました。However, this service has been retired since March 31st, 2018. v4 以降、状態の管理に関する設計上の考慮事項は、Web アプリと同じで、さまざまなオプションを使用できます。Beginning with v4, the design considerations for managing state are just like any Web App and there are a number of options available. これをメモリおよび同じプロセス内にキャッシュするのが通常は最も簡単なのですが、運用環境のアプリについては、状態をより永続的に、たとえば SQL、NoSQL データベース、BLOB などに格納する必要があります。Caching it in memory and in the same process is usually the easiest; however, for production apps you should store state more permanently, such as in an SQL or NoSQL database or as blobs.

v4 では、状態を管理する際に、UserDataConversationDataPrivateConversationData の各プロパティとデータ バッグは使用されません。v4 doesn't use UserData, ConversationData, and PrivateConversationData properties and data bags to manage state. 状態は、「状態の管理」で説明する状態管理オブジェクトとプロパティ アクセサーを使用して管理されるようになりました。State is now managed via state management objects and property accessors as described in managing state.

v4 では、ボットの状態データを管理する、UserStateConversationStatePrivateConversationState の各クラスが定義されています。v4 defines UserState, ConversationState, and PrivateConversationState classes that manage state data for the bot. 定義済みのデータ バッグを単に読み書きするのではなく、保持するプロパティごとに状態プロパティ アクセサーを作成する必要があります。You need to create a state property accessor for each property you want to persist, instead of just reading and writing to a predefined data bag.

状態の設定Setting up state

状態はアプリケーションのエントリ ポイント ファイル、一般的には NodeJS アプリケーションの 'index.js' または 'app.js' で構成する必要があります。State should be configured in the application entry point file, commonly 'index.js' or 'app.js' in NodeJS applications.

  1. botbuilder-core によって提供される Storage インターフェイスを実装する 1 つ以上のオブジェクトを初期化します。Initialize one or more objects that implement the Storage interface provided by botbuilder-core. これは、ボットのデータのバッキング ストアを表します。This represents the backing store for your bot's data. v4 SDK では、ストレージ レイヤーがいくつか提供されます。The v4 SDK provides a few storage layers. 別の種類のストアに接続するために、独自のレイヤーを実装することもできます。You can also implement your own, to connect to a different type of store.
  2. 必要に応じて、状態管理オブジェクトを作成し、登録します。Then, create and register state management objects as necessary. v3 の場合と同じスコープを使用できます。また、必要に応じて、他のスコープを作成することもできます。You have the same scopes available as in v3, and you can create others if you need to.
  3. 最後に、ボットに必要なプロパティの状態プロパティ アクセサーを作成し、登録します。Finally, create and register state property accessors for the properties your bot needs. 状態管理オブジェクト内では、各プロパティ アクセサーに一意の名前が必要です。Within a state management object, each property accessor needs a unique name.

状態の使用Using state

状態プロパティ アクセサーを使用してプロパティを取得および更新し、状態管理オブジェクトを使用して変更をストレージに書き込みます。Use the state property accessors to get and update your properties, and use the state management objects to write any changes to storage. コンカレンシーの問題を考慮する必要があることを理解しているという前提で、一般的なタスクを実行する方法を次に示します。With the understanding that you should take concurrency issues into account, here is how to accomplish some common tasks.

タスクTask 説明Description
状態プロパティ アクセサーを作成するTo create a state property accessor BotState オブジェクトの createProperty メソッドを呼び出します。Call your BotState object's createProperty method.
BotState は、会話状態、個人的な会話状態、ユーザー状態を表す抽象基底クラスです。BotState is the abstract base class for conversation, private conversation, and user state.
プロパティの現在の値を取得するTo get the current value of a property StatePropertyAccessor.get(TurnContext) を呼び出します。Call StatePropertyAccessor.get(TurnContext).
以前に値が設定されていない場合は、出荷時の既定のパラメーターを使用して値が生成されます。If no value has been previously set, then it will use the default factory parameter to generate a value.
状態の変更をストレージに保持するTo persist state changes to storage ターン ハンドラーを終了する前に、状態が変わった状態管理オブジェクトに対して BotState.saveChanges(TurnContext, boolean) を呼び出します。Call BotState.saveChanges(TurnContext, boolean) for any of the state management objects in which state has changed before exiting the turn handler.

コンカレンシーを管理するManaging concurrency

ボットで状態のコンカレンシーを管理することが必要な場合があります。Your bot may need to manage state concurrency. 詳細については、「状態の管理」の「状態の保存」、および「ストレージに直接書き込む」の「eTag を使用してコンカレンシーを管理する」をご覧ください。For more information, see the saving state section of Managing state, and the manage concurrency using eTags section of Write directly to storage.

ダイアログ ライブラリDialogs library

ダイアログの主な変更点を次に示します。Here are some of the major changes to dialogs:

  • ダイアログ ライブラリは、botbuilder-dialogs という独立した npm パッケージになりました。The dialogs library is now a separate npm package: botbuilder-dialogs.
  • ダイアログの状態は、DialogState 状態クラスとプロパティ アクセサーを使用して管理されます。Dialog state is managed through a DialogState state class and property accessors.
    • ダイアログ オブジェクト自体とは異なり、ダイアログの状態プロパティはターン間で保持されるようになりました。The dialog state property is now persisted between turns, as opposed to the dialog object itself.
  • ターン内で、"ダイアログ セット" のダイアログ コンテキストを作成します。Within a turn, you create a dialog context for a dialog set.
    • このダイアログ コンテキストによってダイアログ スタックがカプセル化されます。This dialog context encapsulates the dialog stack. この情報は、ダイアログの状態プロパティ内に保持されます。This information is persisted within the dialog state property.
  • どちらのバージョンにも抽象 Dialog クラスがありますが、v3 では 'ActionSet' クラスが拡張され、v4 では 'Object' が拡張されます。Both versions contain an abstract Dialog class, however in v3 it extends the 'ActionSet' class while in v4 it extends 'Object'.

ダイアログの定義Defining dialogs

v3 では Dialog クラスを使用して柔軟にダイアログを実装できましたが、検証などの機能に対して、独自のコードを実装する必要がありました。While v3 provided a flexible way to implement dialogs using the Dialog class, it meant that you had to implement your own code for features such as validation. v4 では、現在、ユーザー入力を自動検証し、特定の型 (整数など) に制限して、有効な入力が提供されるまでユーザーに入力を求めるプロンプト クラスがあります。In v4, there are now prompt classes that will automatically validate the user input for you, constrain it to a specific type (such as an integer), and prompt the user again until they provide valid input. つまり、一般的に、開発者として書き込むコードが少なくなります。In general, this means less code to write as a developer.

ダイアログを定義する方法について、いくつかのオプションを使用できるようになりました。You have a few options for how to define dialogs now:

ダイアログの種類Dialog Type 説明Description
ComponentDialog クラスから派生したコンポーネント ダイアログA component dialog, derived from the ComponentDialog class 外部コンテキストとの名前の競合なしにダイアログ コードをカプセル化できます。Allows you to encapsulate dialog code without naming conflicts with the outer contexts. ダイアログの再利用」をご覧ください。See reuse dialogs.
WaterfallDialog クラスのインスタンスであるウォーターフォール ダイアログA waterfall dialog, an instance of the WaterfallDialog class さまざまな種類のユーザー入力を要求して検証するプロンプト ダイアログと適切に連携するように設計されています。Designed to work well with prompt dialogs, which prompt for and validate various types of user input. ウォーターフォールによりプロセスの大部分が自動化されますが、ダイアログ コードに特定の形式が適用されます。連続して行われる会話フローに関する記事を参照してください。A waterfall automates most of the process for you, but imposes a certain form to your dialog code; see sequential conversation flow.
抽象 Dialog クラスから派生したカスタム ダイアログA custom dialog, derived from the abstract Dialog class このダイアログでは、ダイアログの動作に最大限の柔軟性が得られますが、ダイアログ スタックの実装の詳細を把握している必要があります。This gives you the most flexibility in how your dialogs behave, but also requires you to know more about how the dialog stack is implemented.

ウォーターフォール ダイアログを作成するときに、コンストラクターでダイアログのステップを定義します。When you create a waterfall dialog, you define the steps of the dialog in the constructor. 実行されるステップの順序は、それを宣言した方法に厳密に従い、1 つずつ自動的に先に進みます。The order of steps executed follows exactly how you have declared it and automatically moves forward one after another.

複数のダイアログを使用して、複雑な制御フローを作成することもできます。高度な会話フローに関する記事を参照してください。You can also create complex control flows by using multiple dialogs; see advanced conversation flow.

ダイアログにアクセスするには、そのインスタンスを "ダイアログ セット" に追加し、そのセットの "ダイアログ コンテキスト" を生成する必要があります。To access a dialog, you need to put an instance of it in a dialog set and then generate a dialog context for that set. ダイアログ セットを作成するときには、ダイアログの状態プロパティ アクセサーを提供する必要があります。You need to provide a dialog state property accessor when you create a dialog set. これにより、フレームワークはターン間でダイアログの状態を保持できるようになります。This allows the framework to persist dialog state from one turn to the next. v4 で状態を管理する方法については、「状態の管理」をご覧ください。Managing state describes how state is managed in v4.

ダイアログの使用Using dialogs

v3 での一般的な操作と、ウォーターフォール ダイアログ内でそれらを実行する方法を次に示します。Here's a list of common operations in v3, and how to accomplish them within a waterfall dialog. ウォーターフォール ダイアログの各ステップでは、DialogTurnResult 値を返す必要があります。Note that each step of a waterfall dialog is expected to return a DialogTurnResult value. そうしないと、ウォーターフォールが早期に終了する可能性があります。If it doesn't, the waterfall may end early.

OperationOperation v3v3 v4v4
ダイアログの開始を処理するHandle the start of your dialog session.beginDialog を呼び出し、ダイアログの ID で渡しますcall session.beginDialog, passing in the id of the dialog DialogContext.beginDialog を呼び出しますcall DialogContext.beginDialog
アクティビティを送信するSend an activity session.send を呼び出します。Call session.send. TurnContext.sendActivity を呼び出します。Call TurnContext.sendActivity.
ステップ コンテキストの Context プロパティを使用して、ターン コンテキスト (step.context.sendActivity) を取得します。Use the step context's Context property to get the turn context (step.context.sendActivity).
ユーザーの応答を待機するWait for a user's response ウォーターフォール ステップ内からプロンプトを呼び出します (例: builder.Prompts.text(session, 'Please enter your destination'))。call a prompt from within the waterfall step, ex: builder.Prompts.text(session, 'Please enter your destination'). 次のステップで応答を取得します。Retrieve the response in the next step. プロンプト ダイアログを開始する TurnContext.prompt を待機して制御を戻します。Return await TurnContext.prompt to begin a prompt dialog. 次に、ウォーターフォールの次のステップで結果を取得します。Then retrieve the result in the next step of the waterfall.
ダイアログの継続を処理するHandle continuation of your dialog 自動Automatic ウォーターフォール ダイアログにステップを追加するか、Dialog.continueDialog を実装するAdd additional steps to a waterfall dialog, or implement Dialog.continueDialog
ユーザーの次のメッセージまで処理が終了したことを伝えるSignal the end of processing until the user's next message session.endDialog を呼び出します。Call session.endDialog. Dialog.EndOfTurn を返します。Return Dialog.EndOfTurn.
子ダイアログを開始するBegin a child dialog session.beginDialog を呼び出します。Call session.beginDialog. ステップ コンテキストの beginDialog メソッドを待機して制御を戻します。Return await the step context's beginDialog method.
子ダイアログから値が返された場合、ステップ コンテキストの Result プロパティを使用して、ウォーターフォールの次のステップでその値を使用できます。If the child dialog returns a value, that value is available in the next step of the waterfall via the step context's Result property.
現在のダイアログを新しいダイアログに置き換えるReplace the current dialog with a new dialog session.replaceDialog を呼び出します。Call session.replaceDialog. ITurnContext.replaceDialog を待機して制御を戻します。Return await ITurnContext.replaceDialog.
現在のダイアログが完了したことを通知するSignal that the current dialog has completed session.endDialog を呼び出します。Call session.endDialog. ステップ コンテキストの endDialog メソッドを待機して制御を戻します。return await the step context's endDialog method.
ダイアログを失敗にするFail out of a dialog. session.pruneDialogStack を呼び出します。Call session.pruneDialogStack. キャッチされた例外をボットの別のレベルでスローするか、Cancelled の状態でステップを終了するか、ステップまたはダイアログ コンテキストの cancelAllDialogs を呼び出します。Throw an exception to be caught at another level of the bot, end the step with a status of Cancelled, or call the step or dialog context's cancelAllDialogs.

v4 コードに関するその他の注意事項を次に示します。Other notes about the v4 code:

  • v4 のさまざまな Prompt 派生クラスでは、ユーザー プロンプトを独立した 2 ステップのダイアログとして実装します。The various Prompt derived classes in v4 implement user prompts as separate, two-step dialogs. [連続して行われる会話フローを実装する][sequential-flow]方法を参照してください。See how to [implement sequential conversation flow][sequential-flow].
  • DialogSet.createContext を使用して、現在のターンのダイアログ コンテキストを作成します。Use DialogSet.createContext to create a dialog context for the current turn.
  • ダイアログ内から、DialogContext.context プロパティを使用して現在のターン コンテキストを取得します。From within a dialog, use the DialogContext.context property to get the current turn context.
  • ウォーターフォール ステップには、DialogContext から派生した WaterfallStepContext パラメーターがあります。Waterfall steps have a WaterfallStepContext parameter, which derives from DialogContext.
  • 具象ダイアログ クラスおよびプロンプト クラスはすべて抽象 Dialog クラスから派生します。All concrete dialog and prompt classes derive from the abstract Dialog class.
  • コンポーネント ダイアログを作成するときに ID を割り当てます。You assign an ID when you create a component dialog. ダイアログ セットの各ダイアログには、そのセット内で一意の ID を割り当てる必要があります。Each dialog in a dialog set needs to be assigned an ID unique within that set.

ダイアログ間およびダイアログ内での状態の受け渡しPassing state between and within dialogs

About component and ウォーターフォールの概要 」記事の「ダイアログの 状態」セクションで は、v4でダイアログの状態を管理する方法について説明 しています。The dialog state section of the dialogs library article and the waterfall step context properties and using dialogs sections of the about component and waterfall dialogs article describe how to manage dialog state in v4.

ユーザーの応答を取得するGet user response

ターンでユーザーのアクティビティを取得するには、ターン コンテキストから取得します。To get the user's activity in a turn, get it from the turn context.

ユーザーに入力を求め、プロンプトの結果を受け取るには、次の手順に従います。To prompt the user and receive the result of a prompt:

  • ダイアログ セットに適切なプロンプト インスタンスを追加します。Add an appropriate prompt instance to your dialog set.
  • ウォーターフォール ダイアログのステップからプロンプトを呼び出します。Call the prompt from a step in a waterfall dialog.
  • 次のステップで、ステップ コンテキストの Result プロパティから結果を取得します。Retrieve the result from the step context's Result property in the following step.

その他のリソースAdditional resources

詳細と背景情報については、次のリソースを参照してください。Please, refer to the following resources for more details and background information.

トピックTopic 説明Description
JavaScript SDK v3 のボットを v4 に移行するMigrate a Javascript SDK v3 bot to v4 JavaScript v3 ボットの v4 への移植Porting v3 JavaScript bot to v4
Bot Framework の新機能What's new in Bot Framework Bot Framework と Azure Bot Service の主な機能と機能強化Bot Framework and Azure Bot Service key features and improvements
ボットのしくみHow bots work ボットの内部メカニズムThe internal mechanism of a bot
状態の管理Managing state 状態の管理を容易にすることができる抽象化Abstractions to make state management easier
ダイアログ ライブラリDialogs library 会話を管理するための中心的な概念Central concepts to manage a conversation
テキスト メッセージを送受信するSend and receive text messages ボットがユーザーと通信するための主な方法Primary way a bot communicate with users
メディアを送信するSend Media 画像、ビデオ、オーディオ、ファイルなどのメディアの添付ファイルMedia attachments, such as images, video, audio, and files
連続して行われる会話フローSequential conversation flow ボットがユーザーと対話する主な方法としての質問Questioning as the main way a bot interacts with users
ユーザーと会話データを保存するSave user and conversation data ステートレスでの会話の追跡Tracking a conversation while stateless
複雑なフローComplex Flow 複雑な会話フローを管理しますManage complex conversation flows
ダイアログの再利用Reuse Dialogs 特定のシナリオを処理する独立したダイアログを作成しますCreate independent dialogs to handle specific scenarios
割り込みInterruptions 堅牢なボットを作成するための割り込み処理Handling interruptions to create a robust bot
アクティビティ スキーマActivity Schema 人間と自動化されたソフトウェアのためのスキーマSchema for humans and automated software