活動處理Activity processing

適用于: SDK v4APPLIES TO: SDK v4

Bot 和使用者會透過活動來互動並交換資訊。The bot and user interact and exchange information via activities. Bot 應用程式收到的每個活動都會傳遞至 Bot 介面卡,而其可將活動資訊傳遞給 Bot 邏輯,最終再傳送回應給使用者。Each activity received by your bot application is passed to a bot adapter, which passes activity information to your bot logic and ultimately sends any responses to the user. 接收活動與透過 Bot 的後續處理,稱為一回合;這代表 Bot 的一個完整的週期。Receiving an activity, and subsequently processing it through your bot, is called a turn; this represents one complete cycle of your bot. 完成所有的執行、活動已完全處理,並且 Bot 的所有層級均已完成時,即為一輪結束。A turn ends when all execution is done, the activity is fully processed and all the layers of the bot have completed.

系統將以非同步方式處理活動,特別是在 Bot 回合期間從 Bot 傳送的活動。Activities, particularly those that are sent from a bot during a bot turn, are handled asynchronously. 其為建置 Bot 的必要部分;如果您想要溫習所有作業的運作方式,請選擇您適用的語言,並參閱 .NET 非同步JavaScript 非同步It's a necessary part of building a bot; if you need to brush up on how that all works, check out async for .NET or async for JavaScript depending on your language choice.

Bot 介面卡The bot adapter

Bot 介面卡可封裝驗證處理程序,並可與 Bot 連接器服務相互傳送和接收活動。The bot adapter encapsulates authentication processes and sends activities to and receives activities from the Bot Connector Service. Bot 接收活動時,介面卡會包裝與該活動有關的所有項目、為該回合建立內容物件、將物件傳送至 Bot 應用程式邏輯,以及將 Bot 產生的回應傳回至使用者通道。When your bot receives an activity, the adapter wraps up everything about that activity, creates a context object for the turn, passes it to your bot's application logic, and sends responses generated by your bot back to the user's channel.

驗證Authentication

介面卡可使用活動的資訊和 REST 要求的 Authentication 標頭,驗證應用程式接收的每項內送活動。The adapter authenticates each incoming activity the application receives, using information from the activity and the Authentication header from the REST request. 介面卡會使用連接器物件及您的應用程式認證,驗證連出給使用者的活動。The adapter uses a connector object and your application's credentials to authenticate the outbound activities to the user.

Bot 連接器服務驗證採用 JWT (JSON Web 權杖) Bearer 權杖和 Microsoft 應用程式識別碼,以及 Azure 再您建立 Bot 服務或註冊 Bot 時為您建立的 Microsoft 應用程式密碼Bot Connector Service authentication uses JWT (JSON Web Token) Bearer tokens and the Microsoft app ID and Microsoft app password that Azure creates for you when you create a bot service or register your bot. 應用程式必須在初始化期間使用這些認證,介面卡才能驗證流量。Your application will need these credentials at initialization time, to allow the adapter to authenticate traffic.

注意

例如,如果您目前已在本機執行或測試 Bot,只要使用 Bot Framework 模擬器即可達到此目標,您無須再設定介面卡驗證來回 Bot 的流量。If you are running or testing your bot locally, for example, using the Bot Framework Emulator, you can do so without configuring the adapter to authenticate traffic to and from your bot.

回合內容Turn context

介面卡收到活動時會整合 回合內容 物件,其中提供內送活動、傳送者及收件者、通道、交談相關資訊,以及其他處理活動所需的資料。When an adapter receives an activity, it generates a turn context object, which provides information about the incoming activity, the sender and receiver, the channel, the conversation, and other data needed to process the activity. 接著,介面卡會將此內容物件傳遞至 Bot。The adapter then passes this context object to the bot. 在整個回合期間,內容物件都會持續存在,並提供下列資訊:The context object persists for the length of a turn, and provides information on the following:

  • 交談 - 識別交談並加入參加交談之 Bot 和使用者的資訊。Conversation - Identifies the conversation and includes information about the bot and the user participating in the conversation.
  • 活動 - 交談中的要求和回覆即所有類型的活動。Activity - The requests and replies in a conversation are all types of activities. 此內容將提供內送活動的相關資訊,包括路由資訊、通道資訊、交談、傳送者及收件者資訊。This context provides information about the incoming activity, including routing information, information about the channel, the conversation, the sender, and the receiver.
  • 自訂資訊 – 如果您實作中介軟體或在 Bot 邏輯中擴充 Bot 服務,則在每個回合中還可取得其他額外資訊。Custom information – If you extend your bot either by implementing middleware or within your bot logic, you can make additional information available in each turn.

內容物件也可用於傳送回應至使用者,並取得介面卡參考資料The context object can also be used to send a response to the user, and get a reference to the adapter..

注意

應用程式和介面卡將以非同步方式處理要求,不過您的業務邏輯不需要是「要求-回應」導向。Your application and the adapter will handle requests asynchronously; however, your business logic does not need to be request-response driven.

