Server-API: Unterschied zwischen den Versionen

Aus TALSIM Docs
Keine Bearbeitungszusammenfassung
(Diese Seite wurde zum Übersetzen freigegeben)
(4 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
<languages/>
<translate>
<!--T:1-->
<div class="achtung">Die Server-API befindet sich noch in der Entwicklungsphase, Änderungen sind zu erwarten</div>
<div class="achtung">Die Server-API befindet sich noch in der Entwicklungsphase, Änderungen sind zu erwarten</div>


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:
<!--T:2-->
Die Serverkomponente von Talsim-NG ([[Special:MyLanguage/TalsimNGSrv|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:
__TOC__
__TOC__
<div class="info">In den unten angegebenen Beispielen wird als Server-Adresse <code>talsim.de</code> verwendet, dies ist mit der Adresse oder IP des tatsächlich verwendeten Talsim-Servers zu ersetzen.</div>
<div class="info">In den unten angegebenen Beispielen wird als Server-Adresse <code>talsim.de</code> verwendet, dies ist mit der Adresse oder IP des tatsächlich verwendeten Talsim-Servers zu ersetzen.</div>
==HttpDataSrv==
 
==HttpDataSrv== <!--T:3-->
 
<!--T:4-->
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:
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===
 
===requestClients=== <!--T:5-->
 
<!--T:6-->
Generelle Abfrage aller Kunden.
Generelle Abfrage aller Kunden.


===requestCustomers===
 
===requestCustomers=== <!--T:7-->
 
<!--T:8-->
Generelle Abfrage aller Kunden. Identisch zu <code>requestClients</code>
Generelle Abfrage aller Kunden. Identisch zu <code>requestClients</code>


<!--T:9-->
Beispiel: <code><nowiki>http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestCustomers/|</nowiki></code>
Beispiel: <code><nowiki>http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestCustomers/|</nowiki></code>
===requestZreDirectories===
 
===requestZreDirectories=== <!--T:10-->
 
<!--T:11-->
Abfrage von Zeitreihen-Ordnern. Es werden Zeitreihen-Ordner mit ihren Zeitreihen zurückgegeben. Parameter sind <code>customer</code> und mit Komma getrennt ein "|".
Abfrage von Zeitreihen-Ordnern. Es werden Zeitreihen-Ordner mit ihren Zeitreihen zurückgegeben. Parameter sind <code>customer</code> und mit Komma getrennt ein "|".


<!--T:12-->
Beispiel: <code><nowiki>http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestZreDirectories/Nile,|</nowiki></code>
Beispiel: <code><nowiki>http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestZreDirectories/Nile,|</nowiki></code>
===ZreDirectories===
 
===ZreDirectories=== <!--T:13-->
 
<!--T:14-->
Abfrage von Zeitreihen-Ordnern. Es werden nur Zeitreihen-Ordner zurückgegeben. Parameter sind <code>customer</code> und mit Komma getrennt ein "|".
Abfrage von Zeitreihen-Ordnern. Es werden nur Zeitreihen-Ordner zurückgegeben. Parameter sind <code>customer</code> und mit Komma getrennt ein "|".


<!--T:15-->
Beispiel: <code><nowiki>http://talsim.de:8090/TalsimNGServer/HttpDataSrv/ZreDirectories/Nile,|</nowiki></code>
Beispiel: <code><nowiki>http://talsim.de:8090/TalsimNGServer/HttpDataSrv/ZreDirectories/Nile,|</nowiki></code>


===requestZreFiles===
 
===requestZreFiles=== <!--T:16-->
 
<!--T:17-->
Abfrage von vorhandenen Zeitreihen. Parameter sind <code>customer</code>, <code>user</code> sowie die ID des Zeitreihen-Ordners. Ist die ID des Zeitreihen-Ordners 0, werden alle Zeitreihen zurückgegeben.
Abfrage von vorhandenen Zeitreihen. Parameter sind <code>customer</code>, <code>user</code> sowie die ID des Zeitreihen-Ordners. Ist die ID des Zeitreihen-Ordners 0, werden alle Zeitreihen zurückgegeben.


<!--T:18-->
Beispiel: <code><nowiki>http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestZreFiles/Nile,hubert,16</nowiki></code>
Beispiel: <code><nowiki>http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestZreFiles/Nile,hubert,16</nowiki></code>
===requestSystemAndSysVar===
 
===requestSystemAndSysVar=== <!--T:19-->
 
<!--T:20-->
Abfrage von Systemen und Systemvarianten
Abfrage von Systemen und Systemvarianten


<!--T:21-->
Beispiel: <code><nowiki>http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestSystemAndSysVar/WFP_SSD,hubert,1</nowiki></code>
Beispiel: <code><nowiki>http://talsim.de:8090/TalsimNGServer/HttpDataSrv/requestSystemAndSysVar/WFP_SSD,hubert,1</nowiki></code>
==HttpZreSrv==
 
==HttpZreSrv== <!--T:22-->
 
<!--T:23-->
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:
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===
 
===SydroTimeSeries=== <!--T:24-->
 
<!--T:25-->
Abfrage einer Zeitreihe
Abfrage einer Zeitreihe


<!--T:26-->
Als Parameter sind zu übergeben <code>Customer</code>, <code>User</code>, <code>Id</code> der Zeitreihe, Weitere Parameter sind aktuell noch ein SQL Statement <code>SQLCriteria</code> oder alternativ drei Parameter als <code>Startdate</code>, <code>Enddate</code> und <code>AttributeFlag</code>. Das SQL Statement ist momentan nur zum Testen aktiviert und wird wenn alle anderen Endpoints gesetzt sind wieder eingestellt.  
Als Parameter sind zu übergeben <code>Customer</code>, <code>User</code>, <code>Id</code> der Zeitreihe, Weitere Parameter sind aktuell noch ein SQL Statement <code>SQLCriteria</code> oder alternativ drei Parameter als <code>Startdate</code>, <code>Enddate</code> und <code>AttributeFlag</code>. Das SQL Statement ist momentan nur zum Testen aktiviert und wird wenn alle anderen Endpoints gesetzt sind wieder eingestellt.  
Wenn Startdate und Enddate mit <code>0</code> angegeben werden, wird die gesamte Zeitreihe gelesen. Um nur einen Teil der Zeitreihe zu bekommen, können Anfang und/oder Ende mit Datumsformat <code>yyyy-MM-dd HH:mm</code> (z.B. <code>2010-08-15 08:00</code>) angegeben werden.
Wenn Startdate und Enddate mit <code>0</code> angegeben werden, wird die gesamte Zeitreihe gelesen. Um nur einen Teil der Zeitreihe zu bekommen, können Anfang und/oder Ende mit Datumsformat <code>yyyy-MM-dd HH:mm</code> (z.B. <code>2010-08-15 08:00</code>) angegeben werden.


<!--T:27-->
Beispiel 1: <code><nowiki>http://talsim.de:8092/TalsimNGServer/HttpZreSrv/SydroTimeSeries/TestAPI,MusterUser,9999,attribFlag=0</nowiki></code>  
Beispiel 1: <code><nowiki>http://talsim.de:8092/TalsimNGServer/HttpZreSrv/SydroTimeSeries/TestAPI,MusterUser,9999,attribFlag=0</nowiki></code>  


===SydroTimeSeries/combine===
 
===SydroTimeSeries/combine=== <!--T:28-->
 
<!--T:29-->
Kombinieren von zwei Zeitreihen. Dies ist zum Beispiel sinnvoll, um eine Messzeitreihe mit Vorhersagedaten zu kombinieren.
Kombinieren von zwei Zeitreihen. Dies ist zum Beispiel sinnvoll, um eine Messzeitreihe mit Vorhersagedaten zu kombinieren.


<!--T:30-->
Als Parameter sind zu übergeben <code>customer</code>, <code>user</code>, <code>id1</code>, <code>id2</code>,<code>startdate1</code>, <code>endstartdate</code>, <code>enddate2</code>, <code>flag1</code>,<code>flag2</code>. <code>Id1</code> bezieht sich auf die erste Zeitreihe und <code>Id2</code> auf die Reihe, welche angehängt wird. <code>Startdate1</code> definiert wo die erste Zeitreihe anfangen soll, <code>endstartdate</code> wo diese aufhöhrt und die zweite beginnen soll und <code>enddate2</code> das Enddatum der zweiten Reihe. Ist <code>enddate2</code> 0 oder leer wird bis zum Ende der zweiten Zeitreihe gelesen.  
Als Parameter sind zu übergeben <code>customer</code>, <code>user</code>, <code>id1</code>, <code>id2</code>,<code>startdate1</code>, <code>endstartdate</code>, <code>enddate2</code>, <code>flag1</code>,<code>flag2</code>. <code>Id1</code> bezieht sich auf die erste Zeitreihe und <code>Id2</code> auf die Reihe, welche angehängt wird. <code>Startdate1</code> definiert wo die erste Zeitreihe anfangen soll, <code>endstartdate</code> wo diese aufhöhrt und die zweite beginnen soll und <code>enddate2</code> das Enddatum der zweiten Reihe. Ist <code>enddate2</code> 0 oder leer wird bis zum Ende der zweiten Zeitreihe gelesen.  


<!--T:31-->
Beispiel 1: <code><nowiki>http://talsim.de:8092/TalsimNGServer/HttpZreSrv/SydroTimeSeries/combine/TestAPI,MusterUser,9999,8888,2019-02-01 00:00,2019-10-01 00:00, 0,0</nowiki></code>
Beispiel 1: <code><nowiki>http://talsim.de:8092/TalsimNGServer/HttpZreSrv/SydroTimeSeries/combine/TestAPI,MusterUser,9999,8888,2019-02-01 00:00,2019-10-01 00:00, 0,0</nowiki></code>


===SydroTimeSeries===
 
===SydroTimeSeries=== <!--T:32-->
 
<!--T:33-->
Erstellen einer neuen Zeitreihen oder Überschreiben einer bestehenden Zeitreihe
Erstellen einer neuen Zeitreihen oder Überschreiben einer bestehenden Zeitreihe


<!--T:34-->
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 <code>ID</code> gesetzt sein. Soll eine neue Zeitreihen angelegt werden, muss <code>ID</code> gleich 0 sein. Das Objekt SydroTimeSeries besitzt folgende Struktur:  
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 <code>ID</code> gesetzt sein. Soll eine neue Zeitreihen angelegt werden, muss <code>ID</code> gleich 0 sein. Das Objekt SydroTimeSeries besitzt folgende Struktur:  


<!--T:35-->
<pre>
<pre>
<SydroTimeSeries>  
<SydroTimeSeries>  
Zeile 78: Zeile 126:
</pre>
</pre>


===SydroTimeSeries/process===
 
===SydroTimeSeries/process=== <!--T:36-->
 
<!--T:37-->
Eine zweite Art eine Zeitreihe zu erstellen bzw. hochzuladen, ist durch <code>process</code> gegeben.
Eine zweite Art eine Zeitreihe zu erstellen bzw. hochzuladen, ist durch <code>process</code> gegeben.


<!--T:38-->
In diesem Fall sind aber mehrere Interaktionen mit dem Server erforderlich, die nur per Software sinnvoll sind. Parameter sind <code>customer</code>, <code>user</code>, <code>id</code>, <code>SydroTimeSeriesFile</code>. Der Parameter <code>SydroTimeSeriesFile</code> ist eine Datei mit dem Inhalt eines SydroTimeSeries Objektes, welches vor dem Aufruf per Streaming in Kommunikation mit dem Server auf den Server hochgeladen werden muss. Dies erfordert das <code>TalsimNGZreClient</code> Modul, welches in eine Software integriert werden muss. Das Werkzeug <code>SydroCmd</code> besitzt die Fähigkeit, Dateien hochzuladen und ist deshalb für den operationellen Einsatz mit dem TalsimNGServer geeignet. Nach dem Aufruf sorgt der Server für die Verarbeitung der Datei und liefert eine Meldung zurück, dass der Prozess gestartet wurde. Es gibt keine Erfolgsmeldung, da der Server diesen Prozess asynchron in einem Thread verarbeitet.  
In diesem Fall sind aber mehrere Interaktionen mit dem Server erforderlich, die nur per Software sinnvoll sind. Parameter sind <code>customer</code>, <code>user</code>, <code>id</code>, <code>SydroTimeSeriesFile</code>. Der Parameter <code>SydroTimeSeriesFile</code> ist eine Datei mit dem Inhalt eines SydroTimeSeries Objektes, welches vor dem Aufruf per Streaming in Kommunikation mit dem Server auf den Server hochgeladen werden muss. Dies erfordert das <code>TalsimNGZreClient</code> Modul, welches in eine Software integriert werden muss. Das Werkzeug <code>SydroCmd</code> besitzt die Fähigkeit, Dateien hochzuladen und ist deshalb für den operationellen Einsatz mit dem TalsimNGServer geeignet. Nach dem Aufruf sorgt der Server für die Verarbeitung der Datei und liefert eine Meldung zurück, dass der Prozess gestartet wurde. Es gibt keine Erfolgsmeldung, da der Server diesen Prozess asynchron in einem Thread verarbeitet.  


<!--T:39-->
Beispiel 1: <code><nowiki>http://talsim.de:8092/TalsimNGServer/HttpZreSrv/SydroTimeSeries/process/TestAPI,MusterUser,9999,..serververzeichnis/file.sydrots</nowiki></code>
Beispiel 1: <code><nowiki>http://talsim.de:8092/TalsimNGServer/HttpZreSrv/SydroTimeSeries/process/TestAPI,MusterUser,9999,..serververzeichnis/file.sydrots</nowiki></code>


===SydroTimeSeries/delete===
 
===SydroTimeSeries/delete=== <!--T:40-->
 
<!--T:41-->
Löschen einer Zeitreihe.
Löschen einer Zeitreihe.


<!--T:42-->
Als Parameter sind zu übergeben <code>Customer</code>, <code>User</code>, <code>Id</code>. Es gibt kein Undo zu diesem Vorgang.
Als Parameter sind zu übergeben <code>Customer</code>, <code>User</code>, <code>Id</code>. Es gibt kein Undo zu diesem Vorgang.


===SydroTimeSeries/deleteRecords===
 
===SydroTimeSeries/deleteRecords=== <!--T:43-->
 
<!--T:44-->
Löschen von Einträgen in einer Zeitreihe.
Löschen von Einträgen in einer Zeitreihe.


<!--T:45-->
Als Parameter sind zu übergeben <code>Customer</code>, <code>User</code>, <code>Id</code>, <code>Startdate</code>, <code>Enddate</code> und <code>AttributeFlag</code>. Gelöscht werden die Einträge, die zwischen <code>Startdate</code> und <code>Enddate</code> liegen und den <code>AttributeFlag</code> besitzen.  
Als Parameter sind zu übergeben <code>Customer</code>, <code>User</code>, <code>Id</code>, <code>Startdate</code>, <code>Enddate</code> und <code>AttributeFlag</code>. Gelöscht werden die Einträge, die zwischen <code>Startdate</code> und <code>Enddate</code> liegen und den <code>AttributeFlag</code> besitzen.  


===SydroTimeSeries/attributes===
 
===SydroTimeSeries/attributes=== <!--T:46-->
 
<!--T:47-->
Abfrage oder Setzen von Metadaten zu einer Zeitreihe
Abfrage oder Setzen von Metadaten zu einer Zeitreihe


<!--T:48-->
Werden als Parameter <code>Customer</code>, <code>User</code>, <code>Id</code> übergeben, erhält man als Antwort einen String im Format FeldName=Wert getrennt durch "#" Zeichen, der alle Metadaten der Zeitreihe zeigt. Wird zusätzlich ein weiterer Parameter <code>KeyValuePairs</code> übergeben, so setzt man Metadaten. Der String KeyValuePairs muss im Format Feldname=Wert getrennt durch "#" angegeben sein. Die gegebenen Eigenschaften werden gespeichert, vorausgesetzt es handelt sich nicht um geschützte Felder.
Werden als Parameter <code>Customer</code>, <code>User</code>, <code>Id</code> übergeben, erhält man als Antwort einen String im Format FeldName=Wert getrennt durch "#" Zeichen, der alle Metadaten der Zeitreihe zeigt. Wird zusätzlich ein weiterer Parameter <code>KeyValuePairs</code> übergeben, so setzt man Metadaten. Der String KeyValuePairs muss im Format Feldname=Wert getrennt durch "#" angegeben sein. Die gegebenen Eigenschaften werden gespeichert, vorausgesetzt es handelt sich nicht um geschützte Felder.


<!--T:49-->
Alternativ kann auch mittels POST ein SydroTimeSeriesAttributes Objekt gesendet werden, welches die zu schreibenden Eigenschaften beinhaltet.  
Alternativ kann auch mittels POST ein SydroTimeSeriesAttributes Objekt gesendet werden, welches die zu schreibenden Eigenschaften beinhaltet.  


===SydroTimeSeries/attributes/fieldnames===
 
===SydroTimeSeries/attributes/fieldnames=== <!--T:50-->
 
<!--T:51-->
Dieser Aufruf gibt alle Feldnamen der Metadaten getrennt durch Komma zurück.
Dieser Aufruf gibt alle Feldnamen der Metadaten getrennt durch Komma zurück.


===SydroTimeSeries/fieldnames===
 
===SydroTimeSeries/fieldnames=== <!--T:52-->
 
<!--T:53-->
Dieser Aufruf gibt alle Feldnamen der Zeitreihentabelle getrennt durch Komma zurück.
Dieser Aufruf gibt alle Feldnamen der Zeitreihentabelle getrennt durch Komma zurück.


===SydroTimeSeries/flags===
 
===SydroTimeSeries/flags=== <!--T:54-->
 
<!--T:55-->
Mit diesem Aufruf erhält man alle in der Zeitreihe verwendeten Flags. Erforderliche Parameter sind <code>Customer</code>, <code>User</code>, <code>Id</code>
Mit diesem Aufruf erhält man alle in der Zeitreihe verwendeten Flags. Erforderliche Parameter sind <code>Customer</code>, <code>User</code>, <code>Id</code>


===SydroTimeSeries/class===
 
===SydroTimeSeries/class=== <!--T:56-->
 
<!--T:57-->
Mit diesem Aufruf erhält man die Klasse einerZeitreihe, also -1= unknown, 0=Default, 1=Flagged, 2=Forecast. Erforderliche Parameter sind <code>Customer</code>, <code>User</code>, <code>Id</code>
Mit diesem Aufruf erhält man die Klasse einerZeitreihe, also -1= unknown, 0=Default, 1=Flagged, 2=Forecast. Erforderliche Parameter sind <code>Customer</code>, <code>User</code>, <code>Id</code>


==HttpZreSrv (spezielle Services)==
 
==HttpZreSrv (spezielle Services)== <!--T:58-->
 
<!--T:59-->
Zusätzlich zu den oben erwähnten REST Schnittstellen gibt es noch drei Sonderschnittstellen.  
Zusätzlich zu den oben erwähnten REST Schnittstellen gibt es noch drei Sonderschnittstellen.  


<!--T:60-->
1. Abfrage des Arbeitsverzeichnisses des <code>users</code> (wichtig für das Hochladen von Dateien)
1. Abfrage des Arbeitsverzeichnisses des <code>users</code> (wichtig für das Hochladen von Dateien)
<!--T:61-->
2. Synchronisierung eines <code>customers</code> (Abgleich aller Metadaten zwischen Master-Datenbank und allen Zeitreihen)
2. Synchronisierung eines <code>customers</code> (Abgleich aller Metadaten zwischen Master-Datenbank und allen Zeitreihen)
<!--T:62-->
3. Konvertierung von Sydro Binar Dateien in Sydro SQLite Dateien für einen <code>customer</code> (normalerweise einmaliger Vorgang bei der Umstellung auf SQLite)
3. Konvertierung von Sydro Binar Dateien in Sydro SQLite Dateien für einen <code>customer</code> (normalerweise einmaliger Vorgang bei der Umstellung auf SQLite)


Die Synchronisierung wird der Server regelmässig zu bestimmten Uhrzeiten selbständig vornehmen. Da diese Schnittstellen nicht zur normalen Benutzung vorgesehen sind, sondern Bestandteil der Sydro Serivices im Operationellen Betrieb sind, erfolgt keine weitere Beschreibung des Aufrufs.  
<!--T:63-->
Die Synchronisierung wird der Server regelmässig zu bestimmten Uhrzeiten selbständig vornehmen. Da diese Schnittstellen nicht zur normalen Benutzung vorgesehen sondern Bestandteil der Sydro Serivices im Operationellen Betrieb sind, erfolgt keine weitere Beschreibung des Aufrufs.  


===Reports===
 
===Reports=== <!--T:64-->
 
<!--T:65-->
Abfrage eines Berichts zur Synchronisierung bzw. Konvertierung.  
Abfrage eines Berichts zur Synchronisierung bzw. Konvertierung.  


Sowohl zur Synchronisierung als auch zur Konvertierung werden Berichte vom Server erstellt, die man abrufen kann. Parameter sind <code>Customer</code>, <code>User</code>, <code>date</code>, <code>TypeOfReport</code>. <code>date</code> kann angegeben werden, um einen Bericht für einen bestimmten Tag zu erhalten. ist <code>date</code> 0 oder leer wird der aktuellste Bericht zurückgegeben. <code>TypeOfReport</code> ist entweder <code>SynchronizeLog</code> oder <code>ConvertLog</code>.  
<!--T:66-->
Sowohl zur Synchronisierung als auch zur Konvertierung werden Berichte vom Server erstellt, die man abrufen kann. Parameter sind <code>Customer</code>, <code>User</code>, <code>date</code>, <code>TypeOfReport</code>. <code>date</code> kann angegeben werden, um einen Bericht für einen bestimmten Tag zu erhalten. ist <code>date</code> 0 oder leer wird der aktuellste Bericht zurückgegeben. <code>TypeOfReport</code> ist entweder <code>SynchronizeLog</code> oder <code>ConvertLog</code>.
 
 
==HttpZreSrv (alte Schnittstelle)== <!--T:67-->
 
<!--T:68-->
Alte Schnittstellen.
 
<!--T:69-->
Der Service besitzt weitere Schnittstellen, die aus Gründen der Kompatibilität bestehen bleiben und zum Austausch von Sydro Binär Dateien dienen, teilweise aber bereits das neue SydroTimeSeries Objekt verwenden. 
 
 
===requestSydroTimeSeries=== <!--T:70-->
 
<!--T:71-->
Abfrage einer Zeitreihe (neues SydroTimeSeries Objekt)


<!--T:72-->
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).


===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)
===requestSydroTimeSeries=== <!--T:73-->


===requestSydroTimeSeries===
<!--T:74-->
Abfrage einer Zeitreihe
Abfrage einer Zeitreihe  


<!--T:75-->
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)
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)


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


