Arbeiten mit Zeitreihendaten

Zeitreihendaten

In HAKOM TSM kann eine Zeitreihe auf bis zu 3 Dimensionen Zeitreihendaten speichern:

Daten-Achse: Persistierung der aktuellsten Werte
Historie-Achse: Persistierung von geänderten und historisierten Werten
Notierung-Achse: Persistierung von Versionen

Es kann in jeder Zeitreihendatenoperation, so auch bei der Abfrage von Zeitreihendaten über Formelreferenzen jede dieser drei Dimensionen abgerufen werden.

Mehr über die Möglichkeiten mit Zeitreihendimensionen siehe: Audit und Notierung

Daten abrufen

Zeitreihendaten können sowohl aus der TSM App als auch via WebTSM Services API einfach abgerufen werden.

TSM App:

Klicke auf Öffnen im TSM Ribbon
Wähle den Namen der Zeitreihe im Bereich Zeitreihe aus, oder benutze die Zeitreihensuche:
1. Betätige die Suchen... Schaltfläche im Bereich Zeitreihe des TSM Fensters
2. Fülle die gewünschten Suchparametern (wie Name, Einheit, Attribute) aus
3. Betätige die Suche Schaltfläche
4. Wähle eine oder mehreren Zeitreihen aus
  
  Tipp
  
  Mittels Hinzufügen Schaltfläche kann die Auswahl gemerkt und mit weiteren Suchergebnissen kombiniert werden:
5. Betätige OK
Wähle Raster, Einheit und gegebenenfalls weitere Parameter (absteigend und / oder Fehlende leer) aus
Betätige die Öffnen Schaltfläche

Tipp

Mittels Drop Down Menü der Öffnen Schaltfläche können die Daten in neue Arbeitsmappe (Standardverhalten) oder in bestehende Arbeitsmappe geladen werden.

WebTSM Services API:

Zeitreihendaten einzeln abrufen:
```
GET /repositories/:reposiory/timeseries/:ID|Name/data
?from=<fromDate>&to=<toDate>
```
Rückgabeformate bei Einzelabrufen
Standard "Self Contained Format" mit From, Value, Flag sowie Interval und Unit im Header (Parameter in URL oder Accept/Content-Type Header: format=timestamp):
XML
```
{
  "Interval": {
    "Value": 1,
    "Multiplier": 3600
  },
  "Unit": "cm/m2",
  "Data": [
    {
      "From": "2010-01-01T00:00:00Z",
      "Value": 1.5,
      "Flag": 9
    },
	{
      "From": "2010-01-01T01:00:00Z",
      "Value": 2.0,
      "Flag": 9
    }
  ]
}
```
Von - Bis Format (Parameter in URL oder Accept/Content-Type Header: format=timespan):
XML
```
[
  {
    "From": "2017-05-01T00:00:00Z",
    "To": "2017-05-01T01:00:00Z",
    "Value": 1.5,
    "Flag": 9
  },
  {
    "From": "2017-05-01T01:00:00Z",
    "To": "2017-05-01T02:00:00Z",
    "Value": 2.0,
    "Flag": 9
  }
]
```
Tipp

Auch das Datumsformat der Zeitstempeln lässt mithilfe des Parameters dateFormat (in URL oder Accept/Content-Type Header) auf folgende Weise beeinflussen:
dateFormat=ISO8601 (oder 0) → ISO 8601 Zeitstempeln (Standard)
dateFormat=EpochSeconds (oder 1) → Sekunden seit Unix Epoch
dateFormat=EpochMilliseconds (oder 2) → Millisekunden seit Unix Epoch
Mehrere Zeitreihen in Bulk abrufen:
```
GET /repositories/:reposiory/timeseriescollections/data
?from=<fromDate>&to=<toDate>&name=<TS.1>&name=<TS.N>&interval=<interval>&intervalMultiplier=<intervalMultiplier>
```
Tipp

Parameter Name und ID können mehrfach auch gemischt an /timeseriescollections/data übergeben werden.
Rückgabeformat bei Bulkabrufen
Ein Bulkabruf liefert exakt die gleichen Formate / Datumsformate wie auch die Einzelabrufe, diese werden aber pro Zeitreihe in ein Umschlag gekapselt. Der Umschlag weist folgende Struktur auf:
[ { "ID": 3, "Name": "Test-TimeSeries", "Data": { "Interval": { "Value": 1, "Multiplier": 3600 }, "Unit": "cm/m2", "Data": [ { "From": "2010-01-01T00:00:00Z", "Value": 123.4, "Flag": 9 } ] }, "Message": "", "Details": "", "Status": 200 } ]
Tipp

