Services web REST (SW REST)
- Bertrand Littel
Elément requis | Version |
|---|---|
Harmony | > Harmony 405 |
IIS | > 7.5 (WServer 2008, W7) |
Comment mettre en oeuvre des services web en mode REST pour permettre a des applications extérieures de communiquer avec l'ERP avec ou sans certificat SSL.
Le service web REST servira au service web standard REST et à l'API RecordSql REST
L'appel en mode REST permet une couche d’authentification et un format de l’enveloppe en JSON.
Installation On Premise
Lancer Harmony, choisir le menu Administration / Installation serveur client léger web
Cocher les cases suivantes et valider
Cette action installe le service REST dans le gestionnaire Microsoft IIS.
Contrôler par le bouton 'Ouvrir la console IIS' la console IIS qui doit permettre de déployer le dossier virtuel DhsDivaltoServiceDivaApiRest
Les objets windows (fichiers DLL) et le paramétrage (fichiers XML) sont installés par exemple dans C:\divalto\Internet\DhsDivaltoServiceDivaApiRest
L'URL est sous la forme http://localhost:8080/DhsDivaltoServiceDivaApiRest/api/v1/WebService/Execute
ou http://localhost:8080/DhsDivaltoServiceDivaApiRest/api/v1/RecordSql/Execute
Gestion de droits windows
Les appels entrants par service web REST passent par une authentification préalable. Le compte utilisateur windows est donc indiqué par l'appelant
Installation Cloud
L'installation en mode cloud est déjà effective.
Chaque environnement dispose de cette fonctionnalité par défaut avec une adresse de connexion dédiée au service :
https://api.divaltocloud.com/[NUMEROSITE]/[ENVIRONNEMENT]/api/v1/
Vous devez substituer [NUMEROSITE] par le numéro de votre site client ainsi que [ENVIRONNEMENT] par le nom de l’environnement que vous souhaitez exploiter.
Ce protocole se base sur des échanges HTTPS au format JSON.
Certificat
Par défaut le dialogue se fait en mode http, mais il est possible de sécuriser avec un certificat pour installer une liaison https. Nécessite un fichier certificat SSL.
Pour passer en certificat SSL, il faut modifier la liaison de la racine de site avec un fichier certificat.
Choisir la racine du site et le modifier les liaisons pour choisir le type HTTPS avec certificat
Cet écran permet de voir les liaisons déjà existantes, par exemple HTTP sur port 8080
Paramétrage REST
Le paramétrage des services web REST se fait dans les fichiers qui sont dans le dossier de travail divalto IIS, par exemple C:\divalto\Internet\DhsDivaltoServiceDivaApiRest
Multi-service
Le service web Rest sait gérer plusieurs environnement, soit via le demandeur, soit via le paramétrage côté serveur. La méthode standard est de passer par le demandeur lors de la phase d’authentification 2 Authentification en indiquant l’environnement souhaité.
Il est aussi possible de configurer plusieurs services web en répliquant les dossiers de travail et dossiers virtuels IIS, de la même manière qu'un service SOAP. Ce sujet est abordé dans les formations d'installation Infinity ou dans le paramétrage SOAP.
Paramétrage du service web RecordSql
Il y a deux fichiers qui permettent le paramétrage système du service web RecordSql natif REST
DhsDivaltoServiceDivaApiRest_ListDHOQ.xml : pour la liste des RecordSql autorisés
DhsDivaltoServiceDivaApiRest_ParamERP : n'est pas exploité pour le moment
Voir le chapitre concernant le service web RecordSql natif REST pour plus de détails.
Paramétrage des services web REST
Il y a deux fichiers qui permettent le paramétrage système des services web REST
DhsDivaltoServiceDivaApiRest_ParamSystem.xml : options système concernant le traitement (cache, debug, sécurité)
DhsDivaltoServiceDivaApiRest_ListENV.xml : n'est pas exploité pour le moment
Le fichier DhsDivaltoServiceDivaApiRest_ParamSystem.xml indique les options du traitement des appels REST.
DhsDivaltoServiceDivaApiRest_ParamSystem.xml
<?xml version="1.0" encoding="utf-8"?>
<params>
<options>
<!-- <debug Value="0" /> -->
<!-- <modelogonuser Value="2" /> -->
<!-- <ReloadCacheUser Value="30" /> -->
<!-- <FreeCacheUser Value="30" /> -->
<!-- <ReloadCacheDHOQ Value="30 /> -->
<!-- <MaxRecordInCount Value="1000" /> -->
<!-- <ReloadCacheDomaineInError Value="5" /> -->
<!-- <LimitValidToken Value="30" /> -->
<!-- <FreeInstanceRecordSQL Value="30" /> -->
<!-- <ControlFree Value="30" /> -->
<!-- <ReloadCacheEnv Value="30" /> -->
<!-- <ReloadCacheDico Value="30" /> -->
<!-- <Domaine Value="xxx" Forcer="0" /> -->
<!-- <Env Value="xxx" Forcer="0" /> -->
</options>
</params>
Les options liées au service web REST en général sont les suivantes
Balise OPTIONS | Description | Valeurs indique celle a utiliser par défaut) |
|---|---|---|
Debug | Mode debug | 0 = sans 1=avec Permet d’écrire des informations de debug dans le fichier EventRest.log stocké dans le chemin DivaltoLog, par exemple c:\divalto\divaltolog\ |
ModeLogonUser | Mode logon | 2 = LOGON32_LOGON_INTERACTIVE 4 = LOGON32_LOGON_BATCH Permet d’indiquer une option dans la fonction LogonUser de windows qui lui indique comment doit se comporter l’impersonation, et en particulier si elle doit être ‘transmise’ au processus sql client qui peut se trouver sur une autre machine. La valeur 4 pour LOGON32_LOGON_BATCH ne fonctionne pas toujours |
ReloadCacheUser | Cache utilisateurs : rechargement | Nombre (minutes) 30 On recherche les paramètres d’un utilisateur toutes les n minutes, pour prendre en compte les modifications des autorisations des applications et des confidentialités |
FreeCacheUser | Cache utilisateurs : libération | Nombre (minutes) 30 On libère le cache d’un utilisateur s’il n’est plus utilisé pendant n minutes |
ReloadCacheDomaineInError | Cache erreur active directory | Nombre (minutes) 5 Quand il y a une erreur sur un utilisateur qui n’existe pas dans active directory, l'information (utilisateur inconnu) est conservée pendant n minutes ce qui permet de ne pas accéder à active directory en permanence. Pemet d'éviter une saturation du serveur REST lors des demandes de token sur des utilisateurs inconnus. |
LimitValidToken | Durée du token | Nombre (minutes) 30 |
Domaine | Authentification : domaine | Nom du domaine suivi de Forcer="0" ou "1" |
Remarque : concernant les délais par défaut proposés à 30 minutes, il s'agit de le faire suffisamment souvent pour actualiser les ressources et les caches, mais pas trop souvent pour consacrer les temps CPU au traitement des demandes de services web et non pas à la relecture et rechargement des paramètres et cache mémoire.
Paramétrage avancé du serveur IIS
Le serveur HTTP Microsoft IIS permet du paramétrage avancé. Consultez la documentation Microsoft en ligne pour plus d'informations.
Limites de taille ou durée des requêtes
Il y a notamment la possibilité de modifier les limites de traitements des requêtes HTTP dans le fichier WEB.CONFIG situé dans le dossier de gestion IIS.
Par exemple C:\divalto\Internet\DhsDivaltoServiceDivaApiRest sur un poste local, dans la section <system.web> sur les attributs de la propriété httpRuntime
maxRequestLength | The property maxRequestLength indicates the maximum file upload size supported by ASP.NET. This limit can be used to prevent denial of service attacks caused by users posting large files to the server. The size specified is in kilobytes. The default is 4096 KB (4 MB) Max. value 2147483647 KB (2 TB). MSDN |
executionTimeout | The executionTimeout attribute defines the maximum amount of time in seconds that a request is allowed to run before it is automatically terminated by ASP.NET. The default value is 90 seconds. |
Une autre méthode est décrite ici Request Limits <requestLimits> et consiste à ajouter à ajouter une section <security> et à mettre en oeuvre les requestLimits via l’attribut maxAllowedContentLength
Pré-chargement et pré-actif
Il est possible de paramétrer l'application IIS en "Préchargement" (preloadEnabled) et aussi en toujours actif (AlwaysRunning)
Cela consomme des ressources complémentaires (mémoire) mais éviter le temps de "réveil" du WebService
C'est un sujet MS Windows (indépendant d'Harmony), mais qui permet de petits gains pour les "premiers" appels aux WebServices