Appui SIE :Développement de services web ADES/SIE Rapport final BRGM/ RP-55128-FR Décembre 2006
Appui SIE : Développement de services web ADES/SIE Rapport final BRGM/ RP-55128-FR décembre 2006 Étude réalisée dans le cadre des projets de Service public du BRGM 2006 (06EAUA06) Convention MEDD/BRGM 2006 n CV0000178 F. Pasquier Avec la collaboration de L.CHERY, P.LAGARDE et A. MAUCLERC Vérificateur : Nom : LAGARDE Pierre Date : 05/02/2007 Approbateur : Nom : PENNEQUIN Didier Date : 05/02/2007 Original signé Original signé Le système de management de la qualité du BRGM est certifié AFAQ ISO 9001:2000. I M 003 - AVRIL 05
Mots clés : Services web, ADES, Système d Information sur l Eau, SANDRE, qualité des eaux souterraines, point d eau, bancarisation données qualité des eaux souterraines. BRGM, 2006, ce document ne peut être reproduit en totalité ou en partie sans l autorisation expresse du BRGM.
Synthèse Dans le cadre de sa mission de service public sur les eaux souterraines, le BRGM procède à l animation et au déploiement de la banque nationale des données quantitatives et qualitatives sur les eaux souterraines ADES (Accès aux Données sur les Eaux Souterraines), système d information national sur les eaux souterraines. En 2005, le Ministère de l Ecologie et du Développement Durable a fixé un schéma général d architecture général pour le Système d Information sur l Eau SIE (livre vert de l architecture du SIE, Janvier 2005) se basant sur la mise en œuvre de portails de services web. Ce présent rapport liste et décrit l'ensemble des délivrables remis dans le cadre de ce projet, dans le cadre de la convention d'application 2006 MEDD/BRGM n CV0000178. Le BRGM a réalisé une première mise en œuvre de cette architecture dans le cadre d ADES : l ouverture d un service web d accès aux données qualité sur les eaux souterraines présentes dans Ades. Ce document décrit de manière synthétique les modalités d accès à ce service et les principes de fonctionnement qui ont dicté son développement. BRGM/RP -55128 -FR Rapport final 3
Sommaire 1. Objectifs et présentation de l étude...7 2. Schéma de principes...9 3. Contenu du service Web ADES : Monitoring...11 3.1. SERVICE MONITORING DU SANDRE...11 3.2. MISE EN ŒUVRE DANS LE CONTEXTE ADES...11 3.3. LIMITATIONS DE LA MISE EN ŒUVRE BRGM AU REGARD DE LA SPECIFICATION SANDRE...12 3.4. ACCES AU SERVICE MONITORING ADES...12 Liste des annexes Annexe 1 Description technique des services...13 Annexe 2 Schéma de réponse GetCapabilities...29 Annexe 3 Schéma de réponse GetSiteDescription...31 Annexe 4 Schéma de réponse GetData...37 BRGM/RP -55128 -FR Rapport final 5
1. Objectifs et présentation de l étude Le Système d Information sur l Eau piloté par la Direction de l Eau, élabore progressivement une architecture adaptée pour la diffusion des données sur l eau en France. Cette architecture décrite dans le livre vert sur l Architecture du Système d Information sur l Eau (ASIE, janvier 2005) se fonde sur une approche distribuée découplant les services de fourniture de données des services de visualisation de l information. Depuis 2000, dans le cadre d une convention MEDD-BRGM, le BRGM est chargé de la gestion technique (définition, architecture, développement) et de l animation de la banque des eaux souterraines : ADES. Cette banque collecte des données provenant de l ensemble de la France et de la plupart des producteurs d informations qualité et quantité sur les eaux souterraines sur la métropole et les DOM. Il parait tout naturel que ADES, banque intégrée au SIE, se conforte aux nouvelles règles d architecture et propose, progressivement, de compléter son accès Web par un accès sous la forme de services Web. La connaissance de la ressource en eau, de son état et de ses usages est un enjeu majeur pour la politique de l eau, qu il s agisse des actions réglementaires et de planification, ou encore de l information du public ; tous les acteurs de l eau, dont l Etat, ont besoin de disposer de manière pérenne d informations fiables, actualisées et pertinentes. La modernisation du Système d Information sur l Eau a pour objectif de répondre à ces besoins, conformément aux exigences de la directive européenne de 2000 sur la politique de l eau. L objectif est de rendre les données de surveillance des eaux souterraines accessibles par des services web, qui doivent pouvoir être invoqués à partir de sites web (notamment les portails de bassin) ou plus généralement des applications (par exemple pour des traitements locaux). L implémentation de ces services doit être conforme aux spécifications techniques des services ASIE (http://www.sandre.eaufrance.fr/article.php3?id_article=224). Le cadre de l étude a consisté à mettre en œuvre le service Web de recherche et de consultation des données qualité sur les points d eau tel que le SANDRE (Service d Administration Nationale des Données et Référentiels sur l Eau) l a défini. Dans un premier temps le schéma de principes est présenté puis dans une dernière partie le contenu du webservices est résumé avec l information sur son accessibilité. BRGM/RP -55128 -FR Rapport final 7
2. Schéma de principes Le schéma ci-après décrit le principe de la mise en œuvre d un portail de services pour la banque ADES. Ce portail offre un accès à la base de données Ades sans «passer» par l interface Web du site Internet Ades. Si un partenaire développe un outil adhoc, il pourra se constituer son propre site Internet (de bassin, de région, ) ou site multithématique sans dupliquer l information de la base Ades. BD ADES XML Application Partenaires : Portail de bassin Portail multithématique Traitement WISE Dans cette version actuelle, le portail de services est en parallèle du portail Web Ades. Néanmoins, à terme, le portail Web ADES deviendra un «client» du portail de services ADES. BRGM/RP -55128 -FR Rapport final 9
3. Contenu du service Web ADES : Monitoring 3.1. SERVICE MONITORING DU SANDRE Le service web mis en œuvre dans le cadre de ce projet a été défini par le Sandre sous le terme générique «Consultation des données qualité des eaux» [Monitoring]. Un document de spécifications a été publié en version provisoire par le Sandre (version 0.3). Il définit les grandes «fonctionnalités» suivantes : - la recherche d un site de mesure dans le domaine de l eau (superficielle, souterraine et littorale) ; - la visualisation d une fiche descriptive sur ce site de mesure ; - la récupération de métadonnées sur les données qualité disponibles sur un ou plusieurs sites de mesure ; - la récupération des données sur un ou plusieurs sites de mesures données suivant des critères géographiques et thématiques, Le lecteur se reportera à cette spécification pour une analyse détaillée du service Web. 3.2. MISE EN ŒUVRE DANS LE CONTEXTE ADES Le service Monitoring du Sandre a été mis en œuvre par le BRGM uniquement pour la thématique des eaux souterraines pour la consultation des points d eau et des données qualité publiées dans le site public Ades (c'est-à-dire la base de données publique Ades). Les services disponibles sont donc : - la recherche d un ou plusieurs points d eau selon des critères géographiques et thématiques liées aux eaux souterraines ; - la récupération des données contenues dans la fiche Point d eau (piézométrie et qualité) - la récupération des données disponibles par année sur un point d eau ; - la récupération des données sur un point d eau des critères géographiques et thématiques liées aux eaux souterraines. BRGM/RP -55128 -FR Rapport final 11
3.3. LIMITATIONS DE LA MISE EN ŒUVRE BRGM AU REGARD DE LA SPECIFICATION SANDRE Actuellement, le service développé autour d ADES met en œuvre le standard du Sandre avec les limitations suivantes : - Seules les opérations synchrones sont mises en œuvre ; - Le domaine interrogeable est uniquement le domaine des eaux souterraines (code 4) ; - Pour la recherche géographique, seule le système de projection WGS84 (epsg : 4626) est autorisé ; - Les codes Sites sont uniquement des codes BSS (code schemaagency = 3) ; - Les critères de recherche sont limités à la thématique des eaux souterraines, c'est-à-dire les référentiels administratifs (district, bassin) ou référentiels géologiques (masse d eau et BD RHF V1) - Les critères analytiques portent toujours sur le support Eau et le type de prélèvement physico-chimiques. La recherche par famille de paramètres n est pas opérationnelle. 3.4. ACCES AU SERVICE MONITORING ADES Le point d accès Internet au service Monitoring Ades est le suivant : http://services.ades.eaufrance.fr/monitoring/1/ Ce point d accès respecte les règles définies par les spécifications techniques de l architecture du SIE (janvier 2006). Ce point d accès est disponible selon les deux protocoles techniques des web services définis par le Sandre : - un accès en mode REST accessible via http://services.ades.eaufrance.fr/monitoring/1/servicesmonitoring.aspx - un accès en mode SOAP avec la mise à disposition du fichier de découverte du service (wsdl) : http://services.ades.eaufrance.fr/monitoring/1/servicesmonitoring.asmx Le descriptif technique est réalisé dans les annexes 1 à 4 de ce document. 12 BRGM/RP -55128 -FR Rapport final
Annexe 1 Description technique des services La présente annexe reprend les éléments importants de la spécification Sandre : Monitoring en mettant en évidence les adaptations au contexte opérationnel de la banque ADES. 1. Généralites Tous les services décris par la suite sont implémentés pour répondre à une invocation en REST ou en SOAP sans distinction quant au contenu des données transmises en conformité avec les spécifications techniques des services ASIE 1 dans un environnement.net. Pour le protocole SOAP, les services sont implémentés de façon à respecter la normalisation Basic Profile version 1.1 2 du WSI. De plus les opérations présentées respectent les WSDL fournis par le SANDRE Dans la suite, tous les paramètres des opérations présentées sont obligatoires si le contraire n est pas indiqué. Lorsqu un paramètre est erroné l utilisateur est averti de façon précise sur la source de ce qui ne convient pas au service en renvoyant une exception. Les paramètres suivants sont donc toujours exploités lors d un appel en REST pour toutes les opérations aussi bien en GET qu en POST: - Service Chaîne de caractère précisant le service appelé, dans notre cas seule la valeur «SANDRE : Monitoring» est acceptée. Dans le cas contraire une exception 3 de type 1003 est renvoyé. - Request 1 http://www.sandre.eaufrance.fr/article.php3?id_article=224 2 http://www.ws-i.org/profiles/basicprofile-1.1.html 3 La correspondance entre le code des exceptions et leur signification est établie en annexe. BRGM/RP -55128 -FR Rapport final 13
Chaîne de caractère précisant l opération appelée, respectivement «GetCapabilities», «GetSites», «GetSiteDescription», «GetDataAvailability» et «GetData» selon l opération souhaitée. Si l opération n est pas prise en charge par le diffuseur de données une exception de type 1001 est levée. - Version Précise le numéro de version du webservice, dans l état actuel seule la valeur «1.0.0» est acceptée. Dans le cas contraire une exception de type 1002 est renvoyée. Par exemple, http://[...]/servicesmonitoring.aspx?service=sandre:monitoring&version=1.0.0&reque st=getcapabilities L opération «GetCapabilities» est la seule à supporter le mode GET 4, les autres services sont appelés en mode POST. En effet, ceux-ci ayant des paramètres complexes pouvant dépasser la capacité de l URL fournie en GET, on les insère dans des fichiers XML qu on passe ensuite à une requête HTTP POST. 2. Description des opérations 2.1. OPERATION «GETCAPABILITIES» 2.1.1. Description Cette opération sans arguments présente à l utilisateur une description détaillée des opérations supportées par le fournisseur de données via son service «Monitoring» sous la forme d un fichier XML normalisé 5. 2.1.2. Spécificités REST et SOAP En REST, cette opération est appelée par la méthode «GET» du protocole HTTP avec les paramètres décrits précédemment. Pour le protocole SOAP, aucun argument n est nécessaire. Le résultat est normalisé par les WSDL fournis par le SANDRE. 4 Les opérations ne supportent qu un seul mode à la fois, GET ou POST mais pas les deux. 5 Schéma en annexe 14 BRGM/RP -55128 -FR Rapport final
L annexe 2 décrit le schéma de réponse à l opération getcapabilities. 2.2. OPERATION GETSITES 2.2.1. Description Cette opération permet de rechercher un ensemble de sites et de disposer des informations descriptives sur le site en fonction de critères de recherche de type métier ou spatiaux. 2.2.2. Paramètres - domain L utilisateur doit fournir la thématique concernée, dans notre cas seule la valeur «4» est autorisée (Eaux souterraines). - spatialconstraints Ce paramètre optionnel permet d indiquer des critères de recherche spatialisés conformément au schéma suivant : BRGM/RP -55128 -FR Rapport final 15
Pour le rectangle englobant, le système de projection doit toujours être indiqué en «epsg :4326», les éléments «LowerCorner» et «UpperCorner» doivent être des chaînes de caractère contenant deux décimaux séparés par un espaces pour les coordonnées X et Y. Exemple de rectangle englobant sous forme XML: <BBOX> <Envelope srsname="epsg:4326"> <lowercorner>13.0983 31.5899</lowerCorner> <uppercorner>35.5472 42.8143</upperCorner> <Envelope> </BBOX> L opération de recherche est de type ET entre les critères et de type OU au sein d un critère. Les caractères spéciaux suivant peuvent être utilisés : * : Joker.? : Remplacement d un caractère. \ : Caractère d échappement autorisant la signification des deux caractères précédents. - domainconstraints 16 BRGM/RP -55128 -FR Rapport final
Le paramètre optionnel «domainconstraints» permet de définir les critères de recherche métier conformément au schéma suivant : De même que pour le filtre spatial, l opération de recherche est de type ET entre les critères et de type OU au sein d un critère. Les caractères spéciaux «*,?,\» décris précédemment peuvent être utilisés. - outputformat Un seul format de réponse est permis : text/xml il doit être spécifié dans le paramètre «outputformat». - outputschema Le schéma de données à retourné par le fournisseur est spécifié par le paramètre «outputschema». La seule valeur acceptée est http://xml.sandre.eaufrance.fr/ws/monitoring/1/getsiteresponse. 2.2.3. Code erreur possible Code Cause 1005 La BBOX du filtre spatial n est pas valide BRGM/RP -55128 -FR Rapport final 17
1006 Le SRS de la BBOX demandé n est pas «epsg :4326» 1008 La thématique est différente de «4» 1009 Le filtre spatial n a pu être interprété (REST uniquement) 1010 Le filtre métier n a pu être interprété (REST uniquement) 1011 Format de réponse différent de «text-xml» 1012 Valeur d un paramètre non reconnu 1013 Schéma de réponse différent de http://xml.sandre.eaufrance.fr/ws/monitoring/1/getsiteresponse 2.2.4. Réponse du service La réponse au service getsite est conforme au schéma suivant : Ce schéma correspond au schéma de réponse spécifié par le paramètre «outputschema». 18 BRGM/RP -55128 -FR Rapport final
2.3. OPERATION GETSITEDESCRIPTION 2.3.1. Description Cette opération permet à l utilisateur de récupérer la description d un site depuis son code BSS. Les informations retournées sont des informations invariantes sur les points d eau spécifiés. 2.3.2. Paramètres - Domain L utilisateur doit fournir la thématique concernée, dans notre cas seule la valeur «4» est autorisée (Eaux souterraines). - Sites Ce paramètre permet à l utilisateur de spécifier une liste de site pour lesquels il souhaite obtenir des informations selon la schématisation suivante : Par exemple : <Sites> <CdSite schemaagency= 3 >12345678</CdSite> <CdSite schemaagency= 3 >12345679</CdSite> </Sites> Le schéma d identification doit toujours être 3 pour les eaux souterraines 6. On ne permet pas l utilisation de caractères spéciaux pour ce paramètre. 6 Code national attribué pour la BSS/ADES BRGM/RP -55128 -FR Rapport final 19
- outputformat Deux formats de réponse sont permis et spécifiés par ce paramètre optionnel: o o text/xml multipart/x-gzip Ce paramètre sert donc à définir si on souhaite une réponse sous forme compressée ou non. Par défaut on prend «text/xml» comme format. - outputschema Le schéma de données à retourné par le fournisseur est spécifié par le paramètre «outputschema». La seule valeur acceptée est http://xml.sandre.eaufrance.fr/scenario/gwsiteinfo/1. 2.3.3. Erreurs Code Cause 1008 La thématique est différente de «4» 1014 Le paramètre «sites» n a pu être interprété (REST uniquement) 1011 Format de réponse différent de «text-xml» et «multipart/x-gzip» 1012 Valeur d un paramètre non reconnu 1013 Schéma de réponse différent de http://xml.sandre.eaufrance.fr/scenario/gwsiteinfo/1 20 BRGM/RP -55128 -FR Rapport final
2.3.4. Réponse du service La réponse du service est un document XML compressé ou non selon ce que souhaite l utilisateur sous forme d un tableau de byte. Ce tableau est encodé en binaire en base 64 7, la compression utilisée s il y en a une est le GZIP 8. La réponse s appuie sur les schémas XML Sandre sur les eaux souterraines. L annexe 3 décrit le contenu du schéma de réponse. 2.4. OPERATION GETDATAAVAILABILITY 2.4.1. Description Cette opération permet d obtenir les informations sur le nombre de prélèvements et le nombre d analyses sur un ou plusieurs sites pour toutes les années disponibles dans le système d information du fournisseur de service. 2.4.2. Paramètres - domain L utilisateur doit fournir la thématique concernée, dans notre cas seule la valeur «4» est autorisée (Eaux souterraines). - sites Ce paramètre permet à l utilisateur de spécifier une liste de site pour lesquels il souhaite obtenir des informations selon la schématisation suivante : 7 Le schéma correspondant est développé en annexe. 8 http://www.gzip.org/ BRGM/RP -55128 -FR Rapport final 21
Par exemple : <Sites> <CdSite schemaagency= 3 >12345678</CdSite> <CdSite schemaagency= 3 >12345679</CdSite> </Sites> Le schéma d identification doit toujours être 3 pour les eaux souterraines 9. On ne permet pas l utilisation de caractères spéciaux pour ce paramètre. - outputformat Seul le format «text/xml» est permis pour ce paramètre facultatif. - outputschema Le schéma de données à retourné par le fournisseur est spécifié par le paramètre «outputschema». La seule valeur acceptée est : http://xml.sandre.eaufrance.fr/ws/availabledatawater/1. 2.4.3. Code erreurs Code Cause 1008 La thématique est différente de «4» 1014 Le paramètre «sites» n a pu être interprété (REST uniquement) 1011 Format de réponse différent de «text-xml» 1012 Valeur d un paramètre non reconnu 1013 Schéma de réponse différent de http://xml.sandre.eaufrance.fr/ws/availabledatawater/1 9 Code national attribué pour la BSS/ADES 22 BRGM/RP -55128 -FR Rapport final
Réponse du service La réponse du service getdataavailability est conforme au schéma suivant : ShemaAgency vaudra toujours «3» de la même manière que précédemment. De même, le compartiment concerné (TypePrélèvement) vaudra toujours «100» (Physico-chimique). 2.5. OPERATION GETDATA 2.5.1. Description Cette opération permet d obtenir les données ou les informations sur les prélèvements/analyses ou le nombre de prélèvements / d analyses pour un ensemble de sites de mesures selon des contraintes analytiques, temporelles ou des critères métiers. 2.5.2. Paramètres - domain L utilisateur doit fournir la thématique concernée, dans notre cas seule la valeur «4» est autorisée (Eaux souterraines). BRGM/RP -55128 -FR Rapport final 23
- sites Ce paramètre permet à l utilisateur de spécifier une liste de site pour lesquels il souhaite obtenir des informations selon la schématisation suivante : On ne permet pas l utilisation de caractères spéciaux pour ce paramètre. - temporalconstraints Ce paramètre précise les contraintes temporelles que l utilisateur souhaite utiliser comme filtre pour l opération getdata. Les contraintes temporelles se limitent à une date de début des données et une date de fin, selon le schéma suivant : On ne permet pas l utilisation de caractères spéciaux pour ce paramètre. - analyticconstraints Le paramètre analyticconstraints précise les critères de recherche liés aux paramètres selon le schéma suivant : 24 BRGM/RP -55128 -FR Rapport final
L élément TypeDePrelevementBiologique doit toujours prendre la valeur «100» (Physico-chimique). De même CdSupport prendra toujours la valeur «3», sinon aucun résultat ne pourra être trouvé. On ne permet pas l utilisation de caractères spéciaux pour ce paramètre. - domainconstraints Ce paramètre décrit les autres critères de recherches liés aux métiers, selon la schématisation suivante : BRGM/RP -55128 -FR Rapport final 25
L attribut SchemaAgency doit obligatoirement prendre l une des valeurs suivantes : SANDRE SIRET L attribut Role n admet qu une seule valeur possible : «PROD (producteur de données)» On ne permet pas l utilisation de caractères spéciaux pour ce paramètre. - outputformat Deux formats de réponse sont permis et spécifiés par ce paramètre optionnel: o o text/xml multipart/x-gzip Ce paramètre sert donc à définir si on souhaite une réponse sous forme compressée ou non. Par défaut on prendra «text/xml» comme format de réponse. - outputschema Le schéma de données à retourné par le fournisseur est spécifié par le paramètre «outputschema». Seules les deux valeurs suivantes sont acceptées en fonction du type de réponse que l utilisateur souhaite : 26 BRGM/RP -55128 -FR Rapport final
- http://xml.sandre.eaufrance.fr/ws/monitoring/1/getdataavailabilityresponse. - http://xml.sandre.eaufrance.fr/scenario/gwdata/1 La seconde réponse est définie selon les spécifications XML du Sandre sur les eaux souterraines disponibles sur http://xml.sandre.eaufrance.fr/. 2.5.3. Code erreurs Code Cause 1008 La thématique est différente de «4» 1014 Le paramètre «sites» n a pu être interprété (REST uniquement) 1011 Format de réponse différent de «text-xml» et «multipart/x-gzip» 1012 Valeur d un paramètre non reconnu 1013 Schéma de réponse différent de http://xml.sandre.eaufrance.fr/ws/monitoring/1/getdataavailabilityresponse et de http://xml.sandre.eaufrance.fr/scenario/gwdata/1 1015 Contraintes temporelles incorrectes (REST uniquement) 1016 Contraintes analytiques incorrectes (REST uniquement) 1010 Contraintes métiers incorrectes (REST uniquement) 1017 Le traitement n a pas été réalisé pour une raison précisée dans le message d erreur 2.5.4. Réponse du service L opération revoie à l utilisateur une réponse de type DataSites lorsque celui-ci spécifie «http://xml.sandre.eaufrance.fr/ws/monitoring/1/getdataavailabilityresponse» comme schéma de réponse sous forme de tableau de byte en binaire base 64, une fois réinterprétées, les informations de la réponse suivent le schéma suivant : BRGM/RP -55128 -FR Rapport final 27
Lorsque le schéma spécifié est «http://xml.sandre.eaufrance.fr/scenario/gwdata/1», les informations réinterprétées sont de type GWSiteData10 et respectent le schéma décrit en annexe 4 de ce document. 10 Schéma en annexe 28 BRGM/RP -55128 -FR Rapport final
Annexe 2 Schéma de réponse GetCapabilities BRGM/RP -55128 -FR Rapport final 29
30 BRGM/RP -55128 -FR Rapport final
Annexe 3 Schéma de réponse GetSiteDescription BRGM/RP -55128 -FR Rapport final 31
32 BRGM/RP -55128 -FR Rapport final
BRGM/RP -55128 -FR Rapport final 33
34 BRGM/RP -55128 -FR Rapport final
BRGM/RP -55128 -FR Rapport final 35
36 BRGM/RP -55128 -FR Rapport final
Annexe 4 Schéma de réponse GetData BRGM/RP -55128 -FR Rapport final 37
38 BRGM/RP -55128 -FR Rapport final
BRGM/RP -55128 -FR Rapport final 39
Centre scientifique et technique Service EAU 3, avenue Claude-Guillemin BP 6009 45060 Orléans Cedex 2 France Tél. : 02 38 64 34 34