• Hilfe
• Links
• Impressum
• Nutzungsbedingungen
• Datenschutzhinweise

• Überblick
• Aktuell
• Archiv
• Visualisierung
• WMS
• WFS
• Dateizugriff
• FAQ

• User's Guide
• Dokumentation
• WSDL
• Demo

PEGELONLINE Webservice-Archiv Dokumentation

• Überblick
• Authentifizierung und Autorisierung
• SSL
• Webservice-Clients für Apache Axis 1.4 und JWSDP 2.0
• Abfragen
  • Abfrage getZeitreihenInfo
  • Abfrage getZeitreihenData
• Datentypen
  • Datentyp ZeitreiheInfo
  • Datentyp ZeitreiheData
  • Datentyp Messstelle
  • Datentyp Parameter
  • Datentyp Zeitebene
  • Datentyp Gewaesser
  • Datentyp Datenverfuegbarkeit
  • Datentyp Pegelnullpunkt

Überblick

Über PEGELONLINE Webservice-Archiv können archivierte Zeitreihen aus PEGELONLINE bezogen werden. Dies umfasst sowohl bestimmte Metadaten der Zeitreihen (siehe Abfrage getZeitreihenInfo), als auch die Zeitreihendaten selbst (siehe Abfrage getZeitreihenData). Es werden Daten des bundesweiten gewässerkundlichen Messstellennetzes in einem Zeitraum von mehreren Jahrzehnten zur Verfügung gestellt. Die Webserviceabfragen können grundsätzlich nur über das SSL-Übertragungsprotokoll angesprochen werden (siehe SSL-Abschnitt). Weiterhin können optional Authentifizierungsangaben bei jedem Request übermittelt werden, um weitere Zeitreihen freizugeben. Die Abfrage getZeitreihenData kann nur mit Authentifizierung verwendet werden (siehe Authentifizierung und Autorisierung). Webservice-Clients müssen daher zwingend mit SSL auf PEGELONLINE Webservice-Archiv zugreifen und optional Authentifizierungsangaben übermitteln. Hinweise zur Konfiguration finden sich in den entsprechenden Abschnitten.

Der SOAP-basierte Webservice ist über die URL

https://www.pegelonline.wsv.de/archiv/webservices/PegelonlineWebserviceArchiv

im Internet verfügbar.

Der namespace von PEGELONLINE Webservice-Archiv ist
https://pegelonline.wsv.de/webservices/archiv/version1_0/2007-05-14.

Kommunikationsprotokoll ist SOAP 1.1 RPC über HTTP POST; Übertragung der Datenstrukturen findet als "wrapped/literal" statt.

Implementation mit Jakarta Tomcat 4.1.30 (Servlet Container) und Apache Axis 1.4 (SOAP Engine).

Die Interoperabilität zu verschiedenen Platformen ist gemäß den Standards WSI Basic Profile 1.1 und WSI Simple SOAP Binding Profile 1.0 der Web Services Interoperability Organization gewährleistet. Eingesetzt werden dazu die Test-Tools der WSI.

Verifizierte Kompatibilität zu folgenden Webservice-Client-Frameworks:

• Apache Axis 1.4
• JWSDP 2.0
• PHP SOAP Extension

APIs für PEGELONLINE Webservice-Archiv können basierend auf Java 1.5 und JWSDP 2.0 oder Apache Axis 1.4 zur Verfügung gestellt werden.

Zeitpunkte werden innerhalb der SOAP-Message gemäß der W3C-XMLSchema-Spezifikation kodiert, immer als UTC- bzw. GMT-Zeit. Wird zum Beispiel im SOAP eine Uhrzeit von 16:00 Uhr kodiert, so handelt es sich dabei um 17:00 Uhr in der mitteleuropäischen Winterzeit, in der Sommerzeit wäre dies 18:00 Uhr.

