Il n'y a pas de champ pour fournir des descriptions pour les composants personnalisés qui expliquent ce qu'ils font et quelles informations doivent leur être transmises. Ainsi, les meilleures façons d'aider les développeurs de compétences à utiliser votre composant sont d'utiliser des noms corrects pour le composant et les paramètres d'entrée et de choisir soigneusement les chaînes d'action retournées par votre composant.

• Les composants YAML intégrés utilisent System.<name> comme nom. Ainsi, en particulier pour les flux de dialogue basés sur YAML, vous pouvez utiliser Custom.<name> pour que les réviseurs de compétence comprennent qu'il s'agit d'un composant personnalisé auquel le flux de dialogue fait référence. Vous pouvez également utiliser un espace de noms pour fournir un contexte. Pour notre échantillon de composants personnalisés, nous utilisons souvent oracle.sample.<name> pour indiquer que ces composants ne sont pas destinés à être de qualité de production.

• Les paramètres d'entrée fournissent des données au composant personnalisé à traiter. Souvent, les données transmises à un composant personnalisé ne sont pas la valeur réelle à utiliser, mais plutôt le nom d'une variable qui contient les valeurs de données à traiter ou auxquelles les données interrogées à partir d'un service distant doivent être écrites. En regardant les composants intégrés, ils utilisent variable comme nom de propriété pour contenir le nom de la variable dans laquelle le résultat du composant sera écrit, ou <name>Var (par exemple nlpResultVar) pour indiquer les propriétés qui font référence à un nom de référence de variable. Vous pouvez améliorer cette situation en utilisant les postfixes _in et _out pour indiquer si une variable fait référence à une variable qui contient des données ou attend des données du composant.

• Les chaînes d'action sont facultatives et peuvent être utilisées par le développeur de la compétence pour déterminer l'état du flux de dialogue suivant vers lequel naviguer. L'utilisation de success ou failure comme chaîne d'action ne fournit pas beaucoup de contexte. Nous vous suggérons donc d'utiliser orderSubmitted, orderRejected ou userUnauthorized à la place.

La réalité est que souvent le développeur d'un composant personnalisé est également le développeur de compétences qui l'utilise. Pour cette raison, de nombreux développeurs simplifient leur travail avec des composants personnalisés en faisant des hypothèses sur les variables présentes dans la compétence. Ainsi, au lieu de transmettre le nom d'une variable au composant, ils font directement référence au nom dans la logique du composant personnalisé. Nous ne recommandons pas cela car de telles hypothèses peuvent facilement casser un composant personnalisé. Nous vous recommandons de définir un contrat clair et complet entre le composant personnalisé et les compétences qui l'utilisent.

Une question courante concerne le nombre de composants personnalisés à ajouter à un ensemble de services de composants personnalisés. En général, il est toujours judicieux de considérer les services de composants personnalisés et les composants qu'ils contiennent comme des bibliothèques. Ainsi, tous les composants liés à une tâche peuvent être enregistrés dans un seul service de composants personnalisés. Cependant, les recommandations doivent être en mesure de faire face à la réalité. Par conséquent, la question sur la façon d'emballer des composants personnalisés doit être traitée en fonction de l'utilisation prévue des composants personnalisés.

• La réutilisation n'est pas une option pour de nombreux développeurs de composants personnalisés. Lorsque des composants personnalisés sont développés pour et utilisés dans une compétence spécifique, il est logique de regrouper tous ces composants dans un seul déploiement de service de composants personnalisés. L'exception à cela concerne les composants qui sont réellement réutilisés dans d'autres compétences.

• Les déploiements de conteneur de composants intégrés sont limités par le nombre de services de composants personnalisés par instance Oracle Digital Assistant. Par conséquent, vous devez utiliser un seul service de composants personnalisés par compétence ou rechercher un déploiement à distance de vos composants personnalisés.

• Utiliser le déploiement de services de composants personnalisés distants vers Kubernetes dans Oracle Cloud Infrastructure, pour les raisons suivantes :

  • Pour ne pas divulguer d'informations sensibles contenues dans votre code de composant personnalisé. Les services de composants personnalisés déployés dans le conteneur intégré peuvent être téléchargés par toute personne disposant d'un accès complet à votre instance Oracle Digital Assistant.

  • Mettre en œuvre une meilleure segmentation de votre code. Les composants personnalisés ne doivent contenir que du code nécessaire pour interagir avec le robot et appeler des services REST. Tout autre code doit être stocké dans des fichiers JavaScript externes (si vous utilisez un conteneur intégré) ou dans des couches d'intégration (services REST). Les composants personnalisés incluent du code qui effectue les opérations suivantes :

    • lire les paramètres d'entrée

    • lire/définir des valeurs de variable

    • gérer les messages reçus par un composant

    • afficher l'interface utilisateur du composant personnalisé

    • déterminer la transition vers un état suivant

    • gérer l'état du composant

    • accéder aux services REST

  • Pour améliorer les performances. Le conteneur intégré pour déployer des composants personnalisés vers des compétences utilise les fonctions OCI, qui ont un délai de démarrage à froid. Pour éviter ce retard, ainsi que la limite du nombre de services pouvant être déployés, un déploiement à distance d'un composant personnalisé vous offre une alternative sans souci.

  • Pour partager des composants communs. Bien que notre expérience soit que la réutilisation ne soit pas très bien classée parmi les développeurs de composants personnalisés, il est logique de créer et de déployer des composants personnalisés couramment utilisés sur un serveur distant. Vous pouvez avoir des composants communs pour le traitement des erreurs et l'escalade, le traitement des autorisations OAuth2 à 2 branches, etc.

