No hay un campo para proporcionar descripciones de componentes personalizados que expliquen lo que hacen y qué información se debe transferir a ellos. Por lo tanto, las mejores formas de ayudar a los desarrolladores de aptitudes a utilizar el componente son utilizar nombres correctos para el componente y los parámetros de entrada y seleccionar cuidadosamente las cadenas de acción que devuelve el componente.

• Los componentes YAML incorporados utilizan System.<name> como nombre. Por lo tanto, especialmente para los flujos de diálogo basados en YAML, puede que desee utilizar Custom.<name> para que los revisores de aptitudes comprendan que es un componente personalizado al que hace referencia el flujo de diálogo. O bien, puede utilizar un espacio de nombres para proporcionar contexto. Para nuestros componentes personalizados de muestra, a menudo utilizamos oracle.sample.<name> para indicar que esos componentes no están destinados a ser de calidad de producción.

• Los parámetros de entrada proporcionan datos al componente personalizado que se va a procesar. A menudo, los datos transferidos a un componente personalizado no son el valor real con el que trabajar, sino el nombre de una variable que contiene los valores de datos que procesar o en la que se deben escribir los datos consultados desde un servicio remoto. Si observan los componentes incorporados, utilizan variable como nombre de propiedad para contener el nombre de la variable en la que se escribirá el resultado del componente o <name>Var (por ejemplo, nlpResultVar) para indicar propiedades que hacen referencia a un nombre de referencia de variable. Puede mejorarlo aún más mediante los postfijos _in y _out para indicar si una variable hace referencia a una variable que contiene datos o está esperando datos del componente.

• Las cadenas de acción son opcionales y las puede utilizar el desarrollador de aptitudes para determinar el siguiente estado de flujo de diálogo al que navegar. El uso de success o failure como cadena de acción no proporciona mucho contexto, por lo que se recomienda utilizar algo como orderSubmitted, orderRejected o userUnauthorized en su lugar.

La realidad es que a menudo el desarrollador de un componente personalizado también es el desarrollador de aptitudes que lo utiliza. Por este motivo, muchos desarrolladores simplifican su trabajo con componentes personalizados realizando suposiciones sobre variables que están presentes en la aptitud. Por lo tanto, en lugar de transferir el nombre de una variable al componente, hacen referencia directamente al nombre en la lógica del componente personalizado. No recomendamos esto porque estas suposiciones pueden romper fácilmente un componente personalizado. Recomendamos definir un contrato claro y completo entre el componente personalizado y las aptitudes que lo utilizan.

Una pregunta común es cuántos componentes personalizados se deben agregar a un paquete de servicios de componentes personalizados. En general, siempre es una buena idea pensar en los servicios de componentes personalizados, y los componentes que contiene, como bibliotecas. Por lo tanto, todos los componentes relacionados con una tarea se pueden guardar en un único servicio de componentes personalizados. Sin embargo, las recomendaciones deben ser capaces de hacer frente a la realidad. Por lo tanto, la pregunta sobre cómo empaquetar componentes personalizados debe responderse en función del uso previsto de los componentes personalizados.

• La reutilización no es una opción para muchos desarrolladores de componentes personalizados. Cuando los componentes personalizados se desarrollan y utilizan en una aptitud específica, tiene sentido agrupar todos esos componentes en un único despliegue de servicio de componentes personalizados. La excepción a esto es para los componentes que se reutilizan realmente en otras aptitudes.

• Los despliegues de contenedores de componentes incrustados están restringidos por el número de servicios de componentes personalizados por instancia de Oracle Digital Assistant. Por lo tanto, deseará utilizar un único servicio de componentes personalizados por aptitud o buscar un despliegue remoto de los componentes personalizados.

• Utilizar el despliegue remoto de servicio de componentes personalizados en Kubernetes en Oracle Cloud Infrastructure, por los siguientes motivos:

  • No divulgar información confidencial incluida en el código de componente personalizado. Los servicios de componentes personalizados desplegados en el contenedor embebido los puede descargar cualquier persona que tenga acceso completo a la instancia de Oracle Digital Assistant.

  • Para implantar una mejor segmentación del código. Los componentes personalizados solo deben contener el código necesario para interactuar con el bot y llamar a los servicios REST. El resto del código se debe almacenar en archivos JavaScript externos (si se utiliza un contenedor embebido) o en capas de integración (servicios REST). Los componentes personalizados incluyen código que realiza las siguientes acciones:

    • parámetros de entrada de lectura

    • valores de variable read/set

    • manejar mensajes recibidos por un componente

    • Representar la interfaz de usuario del componente personalizado

    • determinar la transición al siguiente estado

    • gestionar el estado de los componentes

    • acceso a servicios REST

  • Mejorar el rendimiento. El contenedor embebido para desplegar componentes personalizados en aptitudes utiliza funciones de OCI, que tienen un retraso de inicio en frío. Para evitar este retraso, así como el límite en el número de servicios que se pueden desplegar, un despliegue remoto de componente personalizado le proporciona una alternativa sin preocupaciones.

  • Compartir componentes comunes. Aunque nuestra experiencia es que la reutilización no está muy clasificada entre los desarrolladores de componentes personalizados, tiene sentido crear y desplegar componentes personalizados de uso común en un servidor remoto. Puede que tenga componentes comunes para aspectos como el manejo y la escalada de errores, el manejo de autorizaciones OAuth2 de 2 partes y mucho más.

