Server-API: Unterschied zwischen den Versionen

Version vom 16. Oktober 2019, 12:22 Uhr

Die Server-API befindet sich noch in der Entwicklungsphase, Änderungen sind zu erwarten

Die Serverkomponente von Talsim-NG (TalsimNGSrv) bietet eine REST (HTTP) Schnittstelle (API), über die Daten abgerufen und an den Server übermittelt werden können. Daten werden über diese Schnittstelle im XML oder JSON Format ausgetauscht. Im Folgenden wird diese Schnittstelle dokumentiert:

In den unten angegebenen Beispielen wird als Server-Adresse talsim.de verwendet, dies ist mit der Adresse oder IP des tatsächlich verwendeten Talsim-Servers zu ersetzen.

HttpDataSrv

Der HttpDataSrv Service dient zur Abfrage von Daten mit Bezug zum System, Systemvarianten, Listen zu Zeitreihen-Ordnern oder Zeitreihen. Der HttpDataSrv ist standardmäßig über den Port 8090 ansprechbar und bietet die folgenden Schnittstellen:

requestClients

Generelle Abfrage aller Kunden (wird zukünftig in requestCustomers geändert)

Beispiel: http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestClients/|

requestZreDirectories

Abfrage von Zeitreihen-Ordnern:

Beispiel: http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestZreDirectories/Nile,|

requestZreFiles

Abfrage von vorhandenen Zeitreihen:

Beispiel: http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestZreFiles/Nile,hubert,16

requestSystemAndSysVar

Abfrage von Systemen und Systemvarianten

Beispiel: http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestSystemAndSysVar/WFP_SSD,hubert,1

HttpZreSrv

HttpZreSrv ist der zentrale Service zur Interaktion mit Zeitreihen. Der HttpZreSrv ist standardmäßig über den Port 8092 ansprechbar. Es gibt folgende Schnittstellen, um auf Zeitreihen und deren Metadaten zuzugreifen:

SydroTimeSeries

Abfrage einer Zeitreihe

Als Parameter sind zu übergeben Customer, User, Id der Zeitreihe, Weitere Parameter sind entweder ein SQL Statement SQLCriteria oder alternativ drei Parameter als Startdate, Enddate und AttributeFlag. Wenn Startdate und Enddate mit 0 angegeben werden, wird die gesamte Zeitreihe gelesen. Um nur einen Teil der Zeitreihe zu bekommen, können Anfang und/oder Ende mit Datumsformat yyyy-MM-dd HH:mm (z.B. 2010-08-15 08:00) angegeben werden.

Beispiel 1: http://talsim.de:8092/TalsimNGServer/HttpZreSrv/SydroTimeSeries/TestAPI,MusterUser,9999,attribFlag=0

Beispiel 2: http://talsim.de:8092/TalsimNGServer/HttpZreSrv/SydroTimeSeries/TestAPI,MusterUser,9999,2001-05-15 00:00,2001-10-15 00:00,-1

SydroTimeSeries

Erstellen einer neuen Zeitreihen oder Überschreiben einer bestehenden Zeitreihe

Wird ein POST Aufruf mit dem SydroTimeSeries Objekt gestartet, kann eine Zeitreihe neu erstellt oder eine bestehende überschrieben werden. Soll eine bestehende Zeitreihe überschrieben oder ergänzt werden, muss das Attribute <ID> gesetzt sein. Soll eine neue Zeitreihen angelegt werden, muss <ID> gleich 0 sein. Das Objekt SydroTimeSeries besitzt folgende Struktur:

<SydroTimeSeries> 
<Attribute> (short) 
<Customer> (string) 
<DateValuePairSeparator> (string) shows how Date/Value Pairs in TimeSeriesString can be split 
<ErrorValue> (double) Indicator what is an error value, will be replaced by NaN. 
<HasError> (boolean) shows if an error occured during processing the request 
<Id> (Integer) ID of time series. If ID=0 when POST is performed a new time series will be created and the new ID will be returned 
<Length> (integer) Number or records in the TimeSeriesString
<Lat> (double) Latitude coordinate  
<Lon> (double) Longitude coordinate 
<Name> (string) Short name of the time series 
<Path> (string) Path to the time series on the server 
<ResultMsg> (string) Plain text describing errors if any or return a success message 
<SaveMetadata> (boolean) Indicates whether or not metadata should be updated when posting time series values <Separator> (string) indicates how date/values can be split
<StationId> (integer) ID of the station 
<TimeSeriesHeader> (string) Indicates how one time series entry must be interpreted, e.g. "Date,Value,Flag" if one entry has date/value/flag attributes. 
<TimeSeriesString> (string) This is the time series as text, where date/values are separated by the attribute <Separator> and entries are separated by <DateValuePairSeparator>
 Example: <TimeSeriesString>2001-01-01 00:00:00,3.106106,0#2001-01-02 00:00:00,4.209204,0#2001-01-03 00:00:00,0.1453788,#2002-01-02 00:00:00,0,0</TimeSeriesString>
