mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-02-13 01:11:24 +01:00
Add documentation for json component (#4349)
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
Chad Matsalla
GitHub
parent
0bd7b218d9
commit
9a2c57bd48
@ -246,6 +246,10 @@ can assign values to keys by using the ``root["KEY_NAME"] = VALUE;`` syntax as s
|
||||
|
||||
GET values from a JSON body response
|
||||
************************************
|
||||
If you want to retrieve the value for the vol key and assign it to a template sensor or number component whose id is
|
||||
set to player_volume you can do this, but note that checking for the presence of the key will prevent difficult-to-read
|
||||
error messages:
|
||||
|
||||
|
||||
This example assumes that the server returns a response as a JSON object similar to this:
|
||||
``{"status":"play","vol":"42","mute":"0"}``
|
||||
@ -263,14 +267,20 @@ whose ``id`` is set to ``player_volume``:
|
||||
then:
|
||||
- lambda: |-
|
||||
json::parse_json(body, [](JsonObject root) -> bool {
|
||||
id(player_volume).publish_state(root["vol"]);
|
||||
return true;
|
||||
if (root["vol"]) {
|
||||
id(player_volume).publish_state(root["vol"]);
|
||||
return true;
|
||||
}
|
||||
else {
|
||||
ESP_LOGD(TAG,"No 'vol' key in this json!");
|
||||
return false;
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`index`
|
||||
- :apiref:`http_request/http_request.h`
|
||||
- :doc:`/components/json`
|
||||
- :ghedit:`Edit`
|
||||
|
||||
132
components/json.rst
Normal file
132
components/json.rst
Normal file
@ -0,0 +1,132 @@
|
||||
json Component
|
||||
==============
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for parsing and building json within ESPHome.
|
||||
:keywords: json
|
||||
|
||||
The ``json`` component enables ESPHome to work with JSON data in automations, sensors, and HTTP requests. This is particularly useful for:
|
||||
|
||||
- Processing API responses
|
||||
- Sending structured data to external services
|
||||
- Parsing configuration from JSON files
|
||||
|
||||
What is JSON?
|
||||
|
||||
JSON is a text syntax that facilitates structured data interchange between all programming languages. JSON
|
||||
is a syntax of braces, brackets, colons, and commas that is useful in many contexts, profiles, and applications.
|
||||
JSON stands for JavaScript Object Notation and was inspired by the object literals of JavaScript aka
|
||||
ECMAScript as defined in the `ECMAScript Language Specification, Third Edition <https://ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf>`_ .
|
||||
|
||||
Example 1: Relatively complex JSON
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"first_name": "John",
|
||||
"last_name": "Smith",
|
||||
"is_alive": true,
|
||||
"age": 27,
|
||||
"address": {
|
||||
"street_address": "21 2nd Street",
|
||||
"city": "New York",
|
||||
"state": "NY",
|
||||
"postal_code": "10021-3100"
|
||||
},
|
||||
"phone_numbers": [
|
||||
{
|
||||
"type": "home",
|
||||
"number": "212 555-1234"
|
||||
},
|
||||
{
|
||||
"type": "office",
|
||||
"number": "646 555-4567"
|
||||
}
|
||||
],
|
||||
"children": [
|
||||
"Catherine",
|
||||
"Thomas",
|
||||
"Trevor"
|
||||
],
|
||||
"spouse": null
|
||||
}
|
||||
|
||||
Example 2: Simple JSON:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{"key": 42.0, "greeting": "Hello World"}
|
||||
|
||||
|
||||
Parsing JSON:
|
||||
-------------
|
||||
|
||||
This example assumes that the server returns a response as a JSON object similar to this:
|
||||
``{"status":"play","vol":"42","mute":"0"}``
|
||||
|
||||
|
||||
If you want to retrieve the value for the ``vol`` key and assign it to a template ``sensor`` or ``number`` component
|
||||
whose ``id`` is set to ``player_volume`` you can do this, but note that checking for the presence of the key will prevent difficult-to-read error messages:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
on_...:
|
||||
- http_request.get:
|
||||
url: https://esphome.io
|
||||
capture_response: true
|
||||
on_response:
|
||||
then:
|
||||
- lambda: |-
|
||||
json::parse_json(body, [](JsonObject root) -> bool {
|
||||
if (root["vol"]) {
|
||||
id(player_volume).publish_state(root["vol"]);
|
||||
return true;
|
||||
}
|
||||
else {
|
||||
ESP_LOGD(TAG,"No 'vol' key in this json!");
|
||||
return false;
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
Building JSON:
|
||||
--------------
|
||||
|
||||
You can build JSON in a lambda with a nested array like this:
|
||||
|
||||
.. code-block::
|
||||
|
||||
on_...:
|
||||
- http_request.post:
|
||||
url: https://esphome.io
|
||||
json: |-
|
||||
root["key"] = id(my_sensor).state;
|
||||
root["greeting"] = "Hello World";
|
||||
|
||||
This will send::
|
||||
``{"key": 42.0, "greeting": "Hello World"}``
|
||||
|
||||
|
||||
Troubleshooting Errors:
|
||||
-----------------------
|
||||
A very common error when deserializing is:
|
||||
|
||||
.. code-block::
|
||||
|
||||
JSON parse error: InvalidInput
|
||||
|
||||
The software ESPHome uses does not provide particularly informative messages as to why, but
|
||||
the people at ArduinoJson have created a `wonderful troubleshooter <https://arduinojson.org/troubleshooter>`__.
|
||||
|
||||
Another important resource is `JSONLint <https://jsonlint.com/>`__. It will help you determine if the JSON you are using is valid. It must be valid to work with ESPHome's deserializer and it probably needs to be valid for the destination, if you are sending it.
|
||||
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`index`
|
||||
- :apiref:`http_request/http_request.h`
|
||||
- :apiref:`json/json_util.h`
|
||||
- `ArduinoJson <https://arduinojson.org/>`
|
||||
- :ghedit:`Edit`
|
||||
|
||||
1
images/json.svg
Normal file
1
images/json.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"><path d="M0 0H24V24H0z" fill="none"/><path d="M6 2C4.9 2 4 2.9 4 4v16c0 1.1.9 2 2 2h12c1.1.0 2-.9 2-2V4C20 2.9 19.1 2 18 2z"/><path style="fill:#f9f9f9" d="m8.9208984 17.592773q-.7851562.0-1.2597656-.46289-.46875-.457031-.46875-1.289063v-1.921875q0-.667968-.3222656-.996093Q6.5478516 12.588867 5.8505859 12.577148V11.43457q.7089844-.0293 1.0253907-.357422.3164062-.333984.3164062-.996093V8.1591797q0-.8554688.4570313-1.3007813Q8.1123047 6.4072266 8.9208984 6.4072266H10.075195V7.5205078H9.7353516q-.5332032.0-.7734375.3046875-.234375.3046875-.234375.9199219v1.7636718q0 .556641-.3398438.960938-.3339844.404296-.8730469.515625v.02344q.5566407.128906.8847657.533203.328125.398438.328125.94336v1.763671q0 .621094.234375.919922.2402343.304688.7734375.304688h.3398434v1.11914zm4.9921876-1.11914h.333984q.544922.0.773438-.304688.234375-.298828.234375-.919922v-1.763671q0-.539063.328125-.94336.333984-.404297.884765-.533203v-.02344q-.533203-.111326-.873046-.509763Q15.254883 11.071289 15.254883 10.508789V8.7451172q0-.6152344-.234375-.9199219Q14.791992 7.5205078 14.24707 7.5205078H13.913086V6.4072266h1.154297q.808594.0 1.265625.4511718.46289.4453125.46289 1.3007813v1.9218753q0 .65625.322266.990234t1.03125.363281v1.142578q-.708984.01172-1.03125.351563-.322266.339844-.322266.990234v1.921875q0 .826172-.46875 1.289063-.46875.46289-1.259765.46289h-1.154297z" aria-label="{ }"/></svg>
|
||||
|
After Width: | Height: | Size: 1.4 KiB |
@ -172,6 +172,7 @@ ESPHome-specific components or components supporting ESPHome device provisioning
|
||||
Improv via BLE, components/esp32_improv, improv.svg, dark-invert
|
||||
Improv via Serial, components/improv_serial, improv.svg, dark-invert
|
||||
Interval, components/interval, description.svg, dark-invert
|
||||
JSON, components/json, json.svg, dark-invert
|
||||
Script, components/script, description.svg, dark-invert
|
||||
|
||||
ESPHome Configuration
|
||||
|
||||
Loading…
Reference in New Issue
Block a user