Es wird immer ein Bulk-Response zurück geliefert, auch dann, wenn einzelne Zeitreihen nicht verfügbar, oder aufgrund von zum Beispiel Formelfehlern nicht berechenbar sind. Aus diesem Grund erhält jede Zeitreihe im Bulk-Response neben ID, Name und Data ihre eigenen Http Status Code (Status), Message (e.g. Fehlermeldungen) und Details (e.g. Stack Trace von Fehlermeldungen). Somit lässt es sich nachverfolgen, ob und welche Zeitreihen erfolgreich abgerufen werden konnten.

Summe mehrerer Zeitreihen via Name abrufen:

GET /repositories/:reposiory/timeseriescollections/data/sum
?from=<fromDate>&to=<toDate>&attribute=<TS.1>&name=<TS.N>&interval=<interval>&intervalMultiplier=<intervalMultiplier>

Summe mehrerer Zeitreihen via zugewiesene Attribute abrufen:

GET /repositories/:reposiory/timeseriescollections/data/sum
?from=<fromDate>&to=<toDate>&attribute=<attribute>|<value>&attribute=<attribute>|<value>&interval=<interval>&intervalMultiplier=<intervalMultiplier>

Zeitreihendaten via Ad Hoc Formel abrufen:

GET /repositories/:reposiory/calculations
?from=<fromDate>&to=<toDate>&calculationInterval=<calculation-interval>&calculationIntervalMultiplier=<calculation-intervalMultiplier>&formula=<formula>

Mehrere Ad Hoc Formel abrufen:

POST/repositories/:reposiory/calculations
?from=<fromDate>&to=<toDate>&calculationInterval=<calculation-interval>&calculationIntervalMultiplier=<calculation-intervalMultiplier>&formula=<formula>

JS

Minimum Request Body:
[
    {
        "Name": "<Name der Berechnung>",
        "Formula": "<formula>",
        "CalculationInterval": "<interval>",
        "CalculationIntervalMultiplier": "<intervalMultiplier>"
    },
    {
        "Name": "<Name der Berechnung>",
        "Formula": "<formula>",
        "CalculationInterval": "<interval>",
        "CalculationIntervalMultiplier": "<intervalMultiplier>"
    }
]

Zeitreihendaten aus Knotenattributen (Hierarchien) - Hauptknoten abrufen:

GET /repositories/:reposiory/trees/:ID|Name/sum
?from=<fromDate>&to=<toDate>&attribute=<TS.1>&name=<TS.N>&interval=<interval>&intervalMultiplier=<intervalMultiplier>

Zeitreihendaten aus Knotenattributen (Hierarchien) - Subknoten abrufen:
```
GET /repositories/:reposiory/trees/:ID|Name/nodes/:nodeId/sum
?from=<fromDate>&to=<toDate>&attribute=<TS.1>&name=<TS.N>&interval=<interval>&intervalMultiplier=<intervalMultiplier>
```
Tipp

Folgende Parameter könnten bei Knotenattribute (Hierarchien) nützlich sein:
- timeSeriesAttributes (Suche nach zusätzlichen Attributen)
- includeTimeSeries (inkludiert Zeitreihendefinitionen im Response→ die nützlich sind, um herauszufinden, welche Zeitreihe welchem Knoten zugeordnet ist)
- includeSubNodes (inkludiert Subknoten-Details im Response)
- sumType: includingSubNodes, excludingSubNodes

Daten speichern

Zeitreihendaten können sowohl aus der TSM App als auch via WebTSM Services API persistiert / upgedatet werden.

TSM App:

Öffne ein gespeichertes TSM Excel Template mit Daten der gewünschten Zeitreihe oder Lade die gewünschte Zeitreihe (siehe Kapitel Daten Abrufen) und passe die Daten entsprechend an
Klicke im TSM Ribbon auf Speichern → die Zeitreihendaten werden (sofern keine Kontrollfunktionen für die jeweilige Zeitreihenspalte aktiviert sind) gespeichert.

Tipp

In Zeile 16 des TSM Excel Templates kann durch Hinzufügen der folgenden Steuerbefehle gesteuert werden, ob eine bestimmte Spalte gelesen, gespeichert oder ignoriert werden soll:

nicht lesen
nicht speichern
ignorieren

WebTSM Services API:

Tipp

Die Request Bodies zur Übermittlung von Daten sind identisch mit denen bei Datenabrufen.

Zeitreihendaten einzeln speichern:

POST /repositories/:reposiory/timeseries/:ID|Name/data

Daten mehrerer Zeitreihen in Bulk speichern:

POST /repositories/:reposiory/timeseriescollections/data

Wir empfehlen folgende Videos unter Video Tutorials:

Handling Time Series Data
Bulk Operations