Data Log WebSocket Queries and Parameters
- Nina Cardillo
Only data log WebSockets use queries and parameters.
The general purpose WebSocket is started by /iap/ws and does not use queries or parameters. Once you start a general WebSocket, you can use REST API requests to request ON-Demand GET requests.
A query specifies a selection rule for a specified object or objects. A query parameter can be specified and added to the end of a URI following a ? character.
The remainder of this section applies to data log WebSockets.
Query Syntax
A query in IAP/REST is a key-value pair along with an operator that specifies the relationship between the key and the value. The syntax for a query is {key}{operator}{value}. Multiple key-value pairs can be specified, separated by an & character as a logical AND, combining the parameters. The {key}, {operator}, and {value} have the following descriptions:
Key
The key identifies a property of the IAP/REST resources. When included in a path element, the key specifies a property within the IAP/REST object specified by the path element.
Operator
The operator specifies the relation between the key and value. The available operators are:
| Operator | Definition |
|---|---|
| == | Exact match |
| != | Exact mismatch (for a fully specified string) |
| =+ | Regular expression match, case-insensitive |
| !+ | Regular expression mismatch, case-insensitive |
| < | Less than (for numbers and timestamps) |
| <= | Less than or equal (for numbers and timestamps) |
| => | Equal or greater than (for numbers and timestamps) |
| > | Greater than (for numbers and timestamps |
Value
The value specifies the value of the property to be used to identify selected resources. The value can be:
An absolute value for scalar properties.
A regular expression for the regular expression match (=+) or regular expression mismatch (!+) operators.
For the regular expression match (=+) and regular expression mismatch (!+) operators, the regular expression syntax is defined as a subset of Perl 5 syntax supported by java.util.regex as described in the java.util.regex documentation at https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html .
Regular Expression Encoding
Special characters may need to be encoded before sending the IAP/WS request to the SmartServer. Not all instances of a special character need to be encoded. Encoding depends on where the special character is used in the IAP/WS request.
Encoding in IAP/WS is not the same as IAP/REST.
Device, block and datapoint names are not encoded except for spaces. This is different from the REST API which does require special characters in Device, block and datapoint to be encoded.
Regular expressions cannot include characters that are not allowed in URI paths. Any such characters must be percent encoded as described in https://en.wikipedia.org/wiki/Percent-encoding . For example, the following characters that are reserved in RFC 3986 must be encoded as shown below each character:
Following are additional special characters that require percent encoding:
For example, when you want to specify XIF names in your request, instead of instance names, you need to add *+xifName== which needs to be encoded to %2A%2BxifName==
&dpName=*+xifName=={datapoint XIF name} which needs to be encoded to &dpName=%2A%2BxifName=={datapoint XIF name}
Example: &dpName=*+xifName==nvoLuxLevel which needs to be encoded to &dpName=%2A%2BxifName==nvoLuxLevel
If you want to specify datapoint instance names, but do not want to use exact matches, then you need to add *+name== which needs to be encoded to %2A%2Bname==
&dpName=*+name=={datapoint instance name} which needs to be encoded to &dpName=%2A%2Bname=={datapoint instance name}
Example: &dpName=*+name==nvoLightLevel which needs to be encoded to &dpName=%2A%2Bname==nvoLightLevel
The &value parameter is used to specify timespans. The timespan request needs to be encoded.
Equal sign = in name parameters is not encoded, but it is in &value parameters.
Examples
1. To get all logs between UTC timestamp 2021-04-22T08:00:00.000 and 2021-04-22T17:35:10.000
Request:
|
Encoded: “*+” = “%2A%2B, “>” = “%3E”, “&” in range “%26” and “<=” = “%3C%3D”
|
2. To get all logs for a specific datapoint using instance name after UTC timestamp 2021-04-22T08:00:00.000
Datapoint Instance Name: Sensor 1/LightSensor/0/nvoLightLevel[1]
Request: datapoint instance name
|
Encoded: space = “%20”, “*+” = “%2A%2B, “>” = “%3E"
|
3. To get all logs for datapoints using instance name, which have light in the name after UTC timestamp 2021-04-22T08:00:00.000
Datapoint Instance Name: Sensor 1/LightSensor/0/nvoLightLevel[0], and Sensor 1/LightSensor/0/nvoLightLevel[1]
Request: datapoint instance name
|
Encoded: space = “%20”, “*+” = “%2A%2B, “=~” = “%3D%7E", “>” = “%3E"
|
4. To get all logs for a specific datapoint using XIF name between UTC timestamp 2021-04-22T08:00:00.000 and 2021-04-22T17:35:10.000
Datapoint XIF Name: Sensor 1/LightSensor/0/nvoLuxLevel[1]
Request: datapoint XIF name
|
Encoded: space name ("Sensor 1") = “%20”, “*+” = “%2A%2B, “>” = “%3E”, “&” in range “%26” and “<=” = “%3C%3D”
|