HA文档 目录

  1. 主页
  2. HA文档
  3. HA文档
  4. API服务
  5. REST API

REST API

REST API对外接收和返回JSON格式的数据。

认证

API访问需要提供在HomeAssistant配置文件中设置的密码。密码可以通过HTTP头提供,也可以在URL中提供。

  • 在HTTP头中提供密码:
    curl -X GET -H "x-ha-access: YOURPASSWORD" http://IP_ADDRESS:8123/api/states
  • 在URL中提供密码:
    curl -X GET http://IP_ADDRESS:8123/api/states?api_password=YOURPASSWORD
    你也可以在浏览器中直接输入http://IP_ADDRESS:8123/api/states?api_password=YOURPASSWORD,观察对应输出。

当返回状态为200或201时代表成功,其它可能的返回包括:

  • 400(错误的请求)
  • 401(未通过认证)
  • 404(没有找到请求的资源)
  • 405(不允许的方法,比如,调用服务,只允许用POST方法,而不允许用GET方法)

API服务内容

  • GET /api/
    返回API是否在运行

    curl访问样例命令:
    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" http://localhost:8123/api/
  • GET /api/config
    返回当前的配置

    curl访问样例命令:

    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" http://localhost:8123/api/config
  • GET /api/discovery_info
    返回HomeAssistant实例的基础信息

    curl访问样例命令:
    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" http://localhost:8123/api/discovery_info
  • GET /api/events
    返回系统内事件对象的数组,每一个事件对象包含事件名称和监听者的数量。

    curl访问样例命令:
    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" http://localhost:8123/api/events
  • GET /api/services
    返回系统内服务对象的数组,每一个服务对象包含服务的域与服务。

    curl访问样例命令:
    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" http://localhost:8123/api/services
  • GET /api/history/period/<timestamp>
    返回在过去一段事件内状态变化的数组。数组内每个对象包含实体的具体属性值
    (格式为YYYY-MM-DDThh:mm:ssTZD)可选,缺省为调用前24小时,它代表历史时间段开始的时间:
    可以在GET调用时增加以下参数:

    • filter_entity_id=<entity_id>:仅查询某个实体的状态变化
    • end_time=<timestamp>:历史时间段结束的时间,缺省为调用当时

    curl访问样例命令:
    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" \
    http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00

    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" \
    http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?filter_entity_id=sensor.temperature

    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" \
    http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?end_time=2016-12-31T00%3A00%3A00%2B02%3A00

  • GET /api/states
    返回当前实体的状态的数组。每一个状态包含:实体ID,状态,最后修改时间,属性值。

    curl访问样例命令:
    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" http://localhost:8123/api/states

  • GET /api/states/<entity_id>
    返回某一个实体的状态(当没有此实体时返回404)。

    curl访问样例命令:
    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" \
    http://localhost:8123/api/states/sensor.kitchen_temperature

  • GET /api/error_log
    返回当前HomeAssistant运行实例中所有的错误日志。
    (注:此返回是文本,plaintext)

    curl访问样例命令:
    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" \
    http://localhost:8123/api/error_log

  • GET /api/camera_proxy/camera.<entity_id>
    返回某一个摄像头实体的图片。
    curl访问样例命令:
    $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" \
    http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time=1462653861261 -o image.jpg-WMHAchina01
     
  • POST /api/states/<entity_id>
    创建或更新某个实体的状态。需要输入一段JSON编码,至少包含state值。

    返回状态200代表实体已存在,更新状态;返回状态201代表实体不存在,将创建。
    返回值为JSON格式的实体状态与属性内容:

    curl访问样例命令:
    $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" \
    -d '{"state": "25", "attributes": {"unit_of_measurement": "°C"}}' \
    http://localhost:8123/api/states/sensor.kitchen_temperature

  • POST /api/events/<event_type>
    触发一条事件。
    可以向事件传递JSON格式数据。

    返回的内容为:

  • POST /api/services/<domain>/<service>
    调用一个服务。在服务被调用后返回(如果超过10秒也会返回)。可以向服务传递JSON格式数据。

    返回服务被调用时更新的状态列表(即使更新并不是由于此服务造成的)。

    curl访问样例命令:

    • 调用开灯服务
      $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
      -H "Content-Type: application/json" \
      -d '{"entity_id": "switch.christmas_lights"}' \
      http://localhost:8123/api/services/switch/turn_on
    • 调用MQTT发布信息服务
      $ curl -X POST \
      -H "Content-Type: application/json" \
      -H "x-ha-access:YOUR_PASSWORD" \
      -d '{"payload": "OFF", "topic": "home/fridge", "retain": "True"}' \
      http://localhost:8123/api/services/mqtt/publish
  • POST /api/template
    渲染一段模板代码。

    返回渲染结果

    curl访问样例命令:
    $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
    -H "Content-Type: application/json" \
    -d '{"template": "It is {{ now }}!"}' http://localhost:8123/api/template
  • POST /api/event_forwarding
    设置将事件转发到另一个HomeAssistant实例需要传入JSON格式的转发目标HomeAssistant的API信息:

    如果转发设置成功,将会返回一条消息:
  • DELETE /api/event_forwarding
    取消事件转发到另一个HomeAssistant实例需要传入JSON格式的转发目标HomeAssistant的API信息:

    如果取消成功,将会返回一条信息:

    遇到问题了?快来学习免费在线课程吧,博学老司机在线答疑,找到更多志同道合的HA玩家一起进步

此文不允许转载,如需转载请与BD@hachina.io联系。

这篇文章对您有用吗? 0 0