中介軟體Middleware

您可將中介軟體新增至介面卡。You can add middleware to the adapter. 中介軟體和 Bot 邏輯可使用內容物件擷取活動相關資訊,並據此採取行動。The middleware and the bot logic use the context object to retrieve information about the activity and act accordingly. 中介軟體和 Bot 亦可更新或新增資訊至內容物件,例如:追蹤回合、交談或其他範圍的狀態。The middleware and the bot can also update or add information to the context object, such as to track state for a turn, a conversation, or other scope. 如需有關中介軟體的深入詳細資訊,請參閱中介軟體文章For more in depth information about middleware, see the middleware article.

產生回應Generating responses

內容物件提供活動回應方法,讓程式碼回應活動:The context object provides activity response methods to allow code to respond to an activity:

  • 傳送活動傳送活動 方法可傳送一或多個活動至對話。The send activity and send activities methods send one or more activities to the conversation.
  • 如果通道支援,更新活動 方法也可更新交談內的活動。If supported by the channel, the update activity method updates an activity within the conversation.
  • 如果通道支援,刪除活動 方法也可移除交談內的活動。If supported by the channel, the delete activity method removes an activity from the conversation.

每個回應方法都會以非同步程序執行。Each response method runs in an asynchronous process. 系統呼叫活動回應方法時,該方法開始呼叫處理常式之前,會先複製相關聯的事件處理常式清單,這代表其中包含每個要在此點上新增的每個處理常式,但不包含處理程序開始後新增的項目。When it is called, the activity response method clones the associated event handler list before starting to call the handlers, which means it will contain every handler added up to this point but will not contain anything added after the process starts.

此外,這也表示無法保證回應順序,特別是其中一個工作比另一個更複雜的時候。This also means the order of your responses is not guaranteed, particularly when one task is more complex than another. 如果 Bot 可對內送活動產生多個回應,請確保使用者收到時無論什麼順序都符合常理。If your bot can generate multiple responses to an incoming activity, make sure that they make sense in whatever order they are received by the user.

重要

處理主要 Bot 回合的執行緒可在其完成後處置內容物件。The thread handling the primary bot turn deals with disposing of the context object when it is done. 如果回應 (包含其處理常式) 佔用大量時間,並嘗試在內容物件上動作,則可能會取得 Context was disposed 錯誤。If a response (including its handlers) take any significant amount of time and try to act on the context object, they may get a Context was disposed error. 請務必await任何活動呼叫,這樣主要執行緒才能先等候已產生的活動,再結束其正在處理的工作並處置回合內容。Be sure to await any activity calls so the primary thread will wait on the generated activity before finishing it's processing and disposing of the turn context.

回應事件處理常式Response event handlers

除了 Bot 和中介軟體邏輯,回應處理常式 (有時也指事件處理常式,或活動事件處理常式) 亦可新增至內容物件。In addition to the bot and middleware logic, response handlers (also sometimes referred to as event handlers, or activity event handlers) can be added to the context object. 目前的內容物件發生相關聯回應時,系統在執行實際回應之前會先呼叫處理常式。These handlers are called when the associated response happens on the current context object, before executing the actual response. 如果您已經知道想要針對其餘目前回應中,該類型的每個活動要執行哪些動作 (無論是在實際事件之前或之後執行),這些處理常式非常實用。These handlers are useful when you know you'll want to do something, either before or after the actual event, for every activity of that type for the rest of the current response.

警告

請特別小心,不要在其本身的個別回應事件處理常式內呼叫活動回應方法,例如:從 傳送活動 處理常式內呼叫傳送活動方法。Be careful to not call an activity response method from within it's respective response event handler, for example, calling the send activity method from within an on send activity handler. 這樣可能會產生無限迴圈。Doing so can generate an infinite loop.

每個新活動都取得要在其中執行的新執行緒。Each new activity gets a new thread to execute on. 建立執行緒處理活動時,該活動的處理常式清單會複製到該執行緒。When the thread to process the activity is created, the list of handlers for that activity is copied to that new thread. 系統不會針對該特定活動事件,執行該時間點後新增的任何處理常式。No handlers added after that point will be executed for that specific activity event.

內容物件上所註冊的處理常式,其處理方式非常類似於介面卡管理中介軟體管線的方式。The handlers registered on a context object are handled very similarly to how the adapter manages the middleware pipeline. 也就是說,系統將依照處理常式新增的順序進行呼叫,然後再呼叫 next 委派,將控制項傳遞至下個註冊的事件處理常式。Namely, handlers get called in the order they're added, and calling the next delegate passes control to the next registered event handler. 如果處理常式未呼叫下一個委派,則不會呼叫任何後續的事件處理常式、事件的 短電路,而且介面卡不會傳送回應給通道。If a handler doesn't call the next delegate, none of the subsequent event handlers are called, the event short circuits, and the adapter does not send the response to the channel.

後續步驟Next steps