<TsType> (short) Represents the time series type with -1= unknown, 0=Default, 1=Flagged, 2=Forecast 
<Unit> (string) gives the unit string, e.g. mm or m3/s 
<User>Name of the user requesting or posting the time series 
</SydroTimeSeries>

requestSydroTimeSeries

Abfrage einer Zeitreihe

Als Parameter sind zu übergeben Customer, User, Id der Zeitreihe, Startdate, Enddate und Separator (Trennzeichen für den CSV-Inhalt)

SydroTimeSeries/delete

Löschen einer Zeitreihe.

Als Parameter sind zu übergeben Customer, User, Id.

requestSydroTimeSeries

Abfrage einer Zeitreihe

Als Parameter sind zu übergeben Customer, User, Id der Zeitreihe, Startdate, Enddate und Separator (Trennzeichen für den CSV-Inhalt)

Wenn Startdate und Enddate mit 0 angegeben werden, wird die gesamte Zeitreihe gelesen. Um nur einen Teil der Zeitreihe zu bekommen, können Anfang und/oder Ende mit Datumsformat dd.MM.yyyy HH:mm (z.B. 01.01.2010 00:00) oder yyyyMMddHHmm (z.B. 201001010000) angegeben werden.

Beispiel: http://talsim.de:8092/TalsimNGServer/HttpZreSrv/requestSydroTimeSeries/CSV/UNDP_Kura,Kura,318,0,0,comma

postTimeSeriesValues

Setzen von Zeitreihenwerten (POST)

Beispiel: http://10.0.0.5:8092/TalsimNGServer/HttpZreSrv/postTimeSeriesValues
Post data (raw text):

<SydroTimeSeries>
    <Client>UNDP_Kura</Client>
    <Id>318</Id>
    <Length>427</Length>
    <Name>GE.Iori</Name>
    <ResultMsg></ResultMsg>
    <StationId>21</StationId>
    <TimeSeriesString>
	1975-01-01 00:00:00,0.09&#xD;
	1975-02-01 00:00:00,0.1&#xD;
	1975-03-01 00:00:00,0.3&#xD;
	1975-04-01 00:00:00,0.99&#xD;
	1975-05-01 00:00:00,1.19&#xD;
	1975-06-01 00:00:00,0.58&#xD;
	1975-07-01 00:00:00,0.22&#xD;
	1975-08-01 00:00:00,0.11&#xD;
	1975-09-01 00:00:00,0.09&#xD;
	1975-10-01 00:00:00,0.1&#xD;
</TimeSeriesString>
</SydroTimeSeries>

requestSydroZreBin

Beispiel: http://talsim.de:8092/TalsimNGServer/HttpZreSrv/requestSydroZreBin/WFP_SSD,hubert,724,201001010000,201201010000,0

refreshSydroZreBin

Beispiel: http://localhost:8092/TalsimNGServer/HttpZreSrv/refreshSydroZreBin/All/WFP_SSD,hubert

@@ Zeile 24: / Zeile 24: @@
 ==HttpZreSrv==
 HttpZreSrv ist der zentrale Service zur Interaktion mit Zeitreihen. Der HttpZreSrv ist standardmäßig über den Port 8092 ansprechbar. Es gibt folgende Schnittstellen, um auf Zeitreihen und deren Metadaten zuzugreifen:
 ===SydroTimeSeries===
 Abfrage einer Zeitreihe
@@ Zeile 63: / Zeile 64: @@
 </SydroTimeSeries>
 </pre>
+===requestSydroTimeSeries===
+Abfrage einer Zeitreihe
+Als Parameter sind zu übergeben <code>Customer</code>, <code>User</code>, <code>Id</code> der Zeitreihe, <code>Startdate</code>, <code>Enddate</code> und <code>Separator</code> (Trennzeichen für den CSV-Inhalt)
+===SydroTimeSeries/delete===
+Löschen einer Zeitreihe.
+Als Parameter sind zu übergeben <code>Customer</code>, <code>User</code>, <code>Id</code>.
 ===requestSydroTimeSeries===
 Abfrage einer Zeitreihe