スキルの概要Skills overview

適用対象: SDK v4APPLIES TO: SDK v4

Bot Framework SDK のバージョン 4.7 以降では、別のボット (スキル) を使用してボットを拡張することができます。Starting with version 4.7 of the Bot Framework SDK, you can extend a bot using another bot (a skill). スキルは、他のさまざまなボットで使用されて再利用を促進します。これにより、ユーザー向けに作成したボットを、独自のスキルやサードパーティのスキルを使用して拡張できます。A skill can be consumed by various other bots, facilitating reuse, and in this way, you can create a user-facing bot and extend it by consuming your own or 3rd party skills.

  • "スキル" は、別のボットに対して一連のタスクを実行できるボットです。A skill is a bot that can perform a set of tasks for another bot. 1 つのボットは、スキルでもユーザー向けボットでもあります。A bot can be both a skill and a user-facing bot.
  • "スキル コンシューマー" は、1 つ以上のスキルを呼び出すことができるボットです。A skill consumer is a bot that can call one or more skills. ユーザー向けスキル コンシューマーは、"ルート ボット" とも呼ばれます。A user-facing skill consumer is also called a root bot.
  • "スキル マニフェスト" は、スキルが実行できるアクション、その入力と出力パラメーター、およびスキルのエンドポイントが記述された JSON ファイルです。A skill manifest is a JSON file that describes the actions the skill can perform, its input and output parameters, and the skill's endpoints.

つまり、ユーザーはルート ボットと直接対話し、ルート ボットはその会話ロジックの一部をスキルに委任します。In other words, the user interacts directly with the root bot, and the root bot delegates some of its conversational logic to a skill.

スキル機能は次のように設計されています。The skills feature is designed so that:

  • スキルとコンシューマーは、ボット フレームワークのプロトコルを使用して HTTP で通信します。Skills and consumers communicate over HTTP using the bot framework protocol.
  • スキル コンシューマーは複数のスキルを使用できます。A skill consumer can consume multiple skills.
  • スキル コンシューマーは、スキルの実装に使用された言語とは関係なくスキルを使用できます。A skill consumer can consume a skill regardless of the language used to implement the skill. たとえば C# ボットは、Python を使用して実装されたスキルを使用できます。For example, a C# bot can consume a skill implemented using Python.
  • スキルは、スキル コンシューマーになり、その他のスキルを呼び出すこともできます。A skill can also be a skill consumer and call other skills.
  • スキルはユーザー認証をサポートしますが、ユーザー認証はスキルでローカルに行われ、別のボットに転送することはできません。Skills support user authentication; however, user authentication is local to the skill and cannot be transferred to another bot.
  • スキルは、Bot Framework アダプターとカスタム アダプターの両方と連携できます。Skills can work with both the Bot Framework adapter and custom adapters.

この図は、考えられる順列の一部を示しています。This diagram shows some of the possible permutations.

ブロック図

概念のアーキテクチャConceptual architecture

スキルとスキル コンシューマーは別々のボットであり、ユーザーはそれらを個別に公開します。A skill and skill consumer are separate bots, and you publish them independently.

  • スキルを消費するには、スキルを管理するためのロジックを追加する必要があります (スキルの呼び出しや取り消しなど)。A skill consumer requires added logic for managing a skill, such as when to call or cancel the skill, and so on. コンシューマーには、通常のボット オブジェクトとアダプター オブジェクトに加えて、アクティビティをスキルとやり取りするために使用されるスキル関連オブジェクトがいくつか含まれています。In addition to the usual bot and adapter objects, the consumer includes a few skill-related objects, used to exchange activities with the skill. スキルコンシューマーは、少なくとも2つの HTTP エンドポイントを実装します。A skill consumer implements at least two HTTP endpoints:
    • メッセージングエンドポイント は、ユーザーまたはチャネルからアクティビティを受け取ります。A messaging endpoint receives activities from the user or channel. これは、すべてのボットが実装する通常のメッセージングエンドポイントです。This is the usual messaging endpoint that all bots implement.
    • スキルからアクティビティを受け取るための スキルホストエンドポイントA skill host endpoint for receiving activities from a skill. これは、コールバック URL として機能します。これは、スキルが応答するサービス URL です。This acts as a callback URL, the service URL to which the skill replies. (スキルのコンシューマーは、技術からの HTTP メソッド要求を受け取るコードとスキルハンドラーを組み合わせる必要があります)。(The skill consumer needs to pair code that receives the HTTP method request from the skill with a skill handler.)
  • スキルを利用するには、完了時にアクティビティを送信するロジックを追加する必要があり endOfConversation ます。これにより、スキルの消費者は、そのスキルへの活動の転送を停止するタイミングを知ることができます。A skill requires added logic to send an endOfConversation activity when it completes, so that the skill consumer knows when to stop forwarding activities to the skill.

次の図は、ユーザーから送信されたアクティビティがルート ボットを経由してスキルに到達し、再びユーザーに戻るまでのフローを示しています。This diagram outlines the flow of activities from the user to the root bot to a skill and back again.

