Spécifications techniques pour l`accès aux services web de niveaux

Transcription

Spécifications techniques pour l’accès aux services web de
niveaux d’eau
Version 2.0.3
Septembre 2014
Service hydrographique du Canada
Pêches et Océans Canada
Services web de niveaux d’eau
version 2.0.3
Table des matières
Introduction .................................................................................................................................................................... 3
Accès et aide ................................................................................................................................................................... 3
Adresses .......................................................................................................................................................................... 3
Technologies ................................................................................................................................................................... 3
Méthodes disponibles ..................................................................................................................................................... 4
getStatus ............................................................................................................................................................... 4
getName .................................................................................................................................................................... 4
getInfo .................................................................................................................................................................... 4
getVersion............................................................................................................................................................. 4
getBoundaryDate ................................................................................................................................................. 4
getBoundaryDepth .............................................................................................................................................. 4
getBoundarySpatial ......................................................................................................................................... 4
getDataInfo .......................................................................................................................................................... 5
getMetadata .......................................................................................................................................................... 5
getMetadataInfo ................................................................................................................................................. 7
search ...................................................................................................................................................................... 7
Exemples d’appels à la méthode search ............................................................................................................. 8
interpolate .......................................................................................................................................................... 9
Références .................................................................................................................................................................... 10
Annexe A – Diagramme de classe de la norme WDS .................................................................................................... 11
ResultSet ............................................................................................................................................................. 11
Annexe B – Diagramme de classe de la méthode interpolate du service SPINE .......................................................... 12
ResultSpine ........................................................................................................................................................ 12
DataSpine ............................................................................................................................................................. 13
Annexe C – Les messages d’erreur................................................................................................................................ 14
Page 2 sur 14
version 2.0.3
Introduction
Les trois services web décrits dans ce document permettent un accès direct aux données de niveaux d’eau
acquis et générés par le Service hydrographique du Canada de Pêches et Océans Canada (SHC).
Le service web de prévisions et d’interpolation des niveaux d’eau (communément appelé SPINE) est un
système permettant d’obtenir les niveaux d’eau à une date/heure et à un endroit précis dans le chenal de
navigation du fleuve St-Laurent entre Saint-Joseph-de-la-Rive et le port de Montréal. Ce système s’appuie
sur un modèle de prévisions maintenu par le Service hydrographique du Canada.
Le service web d’observations donne accès aux observations des niveaux d’eau recueillies par un réseau
de marégraphes et de limnimètres, installés le long du fleuve Saint-Laurent, de l’estuaire et du golfe.
Le service web de prédictions donne accès aux prédictions des niveaux d’eau côtiers d’un océan à l’autre
du Canada.
Accès et aide
Ces services web sont ouverts au grand public et ne nécessitent aucune autorisation d’accès spéciale. Si
vous avez des questions supplémentaires, vous pouvez communiquer directement avec le Service
hydrographique du Canada à l’adresse suivante : [email protected]
Veuillez noter que le Service hydrographique du Canada n’offrira aucune information supplémentaire sur
les données « informatives » de température de l’eau, salinité et pression atmosphérique. Les questions sur
les niveaux d’eau seront répondues dans les délais prescrits par les normes de service en vigueur au SHC.
Les conditions météorologiques peuvent engendrer des différences (temps et hauteur) entre les marées
prédites (prédictions) et les marées observées (observations). Ces différences résultent surtout des
variations de la pression atmosphérique, des vents forts soutenus ou des variations du débit d’eau douce.
Adresses
Les points d’entrées des services web sont :



Service web des prévisions : https://ws-shc.qc.dfo-mpo.gc.ca/spine
Service web des observations : https://ws-shc.qc.dfo-mpo.gc.ca/observations
Service web des prédictions : https://ws-shc.qc.dfo-mpo.gc.ca/predictions
Technologies
Les trois services web utilisent SOAP et XML comme protocole de communication et la langue anglaise pour
l’appel des méthodes et l’échange des données. Chacun des trois services possède une description en XML
accessible en langage WSDL (https://ws-shc.qc.dfo-mpo.gc.ca/predictions?wsdl). Cette description est très
utile pour générer automatiquement (par exemple, à l’aide d’outils comme WSDL2Java d’Apache Axis) du
code pour communiquer avec les services. De plus, les services respectent entièrement la norme Web Data
Service WDS établie par l’Observatoire Global du St-Laurent (OGSL). La documentation détaillée de la
norme WDS se trouve à : http://weds.sourceforge.net/cookbook/fr/index.html
Page 3 sur 14
version 2.0.3
Méthodes disponibles
La norme WDS décrit dix méthodes donnant de l’information sur le service lui-même et une méthode pour la
recherche de données. La description détaillée des méthodes et des objets utilisés par celle-ci est disponible
sur le site web de la norme WDS.
Exceptionnellement, le service de prévisions SPINE ajoute la méthode de recherche interpolate décrite
plus bas.
getStatus
Donne le statut du service. Si le service est disponible et fonctionnel, le statut est à « ok », tandis que s’il y a
un problème, le statut est à « error ».
getName
Donne le nom du service.
getInfo
Donne la description du service.
getVersion
Donne la version de la norme WDS utilisée pour le service web.
getBoundaryDate
Donne les limites temporelles du service en UTC (toutes les dates sont en UTC).
Il est important de mentionner qu’une recherche de données effectuée avec des bornes temporelles
excédant les limites temporelles du service ne génèrera pas d’erreur, mais un résultat vide, car aucune
donnée ne respecte les critères temporaux de la recherche.
getBoundaryDepth
Donne la limite de profondeur du service. Tous les services donnent des niveaux d’eau et ceux-ci sont
considérés à la surface à une profondeur de zéro (0.0). Les valeurs sont en mètres.
Le service d’observations est le seul service pour lequel les limites et les valeurs de profondeurs sont
significatives. Les valeurs de température et de salinité de l’eau sont prises sous la surface, rendant les
limites de profondeurs requises lors de leur recherche. Cependant, les valeurs de pression atmosphérique
sont prises au-dessus de la surface et elles ont donc une profondeur de zéro (0.0).
Il est important de mentionner qu’une recherche de données effectuée avec des bornes de profondeur
excédant les limites de profondeurs du service ne génèrera pas d’erreur mais un résultat vide car aucune
donnée ne respecte les critères de profondeur de la recherche.
getBoundarySpatial
Donne les latitudes et longitudes à l’intérieur desquelles il est possible d’interroger le service. Les valeurs
des latitudes et des longitudes sont en degrés décimaux et suivent les règles de la norme ISO 6709 pour ce
qui est du signe (une latitude positive est au Nord et une longitude positive est à l’Est).
Page 4 sur 14
version 2.0.3
Il est encore important de mentionner qu’une recherche de données effectuée avec des bornes spatiales
excédant les limites spatiales du service, ne génèrera pas d’erreur, mais un résultat vide, car aucune donnée
ne respecte les critères géographiques de la recherche.
getDataInfo
Donne la liste des types de données disponibles pour le service ainsi que leur description.
Le service SPINE donne une seule valeur :
spine : prévision de la hauteur du niveau d’eau en mètre
Le service d’observations donne quatre valeurs :
wl : niveau d’eau en mètre au zéro marégraphique (zéro des cartes)
sal : salinité en partie par millier (‰)
temp : température de l’eau en degrés Celcius
atm_pres : pression atmosphérique en millibars
Note : Les données de type environnementales (sal, temp et atm_pres) sont des données auxiliaires,
fournies à titre informatif seulement. Aucun contrôle de la qualité n’est effectué sur ces données et aucune
information supplémentaire ne sera fournie sur celles-ci.
Le service de prédictions donne deux valeurs (en mètre au zéro marégraphique) :
hilo : les niveaux d’eau des marées hautes et marées basses
wl15 : les niveaux d’eau aux quinze minutes ( :00, :15, :30 et :45)
Le service web de prédictions n’offre que les prédictions de niveaux d’eau. Les prédictions reliées aux
arrivées de mascarets (Moncton et Truro) et aux étales de courants (Reversing Falls) ne sont donc pas
disponibles à travers ce service.
Une de ces valeurs doit être fournie comme premier paramètre à la méthode search de son service
respectif.
getMetadata
Donne une liste de métadonnées (informations connexes) du service web accompagnée de leur valeur.
Le service SPINE a six (6) métadonnées :
Nom de la métadonnée
Contact
Language
Name
Abstract
reference_date
max_results
Valeur
Donne l’information sur les personnes à contacter en cas de problèmes
ou à des fins de validation de données.
Donne la langue des différents messages entre le service web et le client.
Donne le nom du service web.
Donne la description du service web.
Donne l’intervalle temporel ayant des données. Toutefois, les extrêmes
temporels définissant les limites du service doivent être accédés via la
méthode getBoundaryDate.
Donne le nombre maximum d’éléments retournés lors d’une requête aux
méthodes search ou interpolate.
Page 5 sur 14
version 2.0.3
Le service d’observations a onze (11) métadonnées:
Valeur
station_id_list
Donne la liste des identifiants des marégraphes disponibles, séparés par
des virgules : 03057,03071,03100,…
station_id_position
Donne la liste des identifiants des marégraphes disponibles ainsi que
leurs latitudes et leurs longitudes séparés par des virgules. Ces trois
valeurs sont englobées par des crochets : [15520,45.5035,73.5525][15540,45.5286667,73.5424444]….
contact
language
name
abstract
reference_date
station_id_name_list
Donne la liste des identifiants et des noms des marégraphes disponibles
séparés par deux points-virgules et englobés par des crochets :
[15520;;Montréal, Jetée no 1][15540;;Montréal, rue Frontenac]…
metadata_selection_accepted
Donne la liste des champs acceptés dans la méthode search afin de
sélectionner les données correspondantes à une certaine valeur : le tout,
séparé par des virgules. Pour plus d’informations, consultez la
documentation des WDS et ciblez le paramètre metadataSelection de la
méthode search.
max_rows
Donne le nombre maximum d’éléments retournés lors d’une requête à la
méthode search.
total_nbr_obs
Donne le nombre total de valeurs dans la base de données.
Le service de prédictions a douze (12) métadonnées:
Valeur
contact
date
Donne la date de mise en service du service web.
language
topic
Donne le sujet du service web.
Page 6 sur 14
version 2.0.3
name
abstract
reference_date
station_id_list
Donne la liste des identifiants des stations disponibles, séparés par des
virgules : 03057,03071,03100,…
station_id_position
Donne la liste des identifiants des stations disponibles ainsi que leur
latitude et leur longitude séparées par des virgules. Ces trois informations
sont englobées par des crochets
: [15520,45.5035,-73.5525][15540,45.5286667,-73.5424444]…
station_id_name_list
Donne la liste des identifiants et des noms des stations disponibles
séparés par des points-virgules et englobés par des crochets :
[15520;;Montréal, Jetée no 1][15540;;Montréal, rue Frontenac]…
metadata_selection_accepted
Donne la liste des champs acceptés dans la méthode search afin de
sélectionner les données correspondantes à une certaine valeur : le tout,
séparé par des virgules. Pour plus d’informations, consultez la
documentation des WDS et ciblez le paramètre metadataSelection de la
méthode search.
max_rows
Donne le nombre maximum d’éléments retournés lors d’une requête à la
méthode search.
getMetadataInfo
Donne une liste avec la description des différentes métadonnées du service.
Il est important de mentionner qu’il y a trois paliers de métadonnées :



Les métadonnées reliées directement au service, accessible par la méthode getMetadata et
décrites par cette méthode.
Les métadonnées qui sont liées au résultat d’une recherche.
Les métadonnées qui sont reliées à chacune des données du résultat d’une recherche.
search
Fais une recherche et retourne un objet ResultSet, les données elles-mêmes, ainsi que diverses
métadonnées reliées à ces résultats (l’objet ResultSet est décrit à l’annexe A).
Cette méthode nécessite une multitude d’informations : un type de donnée, un zone géographique (latitude
minimale et maximale, longitude minimale et maximale), un intervalle de profondeur, un intervalle temporel,
ainsi que l’indice de la première donnée du résultat et le nombre désiré de données, l’indicateur d’inclusion
des métadonnées, la sélection de données basée sur les métadonnées et l’ordre temporel (voir les
exemples plus loin).
Bien que cette méthode soit disponible pour les trois services web, elle est dépréciée (deprecated) pour le
service SPINE, qui utilise plutôt la méthode interpolate pour rechercher les données.
Page 7 sur 14
version 2.0.3
Les données des services d’observations et de prédictions ont les métadonnées suivantes pour aider à
les identifier :

metadata : tableau d’informations connexes à la donnée qui contient :
 station_id : Numéro unique de la station (i.e. : 02985)
 station_name : Nom de la station (i.e. : Rimouski)
 vl : Niveau de validation de la donnée (pour observations seulement)
 0 = donnée invalide, la donnée acquise n’a subi aucun niveau de validation. C’est la
valeur brute donnée par les capteurs du marégraphe.
 1 = donnée vérifiée, la donnée est validée préliminairement selon certains
paramètres de validation comme des valeurs minimum et maximum et un écart
maximum entre les capteurs.
2 = donnée certifiée, les deux niveaux de validation précédents ont été effectués et un algorithme complexe
comparant l’observation avec les prévisions et prédictions permet de certifier cette donnée.Les métadonnées
décrites ci-haut peuvent être utilisées comme valeur au paramètre metadataSelection (c.-à-d.
station_id=02985 ou encore station_name=Rimouski). Des exemples de recherche sont donnés
plus loin.
Il aussi est possible d’utiliser le niveau de validation vl comme paramètre metadataSelection lors d’un appel
à la méthode search, avec en plus, les opérateurs + et - afin d’effectuer une sélection de données de
plusieurs niveaux (i.e vl=1+ ne donnera que les données de niveau 1 et 2).
Exemples d’appels à la méthode search
Service web des prédictions
EXEMPLE 1
search("hilo", 47.5, 47.7, -61.6, -61.4, 0.0, 0.0, "2012-02-01
00:00:00", "2012-02-01 23:59:59", 1, 100, true, "", "asc")
Recherche toutes les marées hautes et basses dans le nord-est des Îles-de-la-Madeleine le
er
1 février 2012 et demande les 100 premières données en commençant par la première
avec les métadonnées sans sélections de métadonnées le tout en ordre croissant de date.
EXEMPLE 2
search("wl15", 47.5, 47.7, -61.6, -61.4, 0.0, 0.0, "2012-02-03
23:43:54", "2012-02-04 00:17:27", 3, 5, true, "", "desc")
Recherche les niveaux d’eau prédits dans le nord-est des Îles-de-la-Madeleines dans la nuit
du 3 février 2012 au 4 février 2012 et demande, en ordre décroissant, les cinq premières
données en commençant par la troisième (données 3, 4, 5, 6 et 7) avec les métadonnées
sans sélections de métadonnées.
Service web des observations
EXEMPLE 1
search("sal", -90.0, 90.0, -180.0, 180.0, 5.0, 50.0, "2012-12-10
14:15:00", "2012-12-10 14:30:00", 1, 1000, true, "", "asc")
Recherche toutes les mesures de salinité prise entre 5 mètres et 50 mètres le 10 décembre
2012 entre 14h15 et 14h30 et donne les 1000 premières valeurs triées en ordre croissant.
Page 8 sur 14
version 2.0.3
EXEMPLE 2
search("wl", -90.0, 90.0, -180.0, 180.0, 0.0, 0.0, "2012-12-10
13:16:00", "2012-12-10 14:16:00", 1, 1, true, "station_id=02985",
"desc")
En supposant être le 10 décembre 2012 à 14h16, donne le niveau d’eau le plus récent à
Rimouski (02985) si celui-ci a été mesuré dans la dernière heure.
EXEMPLE 3
search("wl", 48.4, 48.5, -68.6, -68.5, 0.0, 0.0, "2012-12-10
12:00:00", "2012-12-10 18:00:00", 1, 1000, true, "vl=1+","asc")
Recherche tous les niveaux d’eau à Rimouski durant l’après-midi du 10 décembre 2012 dont
le niveau de validation est 1 ou 2. En remplaçant « vl=1+ », par « vl=2 », l’utilisateur
obtiendrait seulement les données validées de niveau 2.
interpolate
Fait une recherche de prévisions de niveaux d’eau et donne un objet complexe ResultSpine contenant les
données ainsi que diverses métadonnées reliées au résultat (l’objet ResultSpine est décrit à l’annexe B).
Cette méthode exclusive au service SPINE est beaucoup plus simple que la méthode search, ne
nécessitant que trois tableaux en paramètre :



Un tableau de nombres réels pour indiquer la latitude
Un deuxième tableau de nombres réels pour indiquer la longitude
Un tableau de type chaine de caractères pour la date.
Il est important de mentionner que le même indice pour chaque tableau correspond à une même requête.
Page 9 sur 14
version 2.0.3
Références
Pour en savoir plus sur les technologies utilisées dans nos services web, nous vous suggérons les
hyperliens suivants :
SOAP :


http://www.w3.org/TR/soap/
http://en.wikipedia.org/wiki/SOAP
Norme WDS :


http://weds.sourceforge.net/cookbook/fr/index.html
http://weds.sourceforge.net/cookbook/en/index.html
WSDL :


http://www.w3.org/TR/wsdl
http://en.wikipedia.org/wiki/Web_Services_Description_Language
Page 10 sur 14
version 2.0.3
Annexe A – Diagramme de classe de la norme WDS
Extrait du document « WDS Cookbook » (http://weds.sourceforge.net/cookbook/fr/index.html)
ResultSet
Une instance de la classe ResultSet est retournée comme résultat d’une recherche. Cet objet, au centre
du diagramme ci-haut, contient un tableau de données dans sa propriété data de taille size. En plus des
données, un objet ResultSet contient plusieurs autres propriétés :






boundarySpatial : les limites spatiales des données comprises dans le résultat,
boundayDepth : les limites de profondeur des données comprises dans le résultat,
boundaryDate : les limites temporelles des données comprises dans le résultat,
boundaryValue : les limites des valeurs des données elles-mêmes,
status : le statut de la requête
metatada : d’autres métadonnées sur la requête
Pour ce qui des valeurs elles-mêmes, celles-ci sont des instances de la classe Data. Les propriétés
spatialCoordinates, boundaryDepth et boundaryDate indiquent l’emplacement du senseur qui l’a mesuré et
la propriété metadata donne de l’information supplémentaire (voir la section sur la recherche). La valeur de
la donnée est dans la propriété value.
Page 11 sur 14
version 2.0.3
Annexe B – Diagramme de classe de la méthode interpolate du service SPINE
ResultSpine
Une instance de la classe ResultSpine est retournée comme résultat d’une interpolation. Cet objet, au
centre du diagramme ci-haut, contient un tableau de données dans sa propriété data de taille size. En plus
des données, un objet ResultSpine contient :


status : le statut de la requête
metatada : d’autres métadonnées sur la requête
Pour ce qui des valeurs elles-mêmes, celles-ci sont des instances de la classe DataSpine. Les propriétés
coordinates et date indiquent l’emplacement de la mesure et les propriétés metadata et type donnent de
l’information supplémentaire (voir la section sur interpolate). La valeur de la donnée est dans la propriété
value.
Page 12 sur 14
version 2.0.3
DataSpine
Une instance de la classe DataSpine contient les valeurs d’une prévision d’un niveau d’eau et ses
métadonnées :





value : le niveau d’eau en mètre
coordinate : les coordonnées spatiales ramenées au centre du chenal, sur le fleuve Saint-Laurent
date : la date pour laquelle le niveau d’eau est prévu
type : le type de donnée; peut être forecast pour une prévision ou peut commencer par error pour
indiquer une erreur
metadata : les métadonnées sur la prévision, dont age_forecast qui indique l’âge en minute de la
prévision (c’est-à-dire l’écart entre la date de production de la prévision et la date de la demande de
prévision) et precision_index qui donne la marge d’erreur en mètre
Tout autre type ou métadonnée disponible à ce moment n’a pas de valeur significative et sont des espaces
réservés pour des changements futurs.
Page 13 sur 14
version 2.0.3
Annexe C – Les messages d’erreur
S’il y a des erreurs dans une requête à la méthode search ou encore si le service lui-même est en erreur, la
propriété status de l’objet ResultSet pourrait contenir les messages suivants :
Valeur :
Ce que cela signifie :
The web service is currently unavailable.
Please, try later.
Le service web n’est pas disponible dû à des problèmes
de communication avec sa source de données ou pour un
entretien, veuillez réessayer plus tard.
Invalid date format
La date entrée est invalide. Le format requis est le yyyyMM-dd HH:mm:ss en UTC.
Invalid order
Les valeurs acceptées pour
retournées sont asc ou desc.
Invalid datatype
Le type de donnée spécifié dans le paramètre dataname
n’est pas valide. Voir getDataInfo pour la liste des
valeurs.
l’ordre
des
données
S’il y a des erreurs dans une requête à la méthode interpolate du service SPINE ou encore si le service
lui-même est en erreur, la propriété status de l’objet ResultSpine pourrait contenir les messages suivants :
Valeur
The forecast web service
unavailable. Please, try later.
Ce que cela signifie :
is
currently
Le service web n’est pas disponible dû à des problèmes
de communication avec sa source de données ou pour un
entretien, veuillez réessayer plus tard.
error, Out of Date Boundary
Les dates sont en dehors des limites temporelles.
error, Out of Spatial Boundary
Les coordonnées géographiques sont en dehors des
limites spatiales.
error, Wrong date format
La date entrée est invalide. Le format requis est le yyyyMM-dd HH:mm:ss en UTC.
Finalement, les données DataSpine du service SPINE pourraient avoir comme valeur le message suivant :
error, The geographic coordinate must be
closer to the center of the St. Lawrence river.
Les coordonnées géographiques sont dans les bornes
spatiales mais trop loin du chenal du fleuve Saint-Laurent.
Page 14 sur 14

Spécifications techniques pour l`accès aux services web de niveaux

Transcription

Documents pareils

Les métadonnées Modifier les métadonnées des documents

Hydro concept Restauration et entretien des milieux humides et du

Lien - HiSoMA

Livre Vigi + Cinéma/Télévision Musique/Spectacles Contenus

Réaliser une carte avec Géoportail

Qu`est-ce que le PDF/A

ArcView Print Job - Visitez le Grand site des gorges du Tarn, de la

DIRECTIVE CADRE SUR L`EAU INFORMATION, PARTICIPATION

Numérisation de documents