The request URL for retrieving samples for a specific channel has the following form:
/archive/<archive key>/samples/<channel name>?start=<start time-stamp>& ↪end=<end time-stamp>[&count=<desired number of samples>][&prettyPrint]
The archive key is the numeric key of the
archive as specified in the list of archives (typically
1).
The channel name is the name of the channel
for which samples are requested.
The channel name must be URL encoded so that all special characters
(in particular those that have a special meaning in a URL, like the
question mark) are encoded with %xx where xx is the hexadecimal
character code.
When the channel name contains non-ASCII characters, those characters
are expected to be specified in UTF-8 encoding.
The start time-stamp specifies the start of
the interval for which samples are requested.
The time stamp is specified as the number of nanoseconds since epoch
(January 1st, 1970, 00:00:00 UTC).
The end time-stamp specifies the end of
the interval for which samples are requested.
The time stamp is specified as the number of nanoseconds since epoch
(January 1st, 1970, 00:00:00 UTC).
The count parameter is optional.
If specified, the desired number of samples
is a strictly positive number that specifies the number of samples
that should be returned.
The number of samples returned will usually not match this number
exactly.
However, if samples with various densities are available, the density
which will result in the number of samples closest to the requested
number is chosen.
If this parameter is not specified, raw samples are used.
If the optional prettyPrint parameter is present,
the output is formatted nicely, which can be useful for debugging.
Usually, this parameter should be omitted because this will result in
a more compact representation, saving bandwidth.
The response is a JSON array, each element being one sample (JSON object). In addition to the samples between the start and the end time-stamp, one sample at or before the start time-stamp and one sample at or after the end time-stamp is returned (if such samples exist at all). This way, the returned data is sufficient for creating a plot covering the whole interval, even if the specified time stamps do not exactly match the time stamps of samples.
Each of the sample objects can have the following fields:
| Field name | Internal data type | JSON data type | Description |
|---|---|---|---|
| time | big integer | number (must be in integer format) | time-stamp in nanoseconds since epoch (January 1st, 1970, 00:00:00 UTC) |
| severity | see below | object | alarm severity |
| status | string | string | alarm status (might contain additional information about the severity) |
| quality | string | string | sample quality - one of “Original” or “Interpolated” (not case-sensitive) |
| metaData | see below | object | meta-data of the sample |
| type | string | string | sample type - must be one of “double”, “enum”, “long”, “minMaxDouble”, or “string” (not case-sensitive) |
| value | depends on sample type | array | array of values making up the sample |
| minimum | double | number or string | minimum value – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity) |
| maximum | double | number or string | maximum value – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity) |
The type, time,
severity, status,
quality, and value fields are
always present.
The minimum and maximum fields
are only present if the type is minMaxDouble.
The type field must always come before the
value field.
The quality field indicates whether the sample is a
raw sample (“Original”) or a decimated sample (“Interpolated”).
The metaData field may be present for all types
except the string type.
The format of the meta-data depends on the type (see below).
At places where a number may also be expressed as a JSON string, the
use of a string is reserved to cases where the number cannot be
represented as a JSON number (infinity and not-a-number).
Valid strings are inf, infinity,
+inf, +infinity,
-inf, -infinity, and
nan (all not case-sensitive).
The value is always represented as a JSON array. The type of the array elements depends on the sample type:
| Sample type | Element JSON type | Remarks |
|---|---|---|
| double | number or string | must be in number format unless it cannot be expressed as a JSON number (e.g. infinity) |
| enum | number | must be in integer format, numbers outside the interval [-231, 231-1] may be truncated |
| long | number | must be in integer format, numbers outside the interval [-263, 263-1] may be truncated |
| minMaxDouble | number or string | must be in number format unless it cannot be expressed as a JSON number (e.g. infinity) |
| string | string |
The minMaxDouble type is used for samples that have
been aggregates from several raw samples and the
minimum and maximum represent
the least and the greatest value of any of the original samples.
Sample of type minMaxDouble typically have a
quality of “Interpolated” because they represent
decimated samples.
The severity is a JSON object with the following fields (all mandatory):
| Field name | Internal data type | JSON data type | Description |
|---|---|---|---|
| level | string | string | sample severity - one of “OK”, “MINOR”, “MAJOR”, or “INVALID” (all not case-sensitive) |
| hasValue | boolean | boolean | tells whether the sample has a value (or just signals a condition with a certain severity) |
The meta-data is a JSON object.
The format depends on the sample type.
Samples that are of the string type do not have
meta data.
Samples that are of the enum type can have meta
data in the following format (all fields are mandatory):
| Field name | Internal data type | JSON data type | Description |
|---|---|---|---|
| type | string | string | value is always “enum” (not case-sensitive) |
| states | array of strings | array of strings | labels for the enum states |
Samples that are of the double,
long, or minMaxDouble type can
have meta data in the following format (all fields are mandatory):
| Field name | Internal data type | JSON data type | Description |
|---|---|---|---|
| type | string | string | value is always “numeric” (not case-sensitive) |
| precision | integer | number | number of fractional digits to be displayed, must be in integer format |
| unit | string | string | engineering units of the value |
| displayLow | double | number or string | lower display limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity) |
| displayHigh | double | number or string | upper display limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity) |
| warnLow | double | number or string | lower warning limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity) |
| warnHigh | double | number or string | upper warning limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity) |
| alarmLow | double | number or string | lower alarm limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity) |
| alarmHigh | double | number or string | upper alarm limit – must be in number format unless it cannot be expressed as a JSON number (e.g. infinity) |
Request:
GET /archive-access/api/1.0/archive/1/samples/testCalc?start=0& ↪end=1500000000000000000&prettyPrint HTTP/1.0
Response:
[ {
"time" : 1468429059824011000,
"severity" : {
"level" : "OK",
"hasValue" : true
},
"status" : "NO_ALARM",
"quality" : "Original",
"metaData" : {
"type" : "numeric",
"precision" : 2,
"units" : "V",
"displayLow" : 0.0,
"displayHigh" : 0.0,
"warnLow" : "NaN",
"warnHigh" : 12.0,
"alarmLow" : "NaN",
"alarmHigh" : 15.0
},
"type" : "double",
"value" : [ 7.0 ]
}, {
"time" : 1468429060825564000,
"severity" : {
"level" : "MINOR",
"hasValue" : true
},
"status" : "HIGH",
"quality" : "Original",
"metaData" : {
"type" : "numeric",
"precision" : 2,
"units" : "V",
"displayLow" : 0.0,
"displayHigh" : 0.0,
"warnLow" : "NaN",
"warnHigh" : 12.0,
"alarmLow" : "NaN",
"alarmHigh" : 15.0
},
"type" : "double",
"value" : [ 12.0 ]
} ]