HTTP Request¶
The http_request
component lets you make HTTP/HTTPS requests. First, you need to setup a component:
# Example configuration entry
http_request:
useragent: esphome/device
timeout: 10s
Configuration variables:¶
useragent (Optional, string): User-Agent header for requests. Defaults to
ESPHome
.timeout (Optional, Time): Timeout for request. Defaults to
5s
.id (Optional, ID): Manually specify the ID used for code generation.
follow_redirects (Optional, boolean): Enable following HTTP redirects. Defaults to
true
.redirect_limit (Optional, integer): Maximum amount of redirects to follow when enabled. Defaults to
3
.
ESP8266 Options:
esp8266_disable_ssl_support (Optional, boolean): Whether to include SSL support on ESP8266s. Defaults to
no
. See esp8266_disable_ssl_support for more info
esp8266_disable_ssl_support
¶
This options allows you to disable inclusion of SSL libraries. This is required on a flash
constrained devices (512k or 1M) which does not have enough space to support
SSL and OTA concurrently. The flashing will fail with the following error
Error: ESP does not have enough space to store OTA file
.
HTTP Request Actions¶
Component support a number of actions that can be used to send requests.
http_request.get
Action¶
This action sends a GET request.
on_...:
- http_request.get:
url: https://esphome.io
headers:
Content-Type: application/json
verify_ssl: false
on_response:
then:
- logger.log:
format: 'Response status: %d, Duration: %u ms'
args:
- status_code
- duration_ms
# Short form
- http_request.get: https://esphome.io
Configuration variables:
url (Required, string, templatable): URL to send request.
headers (Optional, mapping): Map of HTTP headers. Values are templatable.
verify_ssl (Optional, boolean): Verify the SSL certificate of the endpoint. Defaults to
true
.on_response (Optional, Automation): An automation to perform when the request is finished.
Note
Currently ESPHome can’t verify the SSL certificate of the endpoint.
Set verify_ssl: false
to make HTTPS request.
http_request.post
Action¶
This action sends a POST request.
on_...:
- http_request.post:
url: https://esphome.io
headers:
Content-Type: application/json
json:
key: value
verify_ssl: false
# Short form
- http_request.post: https://esphome.io
Configuration variables:
body (Optional, string, templatable): A HTTP body string to send with request.
json (Optional, mapping): A HTTP body in JSON format. Values are templatable. See Examples.
All other options from http_request.get Action.
http_request.send
Action¶
This action sends a request.
on_...:
- http_request.send:
method: PUT
url: https://esphome.io
headers:
Content-Type: application/json
body: "Some data"
verify_ssl: false
Configuration variables:
method (Required, string): HTTP method to use (
GET
,POST
,PUT
,DELETE
,PATCH
).All other options from http_request.post Action.
on_response
Trigger¶
This automation will be triggered when the HTTP request is finished and will supply these parameters:
status_code
asint
- http response codeduration_ms
asuint32
- time taken to complete the request
on_...
then:
- http_request.get:
url: https://esphome.io
verify_ssl: false
on_response:
then:
- logger.log:
format: "Response status: %d, Duration: %u ms"
args:
- status_code
- duration_ms
Examples¶
Templatable values¶
on_...:
- http_request.post:
url: !lambda |-
return ((std::string) "https://esphome.io?state=" + id(my_sensor).state).c_str();
headers:
X-Custom-Header: !lambda |-
return ((std::string) "Value-" + id(my_sensor).state).c_str();
body: !lambda |-
return id(my_sensor).state;
POST Body in JSON format (syntax 1)¶
Note: all values of the map should be a strings.
It’s impossible to send boolean
or numbers
with this syntax.
on_...:
- http_request.post:
url: https://esphome.io
verify_ssl: false
json:
key: !lambda |-
return id(my_sensor).state;
greeting: "Hello World"
# Will send:
# {"key": "42.0", "greeting": "Hello World"}
POST Body in JSON format (syntax 2)¶
Note: use this syntax to send boolean
or numbers
in JSON.
The JSON message will be constructed using the ArduinoJson library.
In the json
option you have access to a root
object which will represents the base object
of the JSON message. You can assign values to keys by using the root["KEY_NAME"] = VALUE;
syntax
as seen below.
on_...:
- http_request.post:
url: https://esphome.io
verify_ssl: false
json: |-
root["key"] = id(my_sensor).state;
root["greeting"] = "Hello World";
# Will send:
# {"key": 42.0, "greeting": "Hello World"}
GET values from a JSON body response¶
Assuming that the server returns a response in a JSON object over HTTP 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 (with id
set to player_volume
):
on_...:
- http_request.get:
url: https://esphome.io
on_response:
then:
- lambda: |-
json::parse_json(id(http_request_data).get_string(), [](JsonObject root) {
id(player_volume).publish_state(root["vol"]);
});
Note: don’t forget to set the id
for the main http_request
component, to http_request_data
.