<!--T:77-->
Beispiel: <code><nowiki>http://talsim.de:8092/TalsimNGServer/HttpZreSrv/requestSydroTimeSeries/CSV/UNDP_Kura,Kura,318,0,0,comma</nowiki></code>
Beispiel: <code><nowiki>http://talsim.de:8092/TalsimNGServer/HttpZreSrv/requestSydroTimeSeries/CSV/UNDP_Kura,Kura,318,0,0,comma</nowiki></code>
===postTimeSeriesValues===
 
 
===postTimeSeriesValues=== <!--T:78-->
 
<!--T:79-->
Setzen von Zeitreihenwerten (POST)
Setzen von Zeitreihenwerten (POST)


<!--T:80-->
Beispiel: <code><nowiki>http://10.0.0.5:8092/TalsimNGServer/HttpZreSrv/postTimeSeriesValues</nowiki></code><br/>
Beispiel: <code><nowiki>http://10.0.0.5:8092/TalsimNGServer/HttpZreSrv/postTimeSeriesValues</nowiki></code><br/>
Post data (raw text):
Post data (raw text):
Zeile 170: Zeile 284:
</source>
</source>


===requestSydroZreBin===
 
===requestSydroZreBin=== <!--T:81-->
 
<!--T:82-->
Beispiel: <code><nowiki>http://talsim.de:8092/TalsimNGServer/HttpZreSrv/requestSydroZreBin/WFP_SSD,hubert,724,201001010000,201201010000,0</nowiki></code>
Beispiel: <code><nowiki>http://talsim.de:8092/TalsimNGServer/HttpZreSrv/requestSydroZreBin/WFP_SSD,hubert,724,201001010000,201201010000,0</nowiki></code>