L'enregistreur automatique par défaut mis en oeuvre pour les composants personnalisés est l'enregistreur automatique de la console. Vous accédez à l'enregistreur automatique au moyen d'un appel à context.logger(). Vous pouvez utiliser les fonctions de journalisation des appels disponibles pour l'enregistreur automatique de la console, par exemple ".info('…') ou ".warn('…')".

Note : L'utilisation de context.logger() est la plus logique lors du déploiement vers le conteneur intégré, car le conteneur intégré sait comment afficher correctement ces journaux. Pour les composants personnalisés que vous déployez à l'externe, il est préférable d'utiliser une autre bibliothèque de journalisation, telle que log4js.

Les composants de flux de dialogue personnalisés peuvent avoir une interaction plus longue avec un utilisateur avant que la navigation passe à un état de flux de dialogue suivant. Pour cette interaction, vous devez vous assurer que le composant gère son état interne afin qu'il puisse faire la distinction entre un appel initial et les appels suivants. Il existe deux options pour ce faire :

• Ajoutez un jeton aux données utiles du message de republication. Lorsque le composant personnalisé affiche une interface utilisateur dans laquelle les utilisateurs peuvent appuyer sur une action à entreprendre, un message de republication est renvoyé au composant personnalisé. Le composant personnalisé doit évaluer les messages de republication qu'il reçoit pour déterminer si cette republication provient de l'interface utilisateur qu'il affiche ou d'un autre composant. Pour cela, il peut vérifier si le message de republication contient un jeton ajouté par le composant personnalisé lors du rendu de l'action à entreprendre.

• Utilisez une variable de flux de dialogue. Si vous devez gérer un état plus complexe entre les appels de composants personnalisés, par exemple pour assurer le suivi des valeurs extraites des messages d'utilisateur, vous pouvez utiliser une variable de flux de dialogue pour cela. Les composants personnalisés peuvent créer des variables de flux de dialogue lors de l'exécution dans un appel à context.variable('variable name', value). Si une variable du nom spécifié n'existe pas, elle sera créée. L'objet "valeur" peut être tout ce dont vous avez besoin pour suivre.

Les paramètres d'entrée que vous définissez pour un composant personnalisé doivent être validés pour avoir du contenu. Cela est également vrai pour les paramètres que vous définissez au besoin. Les cas suivants doivent être vérifiés :

• Le paramètre d'entrée comporte un jeu de valeurs.

• La valeur ne commence pas par '$ {', car cela indique une expression pour lire la valeur du paramètre d'entrée à partir d'une variable ou qu'un objet n'est pas résolu correctement dans le flux de dialogue.

Toutes les réponses de robot que vous envoyez à partir d'un composant personnalisé doivent utiliser la classe MessageFactory. La classe MessageFactory peut être utilisée pour créer le même type de messages d'utilisateur enrichi que le composant Réponse commune, qui inclut une liste de valeurs, des fichiers joints, des dispositions de carte et des messages texte.

En outre, les messages définis avec la classe MessageFactory sont indépendants des canaux. Cela signifie que vous créez un message de composant unique, qui est ensuite converti par les connecteurs spécifiques au canal dans le format requis par le canal client respectif.

Pour accéder à la classe MessageFactory à partir d'un composant personnalisé, utilisez la référence suivante :

let MessageFactory = context.MessageFactory();

• ☑ Assurez-vous que les services dorsaux sont optimisés ou abstraits pour une utilisation avec les compétences.
• ☑ Les composants personnalisés ne doivent contenir que du code associé au robot. Tout autre code doit être déplacé dans des classes ou des bibliothèques d'utilitaires, ou déployé en tant que services REST individuels vers un serveur distant ou un service en nuage.
• ☑ Créez un contrat clair et complet entre les composants personnalisés et les compétences dans lesquelles ils sont utilisés.
• ☑ Utilisez des composants personnalisés pour les évaluations complexes. Évitez Apache FreeMarker dans ces cas.
• ☑ Gérer l'état des composants pour les interactions utilisateur à demandes multiples.
• ☑ Validez tous les paramètres d'entrée de composant personnalisé.
• ☑ Gérez les erreurs en retournant une chaîne d'action pour que le développeur de la compétence puisse traiter les problèmes.

• Tutoriel : Développement de composants personnalisés pour l'intégration dorsale
• Tutoriel : Débogage de composant personnalisé
• Limites de conteneur intégré pour les services de composants personnalisés
• Documentation sur la trousse SDK de développement de robots : exemple de code MessageFactory pour diverses réponses d'interface utilisateur