Die Zeitpunkte aller Messreihen in Pegelonline Webservice-Archiv sowie die Datenverfuegbarkeit sollten als MEZ, also ohne Winterzeit im Client dargestellt werden. Ein UTC-Zeitpunkt wie 14.08.2003 12:00 entspricht dem 14.08.2003 14:00 in Sommerzeit in der MESZ-Zeitzone. Der Bezugszeitpunkt des gemessenen Wertes, wie er auch beim Datenimport sich darstellt, ist allerdings MEZ, also 14.08.2003 13:00. Hierbei handelt es sich nur um ein Problem der Darstellung des Zeitpunkts, der Zeitpunkt selbst, wie er im Webservice abgebildet ist, ist immer eindeutig. In Java z.B. sollte eine Datumsformatierung gewählt werden, mit einer Zeitzone ohne Daylight Saving Time (DST), also nicht 'CET' (auch hier existiert ein DST-Offset) oder die Default-Zone.

Authentifizierung und Autorisierung

PEGELONLINE Webservice-Archiv kann optional mit Authentifizierungsinformationen in Form von Loginname und Passwort verwendet werden. Ohne Authentifizierung können nur Metadaten zur Veröffentlichung freigegebener archivierter Zeitreihen über die Abfrage getZeitreihenInfo bezogen werden. Die Abfrage getZeitreihenData ist ohne Authentifizierung nicht verwendbar.

Loginname und Passwort können über das Kontaktformular bezogen werden. Es können Accounts mit speziell freigegebenen Zeitreihen eingerichtet werden. Weiterhin können über einen 'Proxyuser-Account' alle nur im Intranet freigegebenen Zeitreihen bezogen werden.

Die Übermittelung von Loginname und Passwort erfolgt über Http Basic Authentication. Dabei wird bei jeder Abfrage die Authentifizierungsinformationen mitgesendet. Der Webservice-Client muss entsprechend konfiguriert werden. Ein Client basierend auf Java JAX-RPC muss dazu im Webservice-Stub, welcher den Remotezugriff auf PEGELONLINE Webservice-Archiv durchführt folgende Properties setzen:

stub._setProperty(javax.xml.rpc.Stub.USERNAME_PROPERTY, "meinLoginname");
		stub._setProperty(javax.xml.rpc.Stub.PASSWORD_PROPERTY, "meinPasswort");
		

SSL

PEGELONLINE Webservice-Archiv ist nur über das sichere Übertragungsprotokoll SSL erreichbar. Dadurch wird sichergestellt, dass mit übertragende Authentifizierungsinformationen verschlüsselt werden.

Folgende SSL-Zertifikate der Bundesanstalt für Wasserbau müssen hierbei dem Webservice-Client bekannt gemacht werden:

• https://pki.pca.dfn.de/baw-ca/pub/cacert/g_rootcert.crt
• https://pki.pca.dfn.de/baw-ca/pub/cacert/g_intermediatecacert.crt
• https://pki.pca.dfn.de/baw-ca/pub/cacert/g_cacert.crt

