Procesamiento de actividadesActivity processing

se aplica a: SDK V4APPLIES TO: SDK v4

El bot y el usuario interactúan e intercambian información mediante actividades.The bot and user interact and exchange information via activities. Cada una de las actividades que recibe la aplicación de bot se pasa a un adaptador de bot, que a su vez pasa la información de la actividad a la lógica del bot y, por último, envía las respuestas al usuario.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. La recepción de una actividad y su posterior procesamiento por el bot se denomina turno; representa un ciclo completo del bot.Receiving an activity, and subsequently processing it through your bot, is called a turn; this represents one complete cycle of your bot. Un turno finaliza cuando se termina toda la ejecución, la actividad se ha procesado por completo y se han completado todas las capas del bot.A turn ends when all execution is done, the activity is fully processed and all the layers of the bot have completed.

Las actividades, especialmente las enviadas desde un bot durante un turno del bot, se controlan de forma asincrónica.Activities, particularly those that are sent from a bot during a bot turn, are handled asynchronously. Se trata de una parte necesaria de la creación de un bot; si necesita repasar cómo funciona todo esto, vea Programación asincrónica para .NET o async para JavaScript, según el lenguaje que haya elegido.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.

El adaptador de botThe bot adapter

El adaptador de bot encapsula los procesos de autenticación, envía actividades a Bot Connector Service y recibe actividades de este.The bot adapter encapsulates authentication processes and sends activities to and receives activities from the Bot Connector Service. Cuando el bot recibe una actividad, el adaptador encapsula todo lo relativo a esa actividad, crea un objeto de contexto para el turno, lo pasa a la lógica de aplicación del bot y envía las respuestas que genera el bot al canal del usuario.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.

AuthenticationAuthentication

El adaptador autentica todas las actividades entrantes que recibe la aplicación mediante la información de la actividad y el encabezado Authentication de la solicitud de REST.The adapter authenticates each incoming activity the application receives, using information from the activity and the Authentication header from the REST request. El adaptador usa un objeto de conector y las credenciales de la aplicación para autenticar las actividades de salida con destino al usuario.The adapter uses a connector object and your application's credentials to authenticate the outbound activities to the user.

La autenticación de Bot Connector Service usa tokens Bearer de JWT (JSON Web Token), así como el identificador de aplicación de Microsoft y la contraseña de aplicación de Microsoft que Azure genera automáticamente cuando se crea un servicio de bot o se registra un bot.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. La aplicación necesitará estas credenciales en el tiempo de inicialización para permitir que el adaptador autentique el tráfico.Your application will need these credentials at initialization time, to allow the adapter to authenticate traffic.

Nota

Si está ejecutando o probando el bot localmente (por ejemplo, mediante Bot Framework Emulator), puede hacerlo sin configurar el adaptador para autenticar el tráfico hacia y desde el 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.

Contexto de turnoTurn context

Cuando un adaptador recibe una actividad, genera un objeto de contexto de turno, que proporciona información sobre la actividad entrante, el remitente, el receptor, el canal, la conversación y otros datos necesarios para procesar la actividad.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. Después, el adaptador pasa este objeto de contexto al bot.The adapter then passes this context object to the bot. El objeto de contexto se conserva mientras dure el turno y proporciona información sobre lo siguiente:The context object persists for the length of a turn, and provides information on the following:

  • Conversación: identifica la conversación e incluye información sobre el bot y el usuario que participan en la conversación.Conversation - Identifies the conversation and includes information about the bot and the user participating in the conversation.
  • Actividad: las solicitudes y las respuestas de una conversación son los tipos de actividades.Activity - The requests and replies in a conversation are all types of activities. Este contexto proporciona información sobre la actividad entrante, incluida la información de enrutamiento, la información sobre el canal, la conversación, el remitente y el receptor.This context provides information about the incoming activity, including routing information, information about the channel, the conversation, the sender, and the receiver.
  • Información personalizada: si extiende el bot mediante la implementación de software intermedio o dentro de la lógica del bot, puede hacer que haya información adicional disponible en cada turno.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.

El objeto de contexto también se puede usar para enviar una respuesta al usuario y obtener una referencia al adaptador.The context object can also be used to send a response to the user, and get a reference to the adapter..

Nota

La aplicación y el adaptador controlarán las solicitudes de forma asincrónica, pero no es necesario que la lógica de negocios esté controlada por la solicitud-respuesta.Your application and the adapter will handle requests asynchronously; however, your business logic does not need to be request-response driven.

