mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-10 15:11:59 +01:00
631199a1f7
Replace https://jsonpath.herokuapp.com/ (dead link) with https://jsonpath.fly.dev/ Signed-off-by: cyr1l0u <164659715+cyr1l0u@users.noreply.github.com>
68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
# JsonPath Transformation Service
|
|
|
|
Extracts values from a JSON string using a [JsonPath](https://github.com/jayway/JsonPath#jayway-jsonpath) expression.
|
|
|
|
Given the following JSON string:
|
|
|
|
```json
|
|
[{ "device": { "location": "Outside", "status": { "temperature": 23.2 }}}]
|
|
```
|
|
|
|
The expression `$.device.location` extracts the string `Outside`.
|
|
The JsonPath expression `$.device.status.temperature` extracts the string `23.2`.
|
|
|
|
## Examples
|
|
|
|
### Items
|
|
|
|
```java
|
|
String Temperature_json "Temperature [JSONPATH($.device.status.temperature):%s °C]" {...}
|
|
Number Temperature "Temperature [%.1f °C]"
|
|
```
|
|
|
|
### Rules
|
|
|
|
```java
|
|
rule "Convert JSON to Item Type Number"
|
|
when
|
|
Item Temperature_json changed
|
|
then
|
|
// use the transformation service to retrieve the value
|
|
val newValue = transform("JSONPATH", "$.device.status.temperature", Temperature_json.state.toString)
|
|
|
|
// post the new value to the Number Item
|
|
Temperature.postUpdate( newValue )
|
|
end
|
|
```
|
|
|
|
Now the resulting Number can also be used in the label to [change the color](https://docs.openhab.org/configuration/sitemaps.html#label-and-value-colors) or in a rule as a value to compare.
|
|
|
|
## Differences to standard JsonPath
|
|
|
|
Compared to standard JsonPath, the transformation returns single values instead of arrays.
|
|
The transformation also will not ever return `null`.
|
|
This makes it possible to use the transform in labels or output channels of Things.
|
|
|
|
If the JsonPath expression provided results in no matches, the transformation will return the entire original JSON string.
|
|
|
|
## Usage as a Profile
|
|
|
|
The transformation can be used in a `Profile` on an `ItemChannelLink` too.
|
|
|
|
One example for configuring it in the `.items` file:
|
|
|
|
```java
|
|
String <itemName> { channel="<channelUID>"[profile="transform:JSONPATH", function="<jsonPath>", sourceFormat="<valueFormat>"]}
|
|
```
|
|
|
|
The JsonPath expression to be used has to be set in the `function` parameter.
|
|
The parameter `sourceFormat` is optional and can be used to format the input value **before** the transformation, i.e. `%.3f`.
|
|
If omitted, the default is `%s`, so the input value will be returned from the transformation without any format changes.
|
|
|
|
This profile is a one-way transformation; only values from a device toward the item are changed.
|
|
|
|
## Further Reading
|
|
|
|
- An extended [introduction](https://www.w3schools.com/js/js_json_intro.asp) can be found at W3School.
|
|
- As JsonPath transformation is based on [Jayway](https://github.com/json-path/JsonPath), using an [online validator](https://jsonpath.fly.dev/) which also uses Jayway will give the most similar results.
|