From 6f44024f95bc5110643f74ca208fc74e82574926 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sat, 22 Feb 2020 06:31:06 -1000 Subject: [PATCH] xml and jsonpath support (#12084) * xml and jsonpath support https://github.com/home-assistant/home-assistant/pull/31809 * adjust for lint * grammar * Fix xml conversion output, add a more complex example * Update rest.markdown * Added note about json_attributes_path * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update rest.markdown * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update source/_integrations/rest.markdown Co-Authored-By: Franck Nijhof * Update rest.markdown Co-authored-by: Franck Nijhof --- source/_integrations/rest.markdown | 133 ++++++++++++++++++++++++++++- 1 file changed, 130 insertions(+), 3 deletions(-) diff --git a/source/_integrations/rest.markdown b/source/_integrations/rest.markdown index 69fbf37cc367..77cdd9402f27 100644 --- a/source/_integrations/rest.markdown +++ b/source/_integrations/rest.markdown @@ -105,12 +105,16 @@ headers: required: false type: [string, list] json_attributes: - description: A list of keys to extract values from a JSON dictionary result and then set as sensor attributes. - reqired: false + description: A list of keys to extract values from a JSON dictionary result and then set as sensor attributes. If the endpoint returns XML with the "text/xml" content type, it will automatically be converted to JSON according to this [specification](https://www.xml.com/pub/a/2006/05/31/converting-between-xml-and-json.html) + required: false type: [string, list] +json_path_attributes: + description: A [JSONPath](https://goessner.net/articles/JsonPath/) that references the location of the `json_attributes` in the JSON content. + required: false + type: string force_update: description: Sends update events even if the value hasn't changed. Useful if you want to have meaningful value graphs in history. - reqired: false + required: false type: boolean default: false {% endconfiguration %} @@ -264,6 +268,26 @@ sensor: ``` {% endraw %} +[JSONPlaceholder](https://jsonplaceholder.typicode.com/) provides sample JSON data for testing. In the below example, JSONPath locates the attributes in the JSON document. [JSONPath Online Evaluator](https://jsonpath.com/) provides a tool to test your JSONPath. If the endpoint returns XML, it will be converted to JSON using `xmltodict` before searching for attributes. You may find the [XMLtoDict debug tool](https://xmltodict-debugger.glitch.me/) helpful for testing how your XML converts to JSON. + +{% raw %} + +```yaml +sensor: + - platform: rest + name: JSON users + json_attributes_path: "$.[0].address" + json_attributes: + - street + - suite + - city + - zipcode + resource: https://jsonplaceholder.typicode.com/users + value_template: '{{ value_json[0].name }}' +``` + +{% endraw %} + This sample fetches a weather report from [OpenWeatherMap](https://openweathermap.org/), maps the resulting data into attributes of the RESTful sensor and then creates a set of [template](/integrations/template) sensors that monitor the attributes and present the values in a usable form. {% raw %} @@ -358,3 +382,106 @@ sensor: unit_of_measurement: '°C' ``` {% endraw %} + +The below example allows shows how to extract multiple values from a dictionary with `json_attributes` and `json_attributes_path` from the XML of a Steamist Steambath Wi-Fi interface and use them to create a switch and multiple sensors without having to poll the endpoint numerous times. + +In the below example `json_attributes_path` is set to `$.response` which is the location of the `usr0`, `pot0`, ... attributes used for `json_attributes`. + +{% raw %} + +```yaml +sensor: +# Steam Controller + - platform: rest + name: Steam System Data + resource: http://192.168.1.105/status.xml + json_attributes_path: "$.response" + scan_interval: 15 + value_template: 'OK' + json_attributes: + - "usr0" + - "pot0" + - "temp0" + - "time0" + - platform: template + sensors: + steam_temp: + friendly_name: Steam Temp + value_template: '{{ states.sensor.steam_system_data.attributes["temp0"] | regex_findall_index("([0-9]+)XF") }}' + unit_of_measurement: "°F" + steam_time_remaining: + friendly_name: "Steam Time Remaining" + value_template: '{{ states.sensor.steam_system_data.attributes["time0"] }}' + unit_of_measurement: "minutes" + +switch: + - platform: template + switches: + steam: + value_template: '{{ states.sensor.steam_system_data.attributes["usr0"] | int >= 1 }}' + turn_on: + - service: rest_command.set_steam_led + data: + led: 6 + - service: homeassistant.update_entity + data: + entity_id: sensor.steam_system_data + - delay: 00:00:15 + - service: homeassistant.update_entity + data: + entity_id: sensor.steam_system_data + turn_off: + - service: rest_command.set_steam_led + data: + led: 7 + - service: homeassistant.update_entity + data: + entity_id: sensor.steam_system_data + - delay: 00:00:15 + - service: homeassistant.update_entity + data: + entity_id: sensor.steam_system_data + friendly_name: Steam + +rest_command: + set_steam_led: + url: http://192.168.1.105/leds.cgi?led={{ led }} +``` + +{% endraw %} + +For reference, the XML content of endpoint shown above example is below: + +```xml + + + + 0 + 12556 + 48 + alexander + + 0 + 0 + 0 + 0 + 0 + + 0 + 0 + 0 + 0 + 0 + 0 + 0 + 0 + up + up + up + up + 0 + 0 + 0x73XF0x73XF + 0 + +```