Software intermedioMiddleware

Puede agregar software intermedio al adaptador.You can add middleware to the adapter. El software intermedio y la lógica del bot usan el objeto de contexto para recuperar información sobre la actividad y actuar en consecuencia.The middleware and the bot logic use the context object to retrieve information about the activity and act accordingly. El software intermedio y el bot también pueden actualizar o agregar información al objeto de contexto, por ejemplo, para llevar un seguimiento del estado de un turno, una conversación u otro ámbito.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. Para información más detallada sobre el middleware, consulte el artículo sobre el middleware.For more in depth information about middleware, see the middleware article.

Generación de respuestasGenerating responses

El objeto de contexto proporciona métodos de respuesta de actividad para permitir que el código responda a una actividad:The context object provides activity response methods to allow code to respond to an activity:

  • Los métodos send activity y send activities envían una o más actividades a la conversación.The send activity and send activities methods send one or more activities to the conversation.
  • Si el canal lo admite, el método update activity actualiza una actividad de la conversación.If supported by the channel, the update activity method updates an activity within the conversation.
  • Si el canal lo admite, el método delete activity elimina una actividad de la conversación.If supported by the channel, the delete activity method removes an activity from the conversation.

Cada método de respuesta se ejecuta en un proceso asincrónico.Each response method runs in an asynchronous process. Cuando se llama al método de respuesta de actividad, este clona la lista de controladores de eventos asociados antes de empezar a llamar a los controladores, lo que significa que contendrá todos los controladores agregados hasta ese momento, pero no contendrá nada de lo que se agregue una vez iniciado el proceso.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.

Esto también significa que no se garantiza el orden de las respuestas, sobre todo cuando una tarea es más compleja que otra.This also means the order of your responses is not guaranteed, particularly when one task is more complex than another. Si el bot puede generar varias respuestas para una actividad entrante, asegúrese de que tienen sentido en cualquier orden en el que las reciba el usuario.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.

Importante

El subproceso que administra el turno de bot principal se ocupa de desechar el objeto de contexto cuando termina.The thread handling the primary bot turn deals with disposing of the context object when it is done. Si una respuesta (incluidos sus controladores) tarda mucho e intenta actuar sobre el objeto de contexto, es posible que reciba un error 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. Asegúrese de usar await para las llamadas de actividad, a fin de que el subproceso principal espere la actividad generada antes de finalizar su procesamiento y desechar el contexto de turno.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.

Controladores de eventos de respuestaResponse event handlers

Además de la lógica del bot y del software intermedio, se pueden agregar controladores de respuesta (a veces denominados controladores de eventos o controladores de eventos de actividad) al objeto de contexto.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. Se llama a estos controladores cuando la respuesta asociada se produce en el objeto de contexto actual, antes de ejecutar la respuesta real.These handlers are called when the associated response happens on the current context object, before executing the actual response. Estos controladores son útiles si sabe que querrá hacer algo, ya sea antes o después del evento real, para todas las actividades de ese tipo durante el resto de la respuesta actual.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.

Advertencia

Tenga cuidado de no llamar a un método de respuesta de actividad desde su controlador de eventos de respuesta correspondiente, por ejemplo, mediante una llamada al método de actividad de envío desde un controlador on send activity.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. Si lo hace, puede generar un bucle infinito.Doing so can generate an infinite loop.

Cada actividad nueva obtiene un nuevo subproceso en el que se ejecuta.Each new activity gets a new thread to execute on. Cuando se crea el subproceso para procesar la actividad, la lista de controladores de esa actividad se copia en ese subproceso nuevo.When the thread to process the activity is created, the list of handlers for that activity is copied to that new thread. No se ejecutará para ese evento de actividad específico ningún controlador agregado después de ese punto.No handlers added after that point will be executed for that specific activity event.

El adaptador administra los controladores registrados en un objeto de contexto de forma muy similar al modo en que administra la canalización de middleware.The handlers registered on a context object are handled very similarly to how the adapter manages the middleware pipeline. Es decir, se llama a los controladores en el orden en que se agregan, y al llamar al delegado next se pasa el control al siguiente controlador de eventos registrado.Namely, handlers get called in the order they're added, and calling the next delegate passes control to the next registered event handler. Si un controlador no llama al delegado siguiente, no se llama a ninguno de los controladores de eventos posteriores, el evento cortocircuidoresy el adaptador no envía la respuesta al canal.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.

Pasos siguientesNext steps