87 lines
2.9 KiB
Markdown
87 lines
2.9 KiB
Markdown
# Event Data
|
|
|
|
Event data can be fetched like this:
|
|
|
|
```bash
|
|
curl "https://data-api.psi.ch/api/4/events?backend=sf-databuffer&channelName=S10BC01-DBPM010:Q1&begDate=2024-02-15T12:41:00Z&endDate=2024-02-15T12:42:00Z"
|
|
```
|
|
|
|
Parameters:
|
|
- `backend`: the backend that the channel exists in, e.g. `sf-databuffer`.
|
|
- `channelName`: the name of the channel.
|
|
- `begDate`: start of the time range, inclusive. In ISO format e.g. `2024-02-15T12:41:00Z`.
|
|
- `endDate`: end of the time range, exclusive.
|
|
- `allowLargeResult=true` indicates that the client is prepared to accept also larger responses compared to
|
|
what might be suitable for a typical browser.
|
|
|
|
By default, events are returned as a json object.
|
|
|
|
Note: if the channel changes data type within the requested date range, then the
|
|
server will return values for that data type which covers the requested
|
|
date range best.
|
|
|
|
Note: if the server decides that the requested dataset gets "too large" then the response will contain
|
|
the key `continueAt` which indicates that the response is incomplete and that the caller should
|
|
issue another request with `begDate` as given by `continueAt`.
|
|
|
|
|
|
## Events as framed JSON stream
|
|
|
|
To download larger amounts of JSON data it recommended to use the `json-framed` content encoding.
|
|
Using this encoding, the server can send the requested events as a stream of json objects, where each
|
|
json object contains a batch of events.
|
|
This content encoding is triggered via the `Accept: application/json-framed` header in the request.
|
|
|
|
The returned body looks like:
|
|
```
|
|
[JSON-frame]
|
|
[JSON-frame]
|
|
[JSON-frame]
|
|
... etc
|
|
```
|
|
|
|
where each `[JSON-frame]` looks like:
|
|
```
|
|
[length N of the following JSON object: uint32 little-endian]
|
|
[reserved: 12 bytes of zero-padding]
|
|
[JSON object: N bytes]
|
|
[padding: P zero-bytes, 0 <= P <= 7, such that (N + P) mod 8 = 0]
|
|
```
|
|
|
|
|
|
## Events as framed CBOR stream
|
|
|
|
The Concise Binary Object Representation (RFC 8949) can be a more compact option to transfer data.
|
|
Usage of the `Accept: application/cbor-framed` header in the request causes the api to return
|
|
the data as a stream of CBOR objects. Each CBOR-object will contain a batch of events.
|
|
|
|
The http body of the response then looks like this:
|
|
|
|
```
|
|
[CBOR-frame]
|
|
[CBOR-frame]
|
|
[CBOR-frame]
|
|
... etc
|
|
```
|
|
|
|
where each `[CBOR-frame]` looks like:
|
|
```
|
|
[length N of the following CBOR object: uint32 little-endian]
|
|
[reserved: 12 bytes of zero-padding]
|
|
[CBOR object: N bytes]
|
|
[padding: P zero-bytes, 0 <= P <= 7, such that (N + P) mod 8 = 0]
|
|
```
|
|
|
|
Most returned CBOR objects are data objects and look like this in equivalent json notation:
|
|
```json
|
|
{
|
|
"tss": [1, 2, 3, 4],
|
|
"values": [42, 60, 55, 20]
|
|
}
|
|
```
|
|
where `tss` is the array of timestamps and `values` the corresponding array of values.
|
|
|
|
Note: "data" CBOR objects are currently identified by the presence of the `tss` key. There can be
|
|
other types of CBOR objects, like log or statistics.
|
|
The next update will add a type-tag to discriminate them, but for now, look for the key `tss`.
|