Scripts REST

REMARQUE

Le sujet suivant peut contenir des références aux fonctionnalités de script personnalisées de la gamme de produits IndySoft. Il se peut que certains aspects des fonctionnalités évoquées ne soient pas accessibles aux clients finaux. À titre indicatif, les fonctionnalités concernées porteront la mention « script » ou « script personnalisé ».Pour plus d'informations sur les scripts personnalisés, ainsi que sur leur mise en œuvre et leur prise en charge au sein du produit, consultez la rubrique « Présentation des scripts personnalisés ».

Notez également que l'utilisation de scripts REST pour accéder à la base de données IndySoft via le Web nécessite l'enregistrement du produit « IndySoft REST Scripting » dans le module d'enregistrement IndySoft. Pour plus d'informations, veuillez contacter le service commercial d'IndySoft. Si « IndySoft REST Scripting » a été enregistré en tant que produit (à l'aide de l'utilitaire d'enregistrement IndySoft), l'onglet « REST Scripts » permet de modifier les scripts et de configurer le service REST IndySoft correspondant. Les scripts REST permettent d'accéder à la base de données IndySoft via des scripts Web. Cette fonctionnalité repose entièrement sur les scripts créés et gérés dans cet onglet. REST est simplement un modèle architectural pour les requêtes et les réponses HTTP. Si le serveur REST IndySoft est en cours d'exécution et qu'un ou plusieurs scripts REST ont été créés, IndySoft peut alors surveiller certaines requêtes HTTP et y répondre en conséquence via ce service.

Voici un exemple très simple. Imaginons que vous soyez propriétaire du domaine myurl.com et que vous souhaitiez autoriser une requête Web spécifique à renvoyer la date d'échéance de l'étalonnage d'un équipement donné. (C'est un exemple très simple !) Tout d'abord, vous devriez configurer un script REST qui se déclencherait en réponse à des requêtes HTTP spécifiques. Ce script lirait les paramètres requis dans chaque requête, puis générerait une réponse HTTP. Le nom du script correspondrait à la partie finale de l'URL dans la requête. Vous devrez ensuite installer/exécuter le service REST IndySoft (en le configurant pour qu'il pointe vers votre domaine myurl.com fonctionnant sur un port spécifique, etc. Les scripts REST d'IndySoft permettent d'accéder à toutes les propriétés des requêtes HTTP (URL, port, adresse IP, etc.), au type de requête (« GET », « POST », « PUT », « DELETE »), à tous les en-têtes, à tous les paramètres de requête et au corps du message (sous forme de texte ou de données binaires). Des fonctions de script spécifiques permettent de renvoyer chacune d'entre elles. Dans notre exemple, supposons que la requête Web côté client soit entièrement définie dans l'URL (aucun corps de message n'est nécessaire dans cet exemple) :

http://myurl.com:9001/IndyScripts/ReturnDueDate?Company=ABC+COMPANY&Id=ABC123

