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.

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 Détails 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 Détails 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 Détails 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 Détails 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 Détails 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 Détails Durée de validité d’un token, au delà de ce temps, le demandeur doit refaire une authentification
Domaine	Authentification : domaine	Nom du domaine suivi de Forcer="0" ou "1" Détails On peut définir un domaine par défaut ou bien le forcer Si forcer = 0 alors on prend ce Nom de domaine si l’utilisateur du service web rest n’a pas mis de nom de domaine dans la requête d’authentification Si forcer = 1 alors on prend toujours ce domaine et on ne tient pas compte du domaine que l’utilisateur a mis dans la requête d’authentification Exemple : <Domaine Value="divalto" Forcer="1" /> a pour effet de toujours prendre le domaine "divalto" quelle que soit la valeur du paramètre 'domaine' lors de l'appel API d'authentification

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.

Propagation des environnements

Attention : il faut faire la propagation des environnements après chaque modification d'environnement car le service REST a besoin des chemins pour accéder au différent fichiers (dictionnaires, recordsql, etc)

Il faut donc, depuis le serveur Harmony qui contient le service REST, aller dans le programme de Gestion des environnements, puis sélectionner tous les environnements et faire une propagation.

Ce qui génère un fichier de propagation des environnements

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 https://docs.microsoft.com/en-us/iis/configuration/system.webServer/security/requestFiltering/requestLimits/ et consiste à ajouter à ajouter une section <security> et à mettre en oeuvre les requestLimits via l’attribut maxAllowedContentLength

Services web REST (SW REST)