Acerca de los consumidores de aptitudesAbout skill consumers

se aplica a: SDK V4APPLIES TO: SDK v4

Un consumidor de aptitudes es un bot que puede llamar a una o más aptitudes.A skill consumer is a bot that can call one or more skills. Con respecto a las aptitudes, un bot raíz es un bot orientado al usuario que también es un consumidor de aptitudes.With respect to skills, a root bot is a user-facing bot that is also a skill consumer.

Desde la perspectiva del usuario, el bot raíz es el bot con el que interactúan.From the user's perspective, the root bot is the bot they are interacting with. Desde la perspectiva de la aptitud, el consumidor de aptitudes es el canal por el que se comunica con el usuario.From the skill's perspective, the skill consumer is the channel over which it communicates with the user. (para obtener más información, consulte Acerca de las aptitudes y Acerca de los bots de aptitud).(For more information, see the skills overview and about skill bots.)

Como consumidor de aptitudes, un bot raíz incluye cierta lógica adicional para administrar el tráfico entre él y una aptitud:As a skill consumer, a root bot includes some additional logic to manage traffic between it and a skill:

  • Información de configuración de cada aptitud que el bot raíz utiliza.Configuration information for each skill the root uses.
  • Un generador de identificadores de conversación que permite al bot raíz alternar entre la conversación que mantiene con el usuario y la que mantiene con una aptitud.A conversation ID factory that allows the root to switch back and forth between the conversation it is having with the user and the one it is having with a skill.
  • Un cliente de aptitudes que puede empaquetar y reenviar actividades a un bot de aptitudes.A skill client that can package and forward activities to a skill bot.
  • Un controlador de aptitudes que puede recibir solicitudes y desempaquetar las actividades de un bot de aptitudes.A skill handler that can receive requests and unpack activities from a skill bot.

Administración de aptitudesManaging skills

La administración del inicio y finalización de la ejecución de una sola aptitud se hace con unas pocas adiciones al consumidor de aptitudes.Starting and letting a single skill run to completion is managed with a few additions to the skill consumer. Se pueden tener escenarios más complicados, con varias aptitudes o hilos de conversación.More complex scenarios are possible, with multiple skills or conversation threads.

Un consumidor de aptitudes implementa al menos dos puntos de conexión HTTP:A skill consumer implements at least two HTTP endpoints:

  • Un punto de conexión de mensajería recibe actividades del usuario o canal.A messaging endpoint receives activities from the user or channel. Este es el punto de conexión de mensajería habitual que implementan todos los bots.This is the usual messaging endpoint that all bots implement.
  • Un punto de conexión de host de aptitud para recibir actividades de una habilidad.A skill host endpoint for receiving activities from a skill. Esto actúa como una dirección URL de devolución de llamada, la dirección URL de servicio a la que responde la aptitud.This acts as a callback URL, the service URL to which the skill replies. (El consumidor de aptitudes necesita emparejar el código que recibe la solicitud de método HTTP de la aptitud con un controlador de aptitudes).(The skill consumer needs to pair code that receives the HTTP method request from the skill with a skill handler.)

Descripciones de aptitudesSkill descriptions

Para cada aptitud, agregue un objeto de aptitud de Bot Framework al archivo de configuración del consumidor de aptitudes.For each skill, add a Bot Framework skill object to the skill consumer's configuration file. Cada uno tendrá un identificador, un identificador de aplicación y un punto de conexión de la aptitud.Each one will have an ID, an app ID, and an endpoint for the skill.

PropiedadProperty DescripciónDescription
IdID Identificador o clave de la aptitud, específico del consumidor de aptitudes.The ID or key of the skill, specific to the skill consumer.
Id. de aplicaciónApp ID appId asignado al recurso de bot cuando la aptitud se registró en Azure.The appId assigned to the bot resource when the skill was registered on Azure.
Punto de conexión de aptitudSkill endpoint El punto de conexión de mensajería de la aptitud.The messaging endpoint for the skill. Esta es la dirección URL que el consumidor utilizará para comunicarse con la aptitud.This is the URL the consumer will use to communicate with the skill.