In einer Java-Umgebung muss dazu eine keystore-Datei erzeugt werden oder eine bereits existierende ergänzt werden und die obigen Zertifikate diesem hinzugefügt werden. Dies ist nur dann notwendig, wenn die bereits in den Java Client-Schnittstellen vorhandene keystore-Datei nicht verwendet werden kann (siehe dazu den User's Guide). Zum manuellen Hinzufügen der SSL-Zertifikate siehe die folgenden externe Links:

• kurze Anleitung
• Java JSSE Guide
• Java keytool

Webservice-Clients für Apache Axis 1.4 und JWSDP 2.0

Abfragen

Abfrage getZeitreihenInfo

Beschreibung:
Über diese Abfrage lassen sich Meta-Informationen über die archivierten Zeitreihen beziehen. Sie kann auch als anonymer Webservice-Client verwendet werden (siehe Authentifizierung und Autorisierung). Es wird ein Array von ZeitreiheInfo-Instanzen generiert. Die zurückgelieferte Teilmenge richtet sich nach den übergebenen Parametern und dem Autorisierungsstatus des Webservice-Clients.

Wird für einen Request-Parameter nil übergeben, so wird nach diesem Parameter nicht gefiltert. Die Antwortzeit kann daher unter Umständen durch das zu übertragende Datenvolumen sehr hoch sein (ca. bis zu einer halben Minute).

Die Request-Parameter kmVon und kmBis werden nur bei angegebenem Gewässernamen ausgewertet.

Request-Parameter:

Name	Beschreibung	Datentyp	nil
gewaesserName	Kurzbezeichnung des Gewässers (siehe Gewaesser)	xsd:string	Ja
kmVon	Beschränkung der Zeitreihen auf einen bestimmten Abschnitt eines Gewässers. Analog zu nil kann auch der Wert -9999 angegeben werden. (siehe Messstelle)	xsd:int	Ja
kmBis	Beschränkung der Zeitreihen auf einen bestimmten Abschnitt eines Gewässers. Analog zu nil kann auch der Wert -9999 angegeben werden. (siehe Messstelle)	xsd:int	Ja
messstellenNummer	Nummer der Messstelle (siehe Messstelle)	xsd:string	Ja
parameterName	Kurzbezeichnung des Parameters (siehe Parameter)	xsd:string	Ja
zeitebeneId	Entsprechende ID der Zeitebene Analog zu nil kann auch der Wert -9999 angegeben werden.	xsd:int	Ja

Response:
0 bis n Arrayelemente von ZeitreiheInfo-Instanzen. Sortiert nachfolgend nach Gewaessername, Flusskilometer, Messstellenname, Parametername und Zeitebene.

Abfrage getZeitreihenData

Beschreibung:
Über diese Abfrage lassen sich Zeitreihendaten (z.B. Wasserstands- oder Abflussdaten) beziehen. Der Webservice-Client muss entsprechend autorisiert sein, um diese Abfrage erstens grundsätzlich verwenden zu können und zweitens die entsprechenden Freigaberechte für die angeforderte Zeitreihe besitzen (siehe Authentifizierung und Autorisierung).

Keiner der übergebenen Request-Parameter darf nil sein. Die Parameter messstellenNummer, parameterName und zeitebeneId spezifizieren die Zeitreihe eindeutig. Die Parameter start und ende grenzen den Zeitraum der Daten entsprechend ein.

Zeiträume können abhängig von der über den Request-Parameter zeitebeneId spezifizierten Zeitebene folgende maximale Längen haben. Wird ein größerer Zeitraum über die Request-Parameter start und ende angefordert, so wird diese Abfrage mit einem Fault zurückgewiesen:

• Hochauflösende Werte: 60 Tage
• Tageswerte: 365 Tage
• Monatswerte: 10 Jahre
• Halbjahreswerte: 10 Jahre
• Jahreswerte: 30 Jahre

Request-Parameter:

Name	Beschreibung	Datentyp	nil
messstellenNummer	Nummer der Messstelle (siehe Messstelle)	xsd:string	Nein
parameterName	Kurzbezeichnung des Parameters (siehe Parameter)	xsd:string	Nein
zeitebeneId	ID der Zeitebene (siehe Zeitebene)	xsd:string	Nein
start	Zeitraum-Anfang	xsd:dateTime (Hinweis)	Nein
ende	Zeitraum-Ende	xsd:dateTime (Hinweis)	Nein

Response:
0 bis n Arrayelemente von ZeitreiheData-Instanzen. Die Elemente sind in erster Linie nach der ID des Aggregationstyps (In der Reihenfolge: Mittel-, Minimum-, Maximalwerte) und in zweiter Hinsicht nach dem Zeitpunkt des Wertes sortiert.

Datentypen

Datentyp ZeitreiheInfo

Beschreibung:
Eine ZeitreiheInfo beinhaltet Metainformationen zu einer Zeitreihe. ZeitreiheInfo-Instanzen können über die Abfrage getZeitreihenInfo bezogen werden.

Members:

Name	Beschreibung	Datentyp
bestellbar	Zeitreihe bestellbar ?	xsd:boolean
datenverfuegbarkeit	siehe Datenverfuegbarkeit. Nil wenn keine Daten verfügbar.	tns:Datenverfuegbarkeit
ganglinieUrl	HTTP-URL zur Darstellung einer Ganglinie für Zeitreihe. Nil wenn keine Daten verfügbar.	xsd:string
gewaesser	siehe Gewaesser	tns:Gewaesser
messstelle	siehe Messstelle	tns:Messstelle
parameter	siehe Parameter	tns:Parameter
pegelnullpunkt	siehe Pegelnullpunkt. Nil wenn Messstelle keiner zugeordnet.	tns:Pegelnullpunkt
zeitebene	siehe Zeitebene	tns:Zeitebene

Datentyp ZeitreiheData

Beschreibung:
Eine ZeitreiheData beinhaltet den Wert einer Zeitreihe zu einem bestimmten Zeitpunkt. ZeitreiheData-Instanzen können über die Abfrage getZeitreihenData bezogen werden.

Members:

Name	Beschreibung	Datentyp
aggregationstypId	siehe Hinweis	xsd:int
wert	Wert der Zeitreihe zu einem Zeitpunkt	tns:Datenverfuegbarkeit
zeitpunkt	Zeitpunkt des Zeitreihenwerts	xsd:dateTime

Folgende IDs für Aggregationstypen sind möglich:

• 1: Mittelwerte der jeweiligen Zeitebene
• 2: Minimumwerte der jeweiligen Zeitebene
• 3: Maximalwerte der jeweiligen Zeitebene
• nil: Bei der Zeitebene 'Hochauflösende Werte' gibt es keine Aggregationstyp-Id

Datentyp Messstelle

Beschreibung:
Eine Messstelle beschreibt eine Messstelle/Pegel, der eine Zeitreihe zugeordnet ist.

Members:

Name	Beschreibung	Datentyp
lageAnGewaesser	Relative Position der Messstelle am Gewässerverlauf in Kilometern	xsd:double
nameLang	Lange Bezeichnung der Messstelle	xsd:string
nameSend	Kurze Bezeichnung der Messstelle	xsd:string
nummer	Nummer der Messstelle	xsd:string

Datentyp Parameter

Beschreibung:
Ein Parameter beschreibt die Art der Daten einer Zeitreihe. Dabei kann es sich zum Beispiel um wasserstandsbezogene oder abflussbezogene Daten handeln.

Members:

Name	Beschreibung	Datentyp
nameLang	Lange Bezeichnung des Parameters	xsd:string
nameSend	Kurze Bezeichnung des Parameters	xsd:string

Datentyp Zeitebene

Beschreibung:
Eine Zeitebene beschreibt den zeitlichen Bezug der Daten einer Zeitreihe.

Hierbei kann es sich um folgendes handeln:

• id=1: Hochauflösende Werte (in Minutenabständen gemessen)
• id=2: Tageswerte
• id=3: Monatswerte
• id=4: Halbjahreswerte (noch nicht verfügbar)
• id=5: Jahreswerte

Members:

Name	Beschreibung	Datentyp
id	ID der Zeitebene (siehe oben)	xsd:int
nameSend	Kurze Bezeichnung der Zeitebene	xsd:string

Datentyp Gewaesser

Beschreibung:
Ein Gewaesser beschreibt das Gewässer der Zeitreihe.

Members:

Name	Beschreibung	Datentyp
nameLang	Lange Bezeichnung des Gewässers	xsd:string
nameSend	Kurze Bezeichnung des Gewässers	xsd:string

Datentyp Datenverfügbarkeit

Beschreibung:
Die Datenverfügbarkeit beschreibt den Zeitraum, in dem archivierte Daten in einer Zeitreihe existieren.

Members:

Name	Beschreibung	Datentyp
ende	Ende des Zeitraums	xsd:dateTime
start	Anfang des Zeitraums	xsd:dateTime

Datentyp Pegelnullpunkt

Beschreibung:
Bei einem Pegelnullpunkt handelt es sich um die Höhe der Messstelle der Zeitreihe über Normal-Null. Daten sind relativ bezogen auf diese Höhenangabe.

Members:

Name	Beschreibung	Datentyp
hoehe	Höhe des Pegelnullpunktes in Metern	xsd:double