El registrador por defecto implantado para componentes personalizados es el registrador de consola. Puede acceder al registrador mediante una llamada a context.logger(). Puede utilizar las funciones de registro de llamadas disponibles para el registrador de consola, como ".info('…') o ".warn('…')".

Nota: el uso de context.logger() tiene más sentido al desplegar en el contenedor embebido, ya que el contenedor embebido sabe cómo mostrar correctamente estos logs. Para los componentes personalizados que despliega externamente, es mejor utilizar una biblioteca de registro diferente, como log4js.

Los componentes del flujo de diálogo personalizado pueden tener una interacción más larga con un usuario antes de que la navegación pase a un siguiente estado de flujo de diálogo. Para esta interacción, debe asegurarse de que el componente maneja su estado interno para que pueda distinguir entre una llamada inicial y las llamadas posteriores. Para ello, existen dos opciones:

• Agregue un token a la carga útil del mensaje de devolución. Cuando el componente personalizado representa una interfaz de usuario en la que los usuarios pueden pulsar un elemento de acción, se envía un mensaje de devolución al componente personalizado. El componente personalizado debe evaluar los mensajes de devolución que recibe para determinar si dicha devolución procede de la interfaz de usuario que está representando o de otro componente. Para ello, puede comprobar el mensaje de devolución en cuanto a si contiene un token que el componente personalizado agregó al representar el elemento de acción.

• Utilice una variable de flujo de diálogo. Si necesita gestionar un estado más complejo entre llamadas a componentes personalizados, por ejemplo, para realizar un seguimiento de los valores extraídos de los mensajes de usuario, puede utilizar una variable de flujo de diálogo para ello. Los componentes personalizados pueden crear variables de flujo de diálogo en tiempo de ejecución en una llamada a context.variable('variable name', value). Si no existe una variable con el nombre especificado, se creará. El objeto "value" puede ser cualquier cosa que necesite para realizar un seguimiento.

Los parámetros de entrada que defina para un componente personalizado deben validarse para tener contenido. Esto también se aplica a los parámetros que defina como necesarios. Es necesario comprobar los siguientes casos:

• El parámetro de entrada tiene un valor definido.

• El valor no empieza por '$ {', ya que indica una expresión para leer el valor del parámetro de entrada de una variable o que un objeto no se ha resuelto correctamente en el flujo de diálogo.

Todas las respuestas de bot que envíe desde un componente personalizado deben utilizar la clase MessageFactory. La clase MessageFactory se puede utilizar para crear el mismo tipo de mensajes de usuario enriquecidos que el componente Respuesta común, que incluye una lista de valores, anexos, diseños de tarjetas y mensajes de texto.

Además, los mensajes que se definen con la clase MessageFactory son independientes del canal. Esto significa que se crea un mensaje de componente único, que luego los conectores específicos del canal convierten en el formato requerido por el canal de cliente correspondiente.

Para acceder a la clase MessageFactory desde un componente personalizado, utilice la siguiente referencia:

let MessageFactory = context.MessageFactory();

• ☑ Asegúrese de que los servicios de backend estén optimizados o abstraídos para su uso con aptitudes.
• ☑ Los componentes personalizados solo deben contener código relacionado con bots. El resto del código se debe mover a bibliotecas o clases de utilidades, o bien se debe desplegar como servicios REST individuales en un servidor remoto o servicio en la nube.
• ☑ Cree un contrato claro y completo entre los componentes personalizados y las aptitudes en las que se utilizan.
• ☑ Utilice componentes personalizados para evaluaciones complejas. Evite Apache FreeMarker en esos casos.
• ☑ Gestione el estado de los componentes para interacciones de usuario de varias solicitudes.
• ☑ Valide todos los parámetros de entrada de componentes personalizados.
• ☑ Gestione los errores devolviendo una cadena de acción para que el desarrollador de aptitudes gestione los problemas.

• Tutorial: Desarrollo de componentes personalizados para la integración de backend
• Tutorial: depuración de componentes personalizados
• Límites de contenedores incrustados para servicios de componentes personalizados
• Documentación del SDK del nodo de bots: código de ejemplo MessageFactory para varias respuestas de la interfaz de usuario

Gran parte de la funcionalidad que se puede definir para el componente Respuesta común, como botones globales de ayuda y cancelación, no está disponible para el componente Resolver entidades mediante la configuración.

