Diese Seite verwendet Cookies. Mit der weiteren Nutzung der Seite erklären Sie sich damit einverstanden. Ausblenden Mehr Informationen

Datasheet Historian REST Interface Einloggen

Historian REST interface

The HistorianAPI is a Websocket Interface that transfers JSON data. By default it is listening on port 8083. This can be changed by editing ConfigServer.Settings.

All API requests expect an UTF-8 encoded JSON object. The following properties are used for all requests:

More properties may exist, depending on the function to execute. Any unknown properties are silently ignored. For future compatibility avoid sending undocumented properties.

All API answers are returned as an UTF-8 encoded JSON object. The following properties always exist:

More properties may exist, depending on the function to execute. For future compatibility, the client should ignore any properties it does not recognize.

Function "Historian/Read"

Reads historical values.

Additional request properties:

Notes:

Additional response properties:

example request:

{
 "function": "Historian/Read",
 "id": 12345,
 "variable": "New Variable",
 "valuecount": 100,
 "start": "2021-04-20T11:30:00Z",
 "stop": "2021-04-20T11:30:10Z",
 "resolution": "second",
 "aggregate": "avg"
}

example response:

{
 "function": "Historian/Read",
  "id": 12345,
  "status": 0,
  "variable": "New Variable",
  "values": [
   { "quality": 0, "time": "2021-04-20T11:30:00Z", "value": 10 },
   { "quality": 0, "time": "2021-04-20T11:30:02Z", "value": 11 },
   { "quality": 0, "time": "2021-04-20T11:30:04Z", "value": 12 },
   { "quality": 0, "time": "2021-04-20T11:30:06Z", "value": 13 },
   { "quality": 0, "time": "2021-04-20T11:30:08Z", "value": 14 },
   { "quality": 0, "time": "2021-04-20T11:30:10Z", "value": 15 },
  ],
 "blocked": false
}

Function "Historian/Write"

Writes historical values. The Historian only supports adding values in sequential order. Values that are passed out of sequence are silently ignored.

Additional request properties:

Notes:

Additional response properties:

example request:

{
 "function": "Historian/Write",
 "id": 12345,
 "variable": "New Variable",
 "values": [
  { "quality": 0, "time": "2021-04-20T11:30:00Z", "value": 10 },
  { "quality": 0, "time": "2021-04-20T11:30:02Z", "value": 11 },
  { "quality": 0, "time": "2021-04-20T11:30:04Z", "value": 12 },
  { "quality": 0, "time": "2021-04-20T11:30:06Z", "value": 13 },
  { "quality": 0, "time": "2021-04-20T11:30:08Z", "value": 14 },
  { "quality": 0, "time": "2021-04-20T11:30:10Z", "value": 15 },
 ]
}

example response:/

{
 "function": "Historian/Write",
 "id": 12345,
 "status": 0,
 "variable": "New Variable"
}

Function "Historian/AddVariable"

Adds a new variable to the Historian. Variables are identified by a unique name. Calling this function with a name that already exists allows changing some properties. When trying to change properties that are not changeable (especially anything that affects file storage format), an error occurs.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/AddVariable",
 "id": 12345,
 "variable":
 {
  "name": "New Variable",
  "type": "UInt16",
  "enabled": true,
  "opc_enabled": true,
  "opc_conn": "S7-1500",
  "opc_variable": "Datablocks.OPC_DB.Temperature",
  "opc_resolution": "second",
  "file_save": false,
  "mem_size": 100
 }
}

example response:

{
 "function": "Historian/AddVariable",
 "id": 12345,
 "status": 0,
 "variable": "New Variable"
}

Function "Historian/DeleteVariable"

Deletes a variable from the Historian. In case of file logging, the data files are not removed.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/DeleteVariable",
 "id": 12345,
 "variable": "New Variable"
}

example response:

{
 "function": "Historian/DeleteVariable",
 "id": 12345,
 "status": 0,
 "variable": "New Variable"
}

Function "Historian/ReadVariable"

Reads a variable configuration from the Historian.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/ReadVariable",
 "id": 12345,
 "variable": "New Variable"
}

example response:

{
 "function": "Historian/ReadVariable",
 "id": 12345,
 "status": 0,
 "variable":
 {
  "name": "New Variable",
  "type": "UInt16",
  "enabled": true,
  "opc_enabled": true,
  "opc_conn": "S7-1500",
  "opc_variable": "Datablocks.OPC_DB.Temperature",
  "opc_resolution": "second",
  "file_save": false,
  "mem_size": 100
 }
}

Function "Historian/ListVariables"

Reads the list of variable configurations from the Historian.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/ListVariables",
 "id": 12345,
 "startoffset": 0,
 "variablecount": 100
}

example response:

{
 "function": "Historian/ListVariables",
 "id": 12345,
 "status": 0,
 "variables": [
 {
  "name": "New Variable",
  "type": "UInt16",
  "enabled": true,
  "opc_enabled": true,
  "opc_conn": "S7-1500",
  "opc_variable": "Datablocks.OPC_DB.Temperature",
  "opc_resolution": "second",
  "file_save": false,
  "mem_size": 100
 }
 ],
 "blocked": false
}

