Création, implémentation et test de services
Les services d'objet sont des fonctions qu'un objet peut exécuter. Les services sont utilisés en interne dans la plateforme ThingWorx et par les applications composites. Ils sont accessibles depuis n'importe quelle source externe disposant des droits d'accès appropriés. Vous ne pouvez définir des services que sur les entités ThingWorx suivantes :
• Objets
• Modèles d'objet
• Formes d'objet
• Ressources
• Authentificateurs
Les services sont implémentés via JavaScript, SQL ou Java.
 |
Java n'est disponible que pour les extensions.
|
Un service peut être appelé via une URL, une application client REST, ou par un autre service dans ThingWorx.
Créez des services personnalisés pour votre modèle dans ThingWorx afin de répondre aux exigences de votre projet.
Bonnes pratiques pour la création et l'implémentation de services
Utilisez les bonnes pratiques suivantes lors de la création et de l'implémentation de services :
• Définissez les conventions de désignation de vos services. Tenez compte des points suivants :
◦ Indiquez un nom et une description logiques et explicites pour le service.
◦ Utilisez une nomenclature standard entre les services. Par exemple, faites précéder le nom du service d'un verbe et d'une description du service. Voici quelques exemples de verbes :
|
Verbe
|
Description
|
|---|---|
|
Get
|
Récupérez des valeurs de la base de données.
|
|
Set
|
Définissez la valeur des entrées de la base de données.
|
|
Query
|
Renvoyez un groupe d'enregistrements de la base de données.
|
|
Add
|
Ajoutez des enregistrements à la base de données.
|
|
Update
|
Mettez à jour les enregistrements de la base de données.
|
|
Delete
|
Supprimez des enregistrements de la base de données.
|
|
Validate
|
Validez des enregistrements dans la base de données.
|
|
Purge
|
Purgez les enregistrements de la base de données.
|
|
Create
|
Créez un ensemble d'enregistrements dans la base de données.
|
|
Import
|
Importez des données dans la base de données.
|
|
Export
|
Exportez des données de la base de données.
|
|
Parse
|
Analysez les données.
|
Par exemple : pour un service qui récupère des données historiques, il est recommandé d'utiliser le nom getHistory plutôt que History.
◦ Evitez les noms ambigus.
◦ Evitez autant que possible les noms de service étendus.
Pour plus d'informations, consultez la rubrique
Noms des entités.
• Groupez des propriétés et des services communs dans une seule entité, de préférence une forme d'objet.
• Dans la mesure du possible, implémentez des services sur des formes d'objet.
|
|
Il est recommandé d'utiliser des formes d'objet pour définir les propriétés et les services. Si vous définissez des propriétés et des services sur un modèle d'objet, il est difficile de transférer leurs définitions vers une forme d'objet.
|
• Concevez des services pour différentes couches comme une interface utilisateur, une logique applicative et une récupération des données. Les services de différentes couches ont des responsabilités différentes. L'image suivante fournit un exemple des responsabilités des différentes couches :
• Lors de l'écriture d'un service, essayez de réutiliser les extraits de code disponibles dans la bibliothèque d'extraits de code ThingWorx. Si vous ne savez pas comment utiliser l'un des extraits de code, testez-le avant de l'utiliser dans votre service.
• Lorsque vous créez votre service avec une sortie JSON, notez les points suivants :
◦ Si les propriétés comportent des valeurs null ou undefined, elles ne sont pas renvoyées dans le résultat.
Par exemple :
var test = {
test1: "aaa",
test2: 123,
test3: null,
test4: undefined
};
var result = test;
test1: "aaa",
test2: 123,
test3: null,
test4: undefined
};
var result = test;
Sortie : {"test1": "aaa", "test2": 123}
◦ Si la propriété est un objet JSON et qu'elle est définie sur null, elle est renvoyée dans le résultat.
Par exemple :
var test = {
test1: "aaa",
test2: 123,
test3: null,
test4: undefined,
"line_categories": [ null ]
};
var result = test;
test1: "aaa",
test2: 123,
test3: null,
test4: undefined,
"line_categories": [ null ]
};
var result = test;
Sortie : {"test1": "aaa", "test2": 123, "line_categories": [ null ]}
• Si vous pensez que l'exécution du service peut prendre un certain temps, assurez-vous que l'utilisateur ne puisse pas le déclencher plus d'une fois en même temps.
• Si le service est basé sur un déclencheur d'événements dans une application composite, utilisez l'événement ServiceInvokeCompleted pour autoriser le flux de données dans une application.
• Pour actualiser les données dans les applications composites, il est recommandé d'utiliser un widget Actualisation automatique ou le service GetProperties.
Si une application composite utilise le service GetProperties et que le navigateur prend en charge les WebSockets, le serveur transmet automatiquement et en temps réel au navigateur les valeurs des propriétés mises à jour. Dans ce cas, il n'est pas nécessaire d'utiliser le widget Actualisation automatique. Cette fonctionnalité n'est disponible que si vous cochez la case Mettre à jour automatiquement les valeurs du panneau des propriétés du service.
Si vous utilisez le widget Actualisation automatique, PTC recommande de le définir sur une valeur minimale de 15 secondes pour ne pas surcharger votre système.
| | N'utilisez pas de service de temporisation côté serveur, car cela peut bloquer d'autres services et entraîner ainsi un plantage de l'application. |
• Pour les conversions simples au moment de l'exécution, il est recommandé d'utiliser le widget Expression plutôt que des services.
Par exemple, si vous affichez la température en degrés Celsius (°C) et que vous souhaitez que l'utilisateur puisse la voir en degrés Fahrenheit (°F), utilisez le widget Expression.
• Ajoutez des contrôles à votre code pour que l'utilisateur final ne rencontre aucune erreur.
Par exemple, si votre code a besoin de quelques paramètres d'entrée pour s'exécuter, créez des contrôles pour vous assurer que ces paramètres d'entrée ne sont pas nuls lors de l'exécution du service.
• Si votre application doit être localisée et si des éléments de l'interface utilisateur contiennent du texte qui change dynamiquement en fonction du résultat des services, assurez-vous de ne pas coder en dur les valeurs de texte de vos services qui seront affichés dans l'application composite. Cela est dû au fait que le résultat des services renvoyant le texte doit être localisé. Cela facilite également la gestion et la modification du texte de l'interface utilisateur.
• Lors de la création de services personnalisés, déterminez les utilisateurs ou groupes d'utilisateurs autorisés à appeler ce service. Pour plus d'informations, consultez la rubrique
Sécurisation des applications conçues sur ThingWorx Platform à l'aide de la visibilité et des autorisations.
• L'exécution des services peut potentiellement créer des entités fantômes. Celles-ci sont créées dynamiquement par code/script, plutôt que par ThingWorx Composer. La création d'entités fantômes est une mauvaise pratique. Pour plus d'informations, consultez le document anglais
Detection, Removal and Prevention of Ghost Entities in ThingWorx (Détection, suppression et prévention des entités fantômes dans ThingWorx).
Si des entités fantômes sont créées, vous pouvez les éliminer de l'une des manières suivantes :
◦ Redémarrez le serveur ThingWorx. La mémoire JVM est rechargée à partir des données persistantes et les entités fantômes sont exclues.
◦ Utilisez l'extension de nettoyage des entités fantômes. Vous pouvez la télécharger sur
PTC Marketplace.
◦ Utilisez à la place le mécanisme try-catch pour supprimer des entités fantômes. Pour plus d'informations, consultez la rubrique
Exemple : création et suppression d'entités fantômes.
• Par défaut, le délai d'expiration des scripts sur ThingWorx Platform est de 30 secondes. Dès lors qu'un script s'exécute plus longtemps que cette durée par défaut, la plateforme met fin à l'exécution. L'administrateur ThingWorx peut configurer le délai d'expiration des scripts dans la section des paramètres de base du fichier platform-settings.json.
Bonnes pratiques en matière de test de services
Utilisez les bonnes pratiques suivantes lors du test des services :
• Testez votre service de manière incrémentielle à mesure que vous le concevez. Utilisez les messages de l'enregistreur de scripts, le cas échéant.
| | Tout service comportant une boucle infinie peut faire planter le serveur ThingWorx. |
• Lors du test d'un service, recherchez dans les journaux les éventuels messages d'erreur. Cela s'avère particulièrement utile pour les services dans les abonnements. Les fichiers journaux suivants sont utiles :
◦ ErrorLog.log : fournit un traçage détaillé des erreurs de la pile.
◦ ScriptErrorLog.log : fournit des informations sur le contexte de service (numéro de ligne des erreurs de la pile).
Les erreurs ne sont consignées dans ce fichier que si vous cochez la case Activer le traçage de la pile de script dans l'onglet Configuration du sous-système LoggingSubsystem.
| | Les fichiers ci-dessus sont disponibles dans le dossier ThingworxStorage/logs. Vous devez accéder au serveur ThingWorx pour lire ces fichiers. |
• Si le service est appelé à partir d'une application composite, testez-le dans Composer et dans l'application composite.
• Si des entrées utilisateur sont requises pour l'exécution du service, vous pouvez utiliser le widget Validateur.
• Utilisez les outils de développement disponibles dans les navigateurs pour vérifier le résultat d'un service. Cette opération est utile lorsque vous souhaitez déboguer une séquence de services qui s'exécute dans une application composite. Cet outil affiche les résultats du service dans le contexte de cette exécution spécifique.
Conseils
• Si vous souhaitez rechercher des services, n'ouvrez pas l'entité en mode Edition. Utilisez le lien de prévisualisation à gauche du nom de l'entité pour ouvrir l'entité en mode Affichage.
Autres points à prendre en compte
• Sécurité
◦ Pour améliorer la sécurité, utilisez les remplacements de service pour refuser des autorisations sur les services critiques disponibles sur la plateforme.
• Mises à niveau
◦ Utilisez les bonnes pratiques de codage et ne créez pas des services monolithiques volumineux.