D'après l'URL de l'exemple ci-dessus, on constate que notre serveur REST IndySoft fonctionne via HTTP (et non HTTPS), que le domaine sur lequel il est configuré est myurl.com, et que l'URI relative (telle que configurée lors de l'installation) est « IndyScripts ». Le nom du script appelé est « ReturnDueDate ». Enfin, deux paramètres de requête sont transmis : « Company » et « Id ». Seules les requêtes HTTP envoyées à « [http://myurl.com:9001/IndyScripts] » (http://myurl.com:9001/IndyScripts&#39;) seront transmises au serveur REST d'IndySoft. De plus, seules les requêtes suivies (dans l'URL) d'un nom de script permettront d'exécuter ce script, comme dans l'exemple « [http://myurl.com:9001/IndyScripts/ReturnDueDate] » (http://myurl.com:9001/IndyScripts/ReturnDueDate&#39;) qui exécute le script « ReturnDueDate ». Enfin, le script lira les paramètres de requête (ainsi que d'autres informations, si nécessaire) et répondra en conséquence. Voici un exemple de script de serveur REST :

sCompany = RequestQueryParameter("Company")

sID = RequestQueryParameter("Id")

if tdDoSQLRecords(1, "SELECT SCHED_DUE_DATE FROM SCHEDGI WHERE COMPANY = '" & sCompany & "' AND GAGE_SN = '" & sID & "' AND SCHED_TYPE = 'CALIBRATION'") then

sDueDate = tdFieldbyNameAsString(1, "SCHED_DUE_DATE")

ResponseStatusCode(700)

ResponseBodyAsText(sDueDate)

Else

sDueDate = ""

ResponseStatusCode(800)

ResponseBodyAsText(sDueDate)

End If

Voici donc un exemple très simple. Le script lit les paramètres de requête de l'URL pour « Company » et « Id ». Notez que les symboles codés en pourcentage sont automatiquement remplacés par la fonction RequestQueryParameter (« ABC+COMPANY » est renvoyé sous la forme « ABC COMPANY »). Si une date d'échéance d'étalonnage est trouvée pour cet équipement, cette date est renvoyée sous forme de texte, accompagnée d'un code de réponse HTTP 700. Si aucune date d'échéance n'est trouvée, un texte vide et un code de réponse HTTP 800 sont renvoyés. Dans la plupart des langages de programmation, la réponse serait une page HTML complète. Ou bien, la réponse comporterait un fichier XML dans le corps du message de réponse, fournissant plus de détails sur la transaction effectuée. Mais voilà l'essentiel : envoyer une requête HTTP vers une URL + une URI relative + un script + des paramètres facultatifs. Ajoutez à cette requête des en-têtes facultatifs et/ou le corps du message. Le script serveur répond aux requêtes valides, lit les détails du message et envoie une réponse appropriée. Les réponses HTTP comprennent un code de réponse et un corps de message sous forme de texte ou de données binaires. Le client HTTP doit être capable de réagir en conséquence (si la réponse est un fichier HTML, celui-ci s'affichera ; si le corps du message contient un fichier PDF, celui-ci s'affichera, etc.)

Configuration d'IndySoftRESTServer
La première étape (après avoir enregistré « IndySoft REST Scripting » dans l'utilitaire d'enregistrement IndySoft) consiste à configurer le service IndySoft REST sur votre serveur web. Ce service répondra à toutes les requêtes Web concernant ce domaine. Pour ouvrir l'écran de configuration, cliquez sur le bouton « IndySoftRESTServer Setup » situé au-dessus de la grille des scripts REST :

Configuration d'IndySoftRESTServer

Paramètres du serveur REST IndySoft

Cette boîte de dialogue permet d'installer ou de désinstaller le service REST IndySoft, de démarrer ou d'arrêter le service, ainsi que de saisir et d'enregistrer tous les paramètres associés. IMPORTANT : des droits d'administrateur Windows seront nécessaires si cette boîte de dialogue est utilisée pour installer ou désinstaller le service, ou pour réserver automatiquement un espace de noms pour l'hôte ou l'URI. Veillez à fermer puis à redémarrer IndySoftSyncOptions.exe en sélectionnant « Exécuter en tant qu'administrateur » dans Windows avant de continuer.

·Installer le service / Désinstaller le service : le bouton situé en haut de la boîte de dialogue permet d'installer ou de désinstaller le service, selon le cas. Veuillez noter que des droits d'accès Windows appropriés sont nécessaires pour effectuer cette opération. Une fois installé, vous verrez ce service apparaître dans la liste des services Windows sous le nom « IndySoft REST Server ». Une fois l'installation ou la désinstallation terminée, la boîte de dialogue se fermera. Remarque : pensez à vérifier les « Paramètres avancés » avant d'installer le service. Une fois installé, le service peut être démarré ou arrêté à l'aide des boutons situés en bas de la boîte de dialogue. Bien sûr, ce service peut également être arrêté ou démarré directement depuis les Services Windows.

·Port utilisé : indiquez le port souhaité pour le service REST IndySoft. Ce port peut être indiqué dans la requête HTTP après le nom de domaine, suivi d'un deux-points (voir l'exemple dans la boîte de dialogue).

·Utiliser HTTPS : cochez cette case si vous préférez les requêtes HTTPS plutôt que HTTP. Si le protocole HTTPS est utilisé, un certificat doit être fourni. Une fois les paramètres enregistrés (lorsque vous cliquez sur OK), IndySoft vous invitera automatiquement à sélectionner un certificat via Windows. Ce processus se déroulera lorsque IndySoft tentera d'enregistrer l'hôte spécifié.

·Hôte : saisissez le nom de domaine de votre hôte pour ce serveur.Remarque : une fois les paramètres enregistrés (lorsque vous cliquez sur le bouton OK), IndySoft tentera d'enregistrer automatiquement cet espace de noms URL. Le serveur REST IndySoft repose sur hHTTPsys en mode noyau, ce qui signifie que le système d'exploitation traite toutes les requêtes HTTP. Dans cette architecture, le noyau transfère les requêtes HTTP en fonction de l'URL demandée. Pour que cela fonctionne, nous devons d'abord réserver un espace de noms d'URL. La réservation d'espace de noms attribue les droits sur une partie de l'espace de noms des URL HTTP à un groupe spécifique d'utilisateurs Windows. Une réservation donne à ces utilisateurs le droit de créer des services qui écoutent sur cette partie de l'espace de noms. Supposons donc que, selon les paramètres définis dans cette boîte de dialogue, votre serveur soit accessible à l'adresse « [http://myurl.com:9001/IndyScripts/] » (http://myurl.com:9001/IndyScripts/&#39;). Dans ce cas, IndySoft tentera de réserver cet espace de noms afin de s'assurer que Windows accepte les requêtes HTTP adressées à ces adresses au lieu de les refuser. Si vous devez configurer ces règles manuellement, demandez l'outil IndyHTTPConfig.exe auprès du service d'assistance d'IndySoft. Notez que cet outil IndyHTTPConfig.exe est déjà inclus dans le serveur d'applications à trois niveaux (si ce service est installé sur le même serveur).

·URI relative : saisissez le nom de l'URI relative. Il s'agit de la partie de l'espace de noms qui suit l'hôte ; par exemple, la partie « IndyScripts » de l'URL complète « http://myurl.com:9001/IndyScripts/ScriptNameHere »

·Exemple : ce texte en lecture seule ajoute les quatre paramètres ci-dessus au format requis lors de l'envoi de la requête client. Notez que la partie finale de l'URL comprendra une référence au script spécifique (suivie d'éventuels paramètres de requête facultatifs). Le petit bouton situé à droite de cette zone de saisie ouvrira l'URL indiquée. Votre navigateur par défaut traitera la requête. Remarque : ce lien web n'est pas nécessairement complet ; étant donné que des paramètres de requête supplémentaires ou un corps de message sont généralement requis, il ne s'agit là que d'un point de départ.

·Connexion au serveur : le serveur REST IndySoft exécute les scripts via une connexion client à la base de données. Cela signifie que certains paramètres, comme ceux relatifs aux e-mails, s'adapteront aux paramètres de l'utilisateur et à sa localisation. C'est pourquoi il est important de définir un nom d'utilisateur qui sera utilisé pour charger ces paramètres au démarrage du serveur REST IndySoft. L'emplacement par défaut de cet utilisateur sera utilisé.

·Préchargement des scripts : lorsque cette case est cochée, tous les scripts sont préchargés en mémoire au démarrage du serveur REST IndySoft. Cela permet une exécution légèrement plus rapide de chaque requête Web. L'inconvénient est que si le script est modifié (à partir de l'utilitaire IndySoft DataSync... Scripts REST), il faudra arrêter puis redémarrer le service pour que les modifications apportées aux fonctionnalités prennent effet. Si cette case n'est pas cochée, le script est chargé depuis la base de données à chaque requête.

·Enregistrer toutes les requêtes : cette option n'est généralement activée que lors du débogage d'un nouveau script. Lorsque cette option est activée, toutes les demandes sont enregistrées dans l'onglet « Historique / Statut ». Le journal des requêtes contiendra une liste complète de toutes les propriétés, en-têtes, paramètres de requête et corps de message disponibles pour consultation dans le script. Les valeurs seront consignées dans le journal dans le même format que celui utilisé pour les référencer (si nécessaire) dans le script.

·Paramètres avancés : vous pouvez utiliser cette boîte de dialogue pour définir les dépendances et les informations d'identification du service. Remarque : ces paramètres ne s'appliqueront au service qu'au moment de l'installation

·Démarrer/Arrêter le service : utilisez les deux boutons situés en bas à gauche de la boîte de dialogue pour démarrer ou arrêter le serveur REST IndySoft.

Grille des scripts REST
Ajouter/Modifier/Supprimer un script REST : utilisez ces options pour ajouter, modifier ou supprimer un script REST. Ces options ne sont disponibles que si « IndySoft REST Scripting » est un produit enregistré. Sinon, le système vous demandera un code de réponse que seul le service d'assistance IndySoft est en mesure de vous fournir.

Imprimer le tableau des scripts REST - Utilisez cette option pour imprimer rapidement le tableau actuel répertoriant les scripts REST.

Afficher uniquement le script REST - Utilisez ce bouton pour consulter le script REST actuellement sélectionné sans pouvoir le modifier. Cette option est utile si vous ne disposez pas des droits de modification mais que vous devez vérifier le bon fonctionnement du script sélectionné.

Importation / Exportation de script REST - Utilisez ces options pour importer un script REST à partir d'un fichier zip (tel qu'il a été précédemment exporté via l'option d'exportation) ou pour exporter le script actuellement sélectionné vers un fichier zip.

Configuration du serveur REST IndySoft - Utilisez cette option pour ouvrir la boîte de dialogue des paramètres du serveur REST.

Ajouter/modifier un script REST
·Nom du script - Le nom unique du script REST. Ce nom apparaîtra dans l'historique des journaux ainsi que dans tous les e-mails envoyés depuis le script ou en réponse à des erreurs de script.

·Actif - Indique si le script est chargé/exécuté par le service REST IndySoft. Le script ne peut être testé à partir de l'écran IndySoftSyncOptions que si cette case n'est pas cochée.

·VBScript/Pascal - Chaque script peut être écrit en syntaxe VBScript ou Pascal

·Nom encodé (pour l'URL) - Le nom du script (« Nom du script » à gauche) doit être utilisé pour appeler ce script à partir d'une requête HTTP Web. Si le nom du script contient des caractères qui ne peuvent pas être saisis dans une URL, il faut alors utiliser la version encodée du nom du script (comme indiqué automatiquement ici). Par exemple, le nom de script « WEB SCRIPT » serait encodé sous la forme « WEB%20SCRIPT » dans une URL.

·Description - Une description plus détaillée du script

·Erreurs du script à envoyer à - Ce champ peut contenir une ou plusieurs adresses e-mail. Ces personnes recevront automatiquement un e-mail si le script génère une erreur lors de son exécution. Notez que ces erreurs sont liées à la compilation du script et ne proviennent pas nécessairement du script lui-même, où elles auraient pu être interceptées. Par exemple, si le script contient des erreurs de syntaxe, ces adresses e-mail seront averties (car le script ne peut pas être compilé). Mais si votre script charge, par exemple, un fichier XML et que ce fichier XML présente un format incorrect qui renvoie un code d'erreur, la logique de votre script peut ou non réagir à ce code d'erreur : cela dépend de l'auteur du script. Ainsi, si votre script détecte ce code d'erreur, vous pouvez appeler la fonction SendEMail depuis le script pour répondre à cette erreur. Si vous souhaitez renvoyer ces adresses « Send Errors To » depuis le script, utilisez la fonction SendScriptErrorsTo.

À droite du script se trouve un onglet « Procédures/Fonctions » qui présente aux utilisateurs les procédures et fonctions disponibles. Les utilisateurs peuvent glisser-déposer ces fonctions/procédures dans la zone de script. L'onglet « Journal de débogage » consigne toutes les erreurs de syntaxe détectées lors du test du script. De plus, ce texte « Journal de débogage » peut être rempli avec des notes de débogage provenant du script lui-même, en appelant la fonction DebugLog.

Pour obtenir de l'aide ou consulter les procédures et fonctions de script liées à REST, reportez-vous aux rubriques « Fonctions de script REST » dans la documentation d'aide d'IndySoft Custom Scripting. |