===refreshSydroZreBin===
 
===refreshSydroZreBin=== <!--T:83-->
 
<!--T:84-->
Beispiel: <code><nowiki>http://localhost:8092/TalsimNGServer/HttpZreSrv/refreshSydroZreBin/All/WFP_SSD,hubert</nowiki></code>
Beispiel: <code><nowiki>http://localhost:8092/TalsimNGServer/HttpZreSrv/refreshSydroZreBin/All/WFP_SSD,hubert</nowiki></code>
</translate>

Version vom 23. September 2020, 14:29 Uhr

Sprachen:
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.


requestCustomers

Generelle Abfrage aller Kunden. Identisch zu requestClients

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

requestZreDirectories

Abfrage von Zeitreihen-Ordnern. Es werden Zeitreihen-Ordner mit ihren Zeitreihen zurückgegeben. Parameter sind customer und mit Komma getrennt ein "|".

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

ZreDirectories

Abfrage von Zeitreihen-Ordnern. Es werden nur Zeitreihen-Ordner zurückgegeben. Parameter sind customer und mit Komma getrennt ein "|".

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


requestZreFiles

Abfrage von vorhandenen Zeitreihen. Parameter sind customer, user sowie die ID des Zeitreihen-Ordners. Ist die ID des Zeitreihen-Ordners 0, werden alle Zeitreihen zurückgegeben.

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 aktuell noch ein SQL Statement SQLCriteria oder alternativ drei Parameter als Startdate, Enddate und AttributeFlag. Das SQL Statement ist momentan nur zum Testen aktiviert und wird wenn alle anderen Endpoints gesetzt sind wieder eingestellt. 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