Une grande partie des fonctionnalités pouvant être définies pour le composant Common Response, telles que les boutons globaux d'aide et d'annulation, n'est pas disponible pour le composant Resolve Entities via la configuration.

Toutefois, vous pouvez ajouter des fonctionnalités manquantes à l'aide des programmes de traitement d'événements d'entité. Cela vous permet de tirer parti de la simplicité du composant Résoudre les entités dans le flux de dialogue sans sacrifier les fonctionnalités avancées.

Les fonctions du gestionnaire d'événements d'entité sont appelées par les composants Resolve Entities et Common Response lors de la résolution d'une entité composite. Il n'est pas nécessaire pour vous de suivre quel article de sac doit être résolu ensuite car tout est fait pour vous.

Néanmoins, vous voudrez peut-être enregistrer certaines informations pour une utilisation ultérieure. Pour cela, vous avez deux options :

• Les propriétés de résolution de contexte sont des variables que vous créez sur l'objet de contexte. Les variables et leurs valeurs existent jusqu'à ce que l'entité composite soit résolue ou que vous quittiez l'état du flux de dialogue qui résout une entité composite. L'avantage d'utiliser les propriétés de résolution de contexte est qu'il n'y a pas d'entretien ménager que vous devez faire.

  • Pour l'écriture, utilisez : context.setCustomProperty(name, value);
  • Pour la lecture, utilisez : context.getCustomProperty(name);

• Les variables de flux Dialog créées lors de l'exécution ou lors de la conception peuvent être utilisées pour stocker les valeurs que vous souhaitez conserver au-delà de la résolution de l'entité composite. Le contenu stocké dans les variables de flux de dialogue est accessible à partir des états de flux de dialogue (pour les variables définies lors de la conception uniquement) et à partir d'autres programmes de traitement d'événements d'entité.

  • Pour l'écriture, utilisez : context.variable(name,value);
  • Pour la lecture, utilisez : context.variable(name);

L'enregistreur automatique par défaut mis en oeuvre pour les programmes de traitement d'événements d'entité est l'enregistreur automatique de la console.

Vous accédez à l'enregistreur automatique au moyen d'un appel à context.logger().

Vous pouvez utiliser les fonctions de journalisation des appels disponibles pour l'enregistreur automatique de la console, telles que .info('…') ou .warn('…').

Les messages d'utilisateur personnalisés sont affichés au moyen de la fonction context.addMessage(). Comme pour les composants de flux de dialogue personnalisés, nous vous recommandons d'utiliser la classe MessageFactory pour créer des messages indépendants du canal au lieu de générer des données utiles propres au canal. Les programmes de traitement d'événements d'entité prennent également en charge les messages de type liste de valeurs, disposition de carte et fichier joint.

• ☑ Stockez les valeurs temporaires dans le contexte de résolution, sauf si cela est nécessaire dans un état de flux de dialogue ultérieur.
• ☑ Utilisez un seul service de composants personnalisés pour tous les programmes de traitement d'événements d'entité utilisés dans une compétence.
• ☑ Utilisez la classe MessageFactory pour afficher les messages aux utilisateurs.

• Vidéo du camp de conception d'Oracle Digital Assistant : Présentation des programmes de traitement d'événements d'entité

• Tutoriel : Développement du programme de traitement d'événements d'entité dans le navigateur

• Tutoriel : Développement du programme de traitement d'événements d'entité dans un environnement de développement intégré externe
• Exemple : Conversations basées sur un modèle utilisant EEH par exemple d'un rapport de frais
• Documentation sur la trousse SDK de développement de robots : exemple de code MessageFactory pour diverses réponses d'interface utilisateur
• Documentation : Fonctions du programme de traitement d'événements d'entité (exposées sur l'objet de contexte)

Voici comment accéder aux paramètres nommés dans un ensemble de ressources :

//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);

L'utilisation d'ensembles de ressources partout est un thème commun dans ce guide. Toutefois, l'utilisation d'ensembles de ressources stockés dans une compétence crée un couplage étroit entre le composant de flux de dialogue personnalisé ou le programme de traitement d'événements et la compétence. Si vous êtes d'accord avec cette dépendance et appréciez l'avantage d'avoir des chaînes de ressource gérées en un seul endroit plus que d'éviter le problème du couplage serré, vous devriez le faire. Pour les gestionnaires d'événements, la possibilité de réutilisation est minime de toute façon, c'est pourquoi il ne devrait pas y avoir de doute sur l'utilisation des chaînes de regroupement de ressources dans les gestionnaires d'événements d'entité.

Pour les composants de flux de dialogue personnalisés réutilisés dans différentes compétences, la fonction de traduction fonctionne également si les compétences ont les noms de clé d'ensemble de ressources requis par le composant personnalisé ajoutés à leur ensemble de ressources.

À l'aide d'une autre solution, vous pouvez éviter de coupler étroitement des composants personnalisés à une compétence en transmettant les messages lus à partir d'un ensemble de ressources en tant que paramètres d'entrée à un composant de flux de dialogue personnalisé.