アーキテクチャの図

  1. ルート ボットのアダプターは、ユーザーからアクティビティを受信して、ルート ボットのアクティビティ ハンドラーに転送します。The root bot's adapter receives activities from the user and forwards them to the root bot's activity handler. (ユーザーからのアクティビティは、ルートボットのメッセージングエンドポイントで受信されます)。(Activities from the user are received at the root bot's messaging endpoint.)
  2. ルート ボットは、スキル HTTP クライアントを使用してアクティビティをスキルに送信します。The root bot uses a skill HTTP client to send an activity to the skill. クライアントは、スキル定義とスキルメッセージ交換 ID ファクトリから、コンシューマースキルのメッセージ交換情報を取得します。The client gets the consumer-skill conversation information from a skill definition and a skill conversation ID factory. これには、スキルがアクティビティへの応答に使用するサービス URL が含まれます。This includes the service URL that the skill will use to reply to the activity.
  3. スキルのアダプターは、スキル コンシューマーからアクティビティを受信して、スキルのアクティビティ ハンドラーに転送します。The skill's adapter receives activities from the skill consumer and forwards them to the skill's activity handler. (コンシューマーからのアクティビティは、スキルボットのメッセージングエンドポイントで受信されます)。(Activities from the consumer are received at the skill bot's messaging endpoint.)
  4. スキルが応答すると、ルート ボットのスキル ハンドラーはアクティビティを受信します。When the skill responds, the root bot's skill handler receives the activity. さらに、スキル会話 ID ファクトリからルート/ユーザー間の会話の情報を取得します。It gets the root-user conversation information from the skill conversation ID factory. その後に、アクティビティをルート ボットのアダプターに転送します。It then forwards the activity to the root bot's adapter. (スキルからのアクティビティは、ルート bot のスキルホストエンドポイントで受信されます)。(Activities from the skill are received at the root bot's skill host endpoint.)
  5. ルート ボットのアダプターは、内部でプロアクティブ メッセージを生成して、ユーザーとの会話を再開します。The root bot's adapter internally generates a proactive message to resume the conversation with the user.
  6. ルート ボットのアダプターは、スキルからのメッセージをすべてユーザーに送信します。The root bot's adapter sends any messages from the skill to the user.

スキルの管理とスキル トラフィックのルーティングには、次のオブジェクトを利用します。These objects help manage skills and route skill traffic:

  • "Bot Framework スキル" は、スキルのルーティング情報を記述したもので、スキル コンシューマーの構成ファイルから読み取られます。A Bot Framework skill describes routing information for a skill and can be read from the skill consumer's configuration file.
  • "スキル HTTP クライアント" は、スキルにアクティビティを送信します。A skill HTTP client sends activities to a skill.
  • "スキル ハンドラー" は、スキルからアクティビティを受信します。A skill handler receives activities from a skill.
  • "スキル会話 ID ファクトリ" は、ユーザー/ルート間の会話リファレンスとルート/スキル間の会話リファレンスの間で変換を行います。The skill conversation ID factory translates between the user-root conversation reference and the root-skill conversation reference.
  • Bot Connector サービスは、チャネルとボット間認証の両方を提供します。The Bot Connector service provides both channel and bot-to-bot authentication. 認証構成 オブジェクトを使用すると、要求の検証をスキルまたはスキルのコンシューマーに追加して、アクセス権を持つアプリケーションまたはユーザーを制限できます。Using an authentication configuration object, you can add claims validation to a skill or skill consumer to limit which applications or users have access.

スキル クライアントとスキル ハンドラーの両オブジェクトは、"会話 ID ファクトリ" を使用して、ルート ボットがユーザーとの対話に使用する会話と、ルート ボットがスキルとの対話に使用する会話の間で変換を行います。The skill client and skill handler objects both use the conversation ID factory to translate between the conversation the root bot uses to interact with the user and the conversation the root bot uses to interact with the skill.

ボット間通信Bot-to-bot communication

設計するボットの種類に関係なく、この設計の一定の側面を理解しておくことが重要です。It's important to understand certain aspects of this design, independent of which bot you're designing.

会話リファレンスConversation references

ユーザー/ルート間の会話とルート/スキル間の会話は異なります。The user-root conversation is different than the root-skill conversation.

"会話 ID ファクトリ" は、スキル コンシューマーとスキルの間のトラフィックの管理を支援します。The conversation ID factory helps to manage traffic between a skill consumer and a skill. このファクトリは、ルート/ユーザー間の会話 ID とルート/スキル間の会話 ID の間で変換を行います。The factory translates between the ID of the conversation the root has with the user and the one it has with the skill. つまり、ルートとスキルの間で使用される会話 ID を生成し、その ID から元のユーザー/ルート間の会話 ID を復旧します。In other words, it generates a conversation ID for use between the root and the skill, and recovers the original user-root conversation ID from the root-skill conversation ID.

サーバー間の調整Cross-server coordination

ルートとスキル ボットは HTTP を介して通信します。The root and skill bots communicate over HTTP. そのため、スキルからアクティビティを受信するルート ボットのインスタンスと、開始アクティビティを送信したインスタンスが同じでない場合があります。つまり、これら 2 つの要求は、異なるサーバーで処理される可能性があります。So, the instance of the root bot that receives an activity from a skill may not be the same instance that sent the initiating activity; in other words, different servers may handle these two requests.

  • アクティビティをスキルに転送する前に、必ずスキル コンシューマーで状態を保存してください。Always save state in the skill consumer before forwarding an activity to a skill. これにより、スキルからトラフィックを受信するインスタンスは、スキルを呼び出す前に、前のインスタンスが中断したところから処理を再開できます。This ensures that the instance that receives traffic from a skill can pick up where the previous instance left off before it called the skill.
  • スキル ハンドラーは、スキルからアクティビティを受信すると、それをスキル コンシューマーに適した形式に変換し、コンシューマーのアダプターに転送します。When the skill handler receives an activity from a skill, it translates it into a form appropriate for the skill consumer, and forwards it to the consumer's adapter.

スキル コンシューマーとスキルの状態Skill consumer and skill state

スキル コンシューマーとスキルは、それぞれの状態を別々に管理します。The skill consumer and skill manage their own state separately. ただしコンシューマーでは、スキルとの通信に使用する会話 ID が作成されます。However, the consumer creates the conversation ID that it uses to communicate with the skill. これがスキルの会話状態に影響することがあります。This can have an effect on conversation state in the skill.

重要

既に説明したように、スキル コンシューマーがユーザー アクティビティをスキルに委任した場合に、そのコンシューマーの別のインスタンスがスキルの応答を受信することがあります。As noted previously, when the skill consumer delegates a user activity to a skill, a different instance of the consumer may receive the skill response. コンシューマーは、アクティビティをスキルに転送する直前に、会話状態を保存する必要があります。The consumer should always save conversation state immediately before forwarding an activity to a skill.

ボット間認証Bot-to-bot authentication

バージョン4.11 以降では、アプリ ID とパスワードを使用して、エミュレーターでスキルとスキルのコンシューマーをローカルにテストする必要はありません。Starting with version 4.11, you do not need an app ID and password to test a skill and skill consumer locally in the Emulator. Azure にスキルをデプロイするには、Azure サブスクリプションが必要です。An Azure subscription is still required to deploy your skill to Azure.

サービス レベルの認証は、Bot Connector サービスで管理されます。Service-level authentication is managed by the Bot Connector service. このフレームワークでは、ベアラー トークンとボット アプリケーション ID を使用して各ボットの ID が検証されます。The framework uses bearer tokens and bot application IDs to verify the identity of each bot. (Bot Framework は、 認証構成 オブジェクトを使用して、受信要求の認証ヘッダーを検証します)。(The Bot Framework uses an authentication configuration object to validate the authentication header on incoming requests.)

重要

そのためには、デプロイされたすべてのボット (スキルの消費者とそれが使用するすべてのスキル) が有効なアプリケーション資格情報を持っている必要があります。This requires all deployed bots (the skill consumer and any skills it consumes) to have valid application credentials.

要求検証Claims validation

認証構成に クレーム検証コントロール を追加する必要があります。You must add a claims validator to the authentication configuration. 要求は認証ヘッダーの後に評価されます。The claims are evaluated after the authentication header. 要求を拒否するには、検証コードでエラーまたは例外をスローします。Throw an error or exception in your validation code to reject the request.

注意

アプリ ID とパスワードが含まれている場合、bot は要求の検証を実行します。それ以外の場合、要求の検証は実行されません。The bot performs claims validation if it has an app ID and password; otherwise, claims validation is not performed.

通常であれば認証される要求を、さまざまな理由で拒否することができます。There are various reasons you might reject an otherwise authenticated request:

  • スキル コンシューマーが、会話を開始した相手である可能性があるスキルからのトラフィックのみを受け入れる必要がある場合。When the skill consumer should accept traffic only from skills that it may have initiated a conversation with.
  • スキルが有料サービスの一部であり、データベースに登録されていないユーザーのアクセスを禁止する必要がある場合。When a skill is part of a paid-for service, and users not in the database should not have access.
  • スキルへのアクセスを特定のスキル コンシューマーに限定する場合。When you want to restrict access to the skill to specific skill consumers.

重要

要求検証コントロールを指定しない場合、bot がスキルまたはスキルの消費者であるかにかかわらず、別のボットからアクティビティを受け取ったときに、ボットによってエラーまたは例外が生成されます。If you don't provide a claims validator, your bot will generate an error or exception upon receiving an activity from another bot, whether your bot is a skill or a skill consumer.

関連情報Additional information

ユーザーから見ると、自分たちはルート ボットと対話しています。From the user's perspective, they are interacting with the root bot. スキルにとってスキル コンシューマーは、ユーザーとの通信に使用するチャネルです。From the skill's perspective, the skill consumer is the channel over which it communicates with the user.