SydroTimeSeries/combine

Kombinieren von zwei Zeitreihen. Dies ist zum Beispiel sinnvoll, um eine Messzeitreihe mit Vorhersagedaten zu kombinieren.

Als Parameter sind zu übergeben customer, user, id1, id2,startdate1, endstartdate, enddate2, flag1,flag2. Id1 bezieht sich auf die erste Zeitreihe und Id2 auf die Reihe, welche angehängt wird. Startdate1 definiert wo die erste Zeitreihe anfangen soll, endstartdate wo diese aufhöhrt und die zweite beginnen soll und enddate2 das Enddatum der zweiten Reihe. Ist enddate2 0 oder leer wird bis zum Ende der zweiten Zeitreihe gelesen.

Beispiel 1: http://talsim.de:8092/TalsimNGServer/HttpZreSrv/SydroTimeSeries/combine/TestAPI,MusterUser,9999,8888,2019-02-01 00:00,2019-10-01 00:00, 0,0


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>
<TsClass> (short) Represents the time series class 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 or the owner of the time series.  
</SydroTimeSeries> 


SydroTimeSeries/process

Eine zweite Art eine Zeitreihe zu erstellen bzw. hochzuladen, ist durch process gegeben.

In diesem Fall sind aber mehrere Interaktionen mit dem Server erforderlich, die nur per Software sinnvoll sind. Parameter sind customer, user, id, SydroTimeSeriesFile. Der Parameter SydroTimeSeriesFile ist eine Datei mit dem Inhalt eines SydroTimeSeries Objektes, welches vor dem Aufruf per Streaming in Kommunikation mit dem Server auf den Server hochgeladen werden muss. Dies erfordert das TalsimNGZreClient Modul, welches in eine Software integriert werden muss. Das Werkzeug SydroCmd besitzt die Fähigkeit, Dateien hochzuladen und ist deshalb für den operationellen Einsatz mit dem TalsimNGServer geeignet. Nach dem Aufruf sorgt der Server für die Verarbeitung der Datei und liefert eine Meldung zurück, dass der Prozess gestartet wurde. Es gibt keine Erfolgsmeldung, da der Server diesen Prozess asynchron in einem Thread verarbeitet.