Controlador de aptitudes y cliente de aptitudesSkill client and skill handler

El consumidor de aptitudes usa un cliente de aptitudes para enviar actividades a una aptitud.The skill consumer uses a skill client to send activities to a skill. El cliente:The client:

  • Toma una actividad para enviar a la aptitud, ya sea de un usuario o generada por el consumidor.Takes an activity to send to the skill, either from a user or generated by the consumer.
  • Establece la dirección URL del servicio en la actividad que se envía al punto de conexión del host de aptitudes del consumidor.Sets the service URL on the activity sent to the skill to the consumer's skill host endpoint.
  • Reemplaza la referencia de la conversación original por la referencia de la conversación entre el consumidor y la aptitud.Replaces the original conversation reference with one for the consumer-skill conversation.
  • Agrega un token de autenticación de bot a bot.Adds a bot-to-bot authentication token.
  • Envía la actividad actualizada a la aptitud.Sends the updated activity to the skill.

El consumidor de aptitudes usa un controlador de aptitudes para recibir actividades de una aptitud.The skill consumer uses a skill handler to receive activities from a skill. El controlador:The handler:

  • Controla los métodos de API de REST del servicio de canal.Handles the channel service REST API methods.
  • Aplica la validación de la autenticación y las notificaciones.Enforces authentication and claims validation.
  • Recupera la referencia de la conversación original.Retrieves the original conversation reference.
  • Genera una actividad para el adaptador del consumidor.Generates an activity for the consumer's adapter. Esta actividad indicará que la aptitud se ha completado o que es una actividad para reenviar al usuario.This activity will either signal that the skill has completed or be an activity to forward to the user.

Administrar una aptitud directamenteManage a skill directly

Debe agregar lógica al consumidor de aptitudes para realizar un seguimiento de las aptitudes activas.You need to add logic to your skill consumer to track any active skills. El consumidor elige cómo administra las aptitudes en general, si puede mantener varias aptitudes activas en paralelo o no, y así sucesivamente.It is up to the consumer as to how it manages skills in general, whether it can maintain multiple active skills in parallel or not, and so on. Algunos escenarios específicos que se deben tener en cuenta son:Specific scenarios to consider include:

  • Iniciar una nueva conversación entre el consumidor y la aptitud.Initiating a new consumer-skill conversation. (Se asociará con una conversación específica entre el usuario y el consumidor).(This will be associated with a specific consumer-user conversation.)
    • Para pasar parámetros a una aptitud, establezca la propiedad value de la actividad inicial en la aptitud.To pass parameters to a skill, set the value property in the initial activity to the skill.
  • Continuar una conversación existente entre el consumidor y la aptitud.Continuing an existing consumer-skill conversation.
  • Reconocer una actividad endOfConversation de la aptitud como señalización del final de una conversación entre el consumidor y la aptitud.Recognizing an endOfConversation activity from the skill as signalling an end of a consumer-skill conversation.
    • Para recuperar cualquier valor devuelto de una aptitud, compruebe la propiedad value de la actividad.To retrieve any return value from a skill, check the activity's value property.
    • Para comprobar por qué está finalizando la aptitud, compruebe el parámetro code de la actividad, que podría indicar que la aptitud encontró un error.To check why the skill is ending, check the activity's code parameter, which could indicate that the skill encountered an error.
  • Cancelar una aptitud del consumidor mediante el envío de una actividad endOfConversation a la aptitud.Cancelling a skill from the consumer by sending an endOfConversation activity to the skill.

Consulte cómo implementar un consumidor de aptitudes para un consumidor que administre una aptitud directamente.See how to implement a skill consumer for a consumer that manages a skill directly.

Administrar una aptitud mediante un cuadro de diálogo de aptitudesManage a skill using a skill dialog

Si usa la biblioteca de diálogos, puede usar un diálogo de aptitudes para administrar una aptitud.If you are using the dialogs library, you can use a skill dialog to manage a skill. Aunque el diálogo de aptitudes es el diálogo activo, reenviará las actividades a la aptitud asociada.While the skill dialog is the active dialog, it will forward activities to the associated skill.

  • Al crear el diálogo de aptitudes, use el parámetro opciones del diálogo para proporcionar toda la información que necesita el diálogo para administrar la aptitud, como el identificador de aplicación del consumidor, la dirección URL de devolución de llamada, el generador de identificadores de conversación que se va a usar, las propiedades de la aptitud, etc.When you create the skill dialog, use the dialog options parameter to provide all the information the dialog needs to manage the skill, such as the consumer's app ID and callback URL, the conversation ID factory to use, the skill's properties, and so on.
    • Si desea administrar más de una aptitud como un diálogo, deberá crear un diálogo de aptitudes independiente para cada aptitud.If you want to manage more than one skill as a dialog, you will need to create a separate skill dialog for each skill.
    • A menudo, agregará el diálogo de aptitudes a un diálogo de componente.Often, you will add the skill dialog to a component dialog.
  • Para iniciar el diálogo de aptitudes, use el método begin del contexto del diálogo y proporcione el identificador del diálogo de aptitudes.To start the skill dialog, use the dialog context's begin method and provide the skill dialog's ID. Use el parámetro options para proporcionar la actividad que el consumidor enviará como la primera actividad a la aptitud.Use the options parameter to provide the activity the consumer will send as the first activity to the skill.
  • Puede cancelar o interrumpir el diálogo de aptitudes como lo haría con cualquier otro diálogo.You can cancel or interrupt the skill dialog as you would any other dialog. Para obtener un ejemplo, consulte cómo controlar las interrupciones de usuario.See how to handle user interruptions for an example.

Consulte cómo usar un cuadro de diálogo para consumir una aptitud para un consumidor que use un cuadro de diálogo para administrar una aptitud.See how to use a dialog to consume a skill for a consumer that uses a dialog to manage a skill.

Usar un modo de entrega de respuestas esperadasUsing a delivery mode of expect replies

Los bots y las habilidades usan REST y JSON estándar del sector a través de HTTPS para la comunicación.Bots and skills use industry-standard REST and JSON over HTTPS for communication. El flujo de procesamiento de actividad normal se inicia cuando el bot raíz recibe una solicitud post de un canal en su punto de conexión de mensajería.Normal activity processing flow starts when the root bot receives a post from a channel at the its messaging endpoint. A continuación, el bot raíz envía la actividad a la aptitud para su procesamiento.The root bot then sends the activity on to the skill for processing. Las respuestas de las aptitudes se devuelven al punto de conexión del host de aptitudes del bot raíz, no a su punto de conexión de mensajería.Replies from the skill are posted back to the root bot's skill host endpoint, not the its messaging endpoint. Por último, el bot raíz procesa las respuestas más o las devuelve al canal.Finally, the replies are processed further or posted back to the channel by the root bot. Este flujo normal se puede modificar cambiando el modo de entrega de la actividad que se envía a la aptitud.This normal flow can be altered by changing the delivery mode of the activity sent to the skill. Si el modo de entrega se establece en "ExpectReplies", la habilidad no volverá a enviarse al punto de conexión del host de aptitudes.If delivery mode is set to "ExpectReplies", the skill will not post back to the skill host endpoint. En su lugar, todas las actividades de respuesta se serializan en el cuerpo de la respuesta.Instead, all reply activities are serialized into the body of the response. A continuación, el bot raíz recorre en iteración estas actividades y las procesa de manera similar a como lo habrían procesado el punto de conexión del host de aptitudes.The root bot then iterates over these activities, processing them similar to how they would have been processed by the skill host endpoint.

Para obtener más información, consulte el modo de entrega en la especificación de la actividad.For information, see the Delivery mode in the Activity specification.