Sin embargo, puede agregar la funcionalidad que falta mediante manejadores de eventos de entidad. Esto le permite aprovechar la simplicidad del componente Resolver entidades en el flujo de diálogo sin sacrificar la funcionalidad avanzada.

Los componentes Resolve Entities y Common Response llaman a las funciones del manejador de eventos de entidad al resolver una entidad de bolsa compuesta. No es necesario que realice un seguimiento de qué artículo de bolsa debe resolverse a continuación, ya que todo se realiza por usted.

Aún así, puede que desee guardar información para su uso posterior. Para ello, tiene dos opciones:

• Las propiedades de resolución de contexto son variables que crea en el objeto de contexto. Las variables y sus valores existen hasta que se resuelve la entidad de bolsa compuesta o se deja el estado del flujo de diálogo que resuelve una entidad de bolsa compuesta. La ventaja de usar las propiedades de resolución de contexto es que no hay servicio de limpieza que deba hacer.

  • Para escritura, utilice: context.setCustomProperty(name, value);
  • Para la lectura, utilice: context.getCustomProperty(name);

• Las variables de flujo de diálogo creadas en tiempo de ejecución o en tiempo de diseño se pueden utilizar para almacenar los valores que desea mantener más allá de la resolución de la entidad de bolsa compuesta. Se puede acceder al contenido almacenado en variables de flujo de diálogo desde estados de flujo de diálogo (solo para variables definidas en tiempo de diseño) y desde otros manejadores de eventos de entidad.

  • Para escritura, utilice: context.variable(name,value);
  • Para la lectura, utilice: context.variable(name);

El registrador por defecto implantado para los manejadores de eventos de entidad es el registrador de consola.

Puede acceder al registrador mediante una llamada a context.logger().

Puede utilizar las funciones de registro de llamadas disponibles para el registrador de consola, como .info('…') o .warn('…').

Los mensajes de usuario personalizados se muestran mediante la función context.addMessage(). Al igual que con los componentes de flujo de diálogo personalizados, nuestra recomendación es utilizar la clase MessageFactory para crear mensajes independientes del canal en lugar de generar cargas útiles específicas del canal. Los gestores de eventos de entidad también admiten mensajes de tipo lista de valores, diseño de tarjeta y anexo.

• ☑ Almacene valores temporales en el contexto de resolución a menos que sea necesario en un estado de flujo de diálogo posterior.
• ☑ Utilice un único servicio de componente personalizado para todos los manejadores de eventos de entidad utilizados en una aptitud.
• ☑ Utilice la clase MessageFactory para que los mensajes se muestren a los usuarios.

• Video del campamento de diseño de Oracle Digital Assistant: Descripción de los manejadores de eventos de entidades

• Tutorial: Desarrollo del manejador de eventos de entidades en el explorador

• Tutorial: Desarrollo de un manejador de eventos de entidad en un IDE externo
• Ejemplo: Conversaciones basadas en modelos con EEH por ejemplo de un informe de gastos
• Documentación del SDK del nodo de bots: código de ejemplo MessageFactory para varias respuestas de la interfaz de usuario
• Documentación: Funciones del manejador de eventos de entidad (expuestas en el objeto de contexto)

A continuación, se muestra cómo acceder a parámetros con nombre en un grupo de recursos:

//Entity event handler sample
let expression = "${rb('key_name','param_name1,param_name2',"+value1+","+value2+")}";
let message = messageFactory.createTextMessage(expression);
context.addMessage(message,true);

//Custom dialog flow component sample
let expression = "${rb('key_name','param_name1,param_name2',"+value1+","+value2+")}";
let message = messageFactory.createTextMessage(expression);
context.reply(message);

El uso de grupos de recursos en todas partes es un tema común en esta guía. Sin embargo, el uso de grupos de recursos almacenados en una aptitud crea un acoplamiento estricto entre el componente de flujo de diálogo personalizado o el manejador de eventos y la aptitud. Si está de acuerdo con esta dependencia y valora la ventaja de tener cadenas de recursos gestionadas en un solo lugar más que evitar el problema del acoplamiento estricto, debe hacerlo. En el caso de los gestores de eventos, la posibilidad de reutilización es mínima, por lo que no debe haber ninguna duda sobre el uso de cadenas de grupos de recursos en los gestores de eventos de entidades.

Para los componentes de flujo de diálogo personalizados que se reutilizan en diferentes aptitudes, la función de traducción también funcionará si las aptitudes tienen los nombres de clave de grupo de recursos requeridos por el componente personalizado agregado a su grupo de recursos.

Con una solución alternativa, puede evitar el acoplamiento estricto de componentes personalizados a una aptitud transfiriendo los mensajes leídos de un grupo de recursos como parámetros de entrada a un componente de flujo de diálogo personalizado.