Beispiel 1: http://talsim.de:8092/TalsimNGServer/HttpZreSrv/SydroTimeSeries/process/TestAPI,MusterUser,9999,..serververzeichnis/file.sydrots


SydroTimeSeries/delete

Löschen einer Zeitreihe.

Als Parameter sind zu übergeben Customer, User, Id. Es gibt kein Undo zu diesem Vorgang.


SydroTimeSeries/deleteRecords

Löschen von Einträgen in einer Zeitreihe.

Als Parameter sind zu übergeben Customer, User, Id, Startdate, Enddate und AttributeFlag. Gelöscht werden die Einträge, die zwischen Startdate und Enddate liegen und den AttributeFlag besitzen.


SydroTimeSeries/attributes

Abfrage oder Setzen von Metadaten zu einer Zeitreihe

Werden als Parameter Customer, User, Id übergeben, erhält man als Antwort einen String im Format FeldName=Wert getrennt durch "#" Zeichen, der alle Metadaten der Zeitreihe zeigt. Wird zusätzlich ein weiterer Parameter KeyValuePairs übergeben, so setzt man Metadaten. Der String KeyValuePairs muss im Format Feldname=Wert getrennt durch "#" angegeben sein. Die gegebenen Eigenschaften werden gespeichert, vorausgesetzt es handelt sich nicht um geschützte Felder.