Function "Historian/ReadGlobalSettings"

Reads the global settings object of the historian

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/ReadGlobalSettings",
 "id": 12345
}

example response:

{
 "function": "Historian/ReadGlobalSettings",
 "id": 12345,
 "status": 0,
 "mindiskspace": 1000
}

Function "Historian/WriteGlobalSettings"

Writes the global settings object of the historian

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/WriteGlobalSettings",
 "id": 12345,
 "mindiskspace": 1000
}

example response:

{
 "function": "Historian/WriteGlobalSettings",
 "id": 12345,
 "status": 0
}

Function "Historian/ReadChangeTimestamp"

Reads the timestamp of the last historian variable change (addition, modification or deletion).

Additional request properties:

Additional response properties:

example request: {
 "function": "Historian/ReadChangeTimestamp",
 "id": 12345
}
example response: {
 "function": "Historian/ReadChangeTimestamp",
 "id": 12345,
 "status": 0,
 "time": "2021-04-20T11:30:00Z"
}

Function "Historian/DiagVariable"

Reads diagnostic information for a historian variable.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/DiagVariable",
 "id": 12345,
 "variable": "New Variable"
}

example response:

{
 "function": "Historian/DiagVariable",
 "id": 12345,
 "status": 0,
 "variable": "New Variable",
 "starttime": "2021-04-20T11:30:00Z",
 "currenttime": "2021-04-20T11:30:10Z",
 "currentquality": 0
}

Function "Historian/ReadStruct"

Reads structure information for a historian variable. Can be used to decode structured data.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/ReadStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}

example response:

{
 "function": "Historian/ReadStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure",
 "structcomment": "commment text ...",
 "structdata": [
  {
   "name": "element 1",
   "type": "uint8",
   "arraylength": 10
  },
  {
   "name": "element 2",
   "type": "uint32"
  }
 ]
}

Function "Historian/WriteStruct"

Writes structure information for a historian variable. The Historian doesn't use this, but it can be read back via "Historian/ReadStruct".

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/WriteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure",
 "structcomment": "commment text ...",
 "structdata": [
  {
   "name": "element 1",
   "type": "uint8",
   "arraylength": 10
  },
  {
   "name": "element 2",
   "type": "uint32"
  }
 ]
}

example response:

{
 "function": "Historian/WriteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}

Historian/ListStructs

Lists structure information for a historian variable.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/ListStructs",
 "id": 12345,
 "variable": "New Variable",
 "startoffset": 0
}

example response:

{
 "function": "Historian/ListStructs",
 "id": 12345,
 "variable": "New Variable",
 "structs": [
  {
   "structname": "New Structure",
   "structcomment": "commment text ...",
   "structdata": [
    {
     "name": "element 1",
     "type": "uint8",
     "arraylength": 10
    },
    {
     "name": "element 2",
     "type": "uint32"
    }
   ]
  }
 ]
}

Function "Historian/DeleteStruct"

Deletes structure information for a historian variable.

Additional request properties:

Additional response properties:

example request:

{
 "function": "Historian/DeleteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}

example response:

{
 "function": "Historian/DeleteStruct",
 "id": 12345,
 "variable": "New Variable",
 "structname": "New Structure"
}

value objects

properties:

example:

{ "quality": 0, "time": "2021-04-20T11:30:00Z", "value": 10 }

variable object

general properties:

properties for OPC data acquisation:

properties for data storage:

example:

{
 "name": "New Variable",
 "type": "uint16",
 "enabled": true,
 "opc_enabled": true,
 "opc_conn": "S7-1500",
 "opc_variable": "Datablocks.OPC_DB.Temperature",
 "opc_resolution": "second",
 "file_save": false,
 "mem_size": 100
}

structure element object

properties:

structure layout rules:

resolution values

aggregate values

ISO-8601 time format

note: this is only a subset of ISO-8601

2021-04-20T11:30:10.123+00:00
^    ^  ^  ^  ^  ^  ^  ^------- optional Timezone offset, allowed are "Z" (UTC)
|    |  |  |  |  |  |           or a zone difference in hours (and optionally
|    |  |  |  |  |  |           minutes), positive is east, UTC if not given
|    |  |  |  |  |  +---------- optional second fractions, up to 9 digits are
|    |  |  |  |  |              supported
|    |  |  |  |  +------------- second, always 2 digits
|    |  |  |  +---------------- minute, always 2 digits
|    |  |  +------------------- hour, always 2 digits, 24-hour format
|    |  +---------------------- day, always 2 digits
|    +------------------------- month, always 2 digits
+------------------------------ year, always 4 digits

Other ISO-8601 formats (e.g. week numbers, day-of-year, ...) are not supported. All returned timestamp values are in UTC.

Data types

Status codes

Other numbers signal an unspecified or undocumented error. Please contact TANI support in such cases.

Quality codes

Other numbers signal an unspecified or undocumented error. Please contact TANI support in such cases.