技能概觀Skills overview

適用于: SDK v4APPLIES TO: SDK v4

從 Bot Framework SDK 版本 4.7 開始,您可以使用另一個聊天機器人 (技能) 來擴充 Bot。Starting with version 4.7 of the Bot Framework SDK, you can extend a bot using another bot (a skill). 技能可由各種不同的 Bot 取用且便於重複使用;因此,您可以建立使用者對應的 Bot,並透過您自己或第三方廠商的技能加以擴充。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.

  • 「技能」是一種 Bot,可以為另一個 Bot 執行一組工作。A skill is a bot that can perform a set of tasks for another bot. Bot 可以是一項技能和使用者對應的 Bot。A bot can be both a skill and a user-facing bot.
  • 「技能取用者」是可呼叫一或多項技能的 Bot。A skill consumer is a bot that can call one or more skills. 使用者對應的技能取用者也稱為「根 Bot」。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.

換句話說,使用者會直接與根目錄 Bot 互動,而根目錄 Bot 會將其中一些交談邏輯委派給技能。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:

  • 技能和取用者會使用 Bot 架構通訊協定,透過 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# Bot 可以取用使用 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.
  • 技能支援使用者驗證;不過,使用者驗證是在本機上使用的技能,無法轉移至另一個 Bot。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

技能和技能取用者是不同的 Bot,可以獨立發佈。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. 除了一般的 Bot 和配接器物件,取用者還包含一些與技能相關的物件,用來與技能交換活動。In addition to the usual bot and adapter objects, the consumer includes a few skill-related objects, used to exchange activities with the skill. 技能取用者會至少執行兩個 HTTP 端點:A skill consumer implements at least two HTTP endpoints:
    • 訊息端點 會接收來自使用者或通道的活動。A messaging endpoint receives activities from the user or channel. 這是所有 bot 都會執行的一般訊息端點。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.

此圖表概述從使用者到根目錄 Bot、技能再重覆循環的活動流程。This diagram outlines the flow of activities from the user to the root bot to a skill and back again.

架構圖

  1. 根目錄 Bot 的配接器會接收來自使用者的活動,並將其轉送至根目錄 Bot 的活動處理常式。The root bot's adapter receives activities from the user and forwards them to the root bot's activity handler. 系統會在根 bot 的訊息端點接收來自使用者的 (活動。 ) (Activities from the user are received at the root bot's messaging endpoint.)
  2. 根目錄 Bot 會使用技能 HTTP 用戶端,將活動傳送至技能。The root bot uses a skill HTTP client to send an activity to the skill. 用戶端會從技能定義和技能交談識別碼 factory 取得取用者技能交談資訊。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. 在技能 bot 的訊息端點收到來自取用者的 (活動。 ) (Activities from the consumer are received at the skill bot's messaging endpoint.)
  4. 當技能回應時,根目錄 Bot 的技能處理常式會接收活動。When the skill responds, the root bot's skill handler receives the activity. 接著從技能交談識別碼中心取得根使用者的交談資訊。It gets the root-user conversation information from the skill conversation ID factory. 然後,其會將活動轉送到根目錄 Bot 的配接器。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. 根目錄 Bot 的配接器會在內部產生主動式訊息,以繼續與使用者交談。The root bot's adapter internally generates a proactive message to resume the conversation with the user.
  6. 根目錄 Bot 的配接器會將任何來自技能的訊息傳送給使用者。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.
  • 「技能交談識別碼中心」可在使用者根交談參考與根技能交談參考之間轉譯。The skill conversation ID factory translates between the user-root conversation reference and the root-skill conversation reference.
  • Bot Connector 服務可提供通道和 Bot 對 Bot 驗證。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.

技能用戶端和技能處理常式物件都會使用「交談識別碼中心」在根目錄 Bot 用來與使用者互動的交談和根目錄 Bot 用來與技能互動的交談之間進行轉譯。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 對 Bot 的通訊Bot-to-bot communication

請務必了解這項設計的某些層面,與您設計的 Bot 無關。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.

「交談識別碼中心」有助於管理技能取用者與技能間的流量。The conversation ID factory helps to manage traffic between a skill consumer and a skill. 中心會轉譯根與使用者和技能之間的交談識別碼。The factory translates between the ID of the conversation the root has with the user and the one it has with the skill. 換句話說,其會產生要在根與技能之間使用的交談識別碼,並從根技能的交談識別碼復原原始的使用者根交談識別碼。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

根和技能 Bot 會透過 HTTP 進行通訊。The root and skill bots communicate over HTTP. 因此,從技能接收活動的根 Bot 執行個體可能不是傳送起始活動的相同執行個體。換句話說,可能有不同的伺服器會處理這兩個要求。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. 不過,取用者會建立用來與技能通訊的交談識別碼。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 對 Bot 驗證Bot-to-bot authentication

從4.11 版開始,您不需要應用程式識別碼和密碼,即可在模擬器中本機測試技能和技能取用者。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. 其架構會使用持有人權杖和 Bot 應用程式識別碼來驗證每個 Bot 的身分識別。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.)

重要

這需要所有已部署的 bot (技能取用者,以及它所使用的任何技能) 具有有效的應用程式認證。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.

注意

如果 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 將會在收到來自另一個 bot 的活動時產生錯誤或例外狀況,無論您的 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

從使用者的觀點來看,技能取用者會與根 Bot 互動。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.