Alternativ kann auch mittels POST ein SydroTimeSeriesAttributes Objekt gesendet werden, welches die zu schreibenden Eigenschaften beinhaltet.


SydroTimeSeries/attributes/fieldnames

Dieser Aufruf gibt alle Feldnamen der Metadaten getrennt durch Komma zurück.


SydroTimeSeries/fieldnames

Dieser Aufruf gibt alle Feldnamen der Zeitreihentabelle getrennt durch Komma zurück.


SydroTimeSeries/flags

Mit diesem Aufruf erhält man alle in der Zeitreihe verwendeten Flags. Erforderliche Parameter sind Customer, User, Id


SydroTimeSeries/class

Mit diesem Aufruf erhält man die Klasse einerZeitreihe, also -1= unknown, 0=Default, 1=Flagged, 2=Forecast. Erforderliche Parameter sind Customer, User, Id


HttpZreSrv (spezielle Services)

Zusätzlich zu den oben erwähnten REST Schnittstellen gibt es noch drei Sonderschnittstellen.

1. Abfrage des Arbeitsverzeichnisses des users (wichtig für das Hochladen von Dateien)

2. Synchronisierung eines customers (Abgleich aller Metadaten zwischen Master-Datenbank und allen Zeitreihen)

3. Konvertierung von Sydro Binar Dateien in Sydro SQLite Dateien für einen customer (normalerweise einmaliger Vorgang bei der Umstellung auf SQLite)

Die Synchronisierung wird der Server regelmässig zu bestimmten Uhrzeiten selbständig vornehmen. Da diese Schnittstellen nicht zur normalen Benutzung vorgesehen sondern Bestandteil der Sydro Serivices im Operationellen Betrieb sind, erfolgt keine weitere Beschreibung des Aufrufs.


Reports

Abfrage eines Berichts zur Synchronisierung bzw. Konvertierung.

Sowohl zur Synchronisierung als auch zur Konvertierung werden Berichte vom Server erstellt, die man abrufen kann. Parameter sind Customer, User, date, TypeOfReport. date kann angegeben werden, um einen Bericht für einen bestimmten Tag zu erhalten. ist date 0 oder leer wird der aktuellste Bericht zurückgegeben. TypeOfReport ist entweder SynchronizeLog oder ConvertLog.


HttpZreSrv (alte Schnittstelle)

Alte Schnittstellen.

Der Service besitzt weitere Schnittstellen, die aus Gründen der Kompatibilität bestehen bleiben und zum Austausch von Sydro Binär Dateien dienen, teilweise aber bereits das neue SydroTimeSeries Objekt verwenden.


requestSydroTimeSeries

Abfrage einer Zeitreihe (neues SydroTimeSeries Objekt)

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


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