yongxu/sparrow

apiprovicer服务接口文档

接口响应约定

{
  "code": 0,
  "message": "",
  "result": null
}

code为0，为请求成功

message保存相关的消息提示

result为服务器处理结果

1.服务功能

为厂商app提供平台原生的api调用能力

2.接口说明

接口URL	请求类型	功能说明
/application/v1/device/info	GET	根据device_key获取设备基本信息
/application/v1//devices/{identifier}/info	GET	根据设备identifier获取设备信息
/application/v1/devices/{identifier}/status/current	GET	获取设备当前状态
/application/v1/devices/{identifier}/status	PUT	设置设备当前设备的状态
/application/v1/devices/{identifier}/commands	POST	向指定设备发送命令
/application/auth	POST	获取app认证token

2.1 获取App Token

_首先应用方要获取当前应用的授权访问token,为后续的接口请求提供正确的认证,应用方就根据expireat值自动获取最新的token

接口URL: application/auth
请求方法: POST
请求参数: BODY

参数	类型	是否必填	说明
AppKey	字符串	Y	平台为应用分配的AppKey
Secretkey	字符串	Y	平台为应用分配的Secretkey

接口响应: JSON

{
  "code": 0,
  "message": "",
  "result": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBcHBJRCI6MSwiQXBwTmFtZSI6ImNsaWVudCIsIkFwcEtleSI6IjRkMjJmZDZjOWU4YWY0MzQwM2QwZmU2MWMwYzdlNTYzODc4YTg1YWE5ZDE4MGZmNjcyNmUwOWIxYTEzOTdjOTZkN2MyNjkzZWM4NjlhZmU3MDc5ODZmZDgyNTMxYzdlZiIsIlNlY3JldEtleSI6Im5yM3preHBLRDg0UTJCV1giLCJWZW5kb3JJRCI6IjFwczlkanBzd2kwY2RzN2NvZnlua3NvMzAwZXFsNGl1IiwiZXhwIjoxNjMwOTg0MTU2LCJpYXQiOjE2MzA4OTc3NTYsImlzcyI6ImFwaXByb3ZpZGVyIn0.t0KX26p_8Q5WxzU-96Gwg5t6iuFnA8iDmUJk8bmW4Uc",
    "expire_at": 1630984156
  }
}

字符	类型	说明
access_token	字符串	token字符串
expire_at	数字	精确到秒的过期时间戳

2.2 根据设备device_key获取设备信息

_厂商可以通过平台为设备生成的devicekey查询设备基础信息

请求URL: /application/v1/device/info
请求方法: GET
请求参数: Query

参数	类型	是否必填	说明
device_key	字符串	Y	设备device_key,注册流程可以得到这个数据

请求Header:

参数	类型	是否必填	说明
Authorization	字符串	Y	获取AppToken(2.1)接口返回的access_token字段值

请求响应:

{
  "code": 0,
  "message": "",
  "result": null,
  "data": {
    "identifier": "1-1-relay-test",
    "name": "TSL-8",
    "description": "模块",
    "version": "1.0.0"
  }
}

2.3 根据设备identifier获取设备基本信息

请求URL: /application/v1/devices/{identifier}/info
请求方法: GET
请求参数: Path参数

参数	类型	是否必填	说明
identifier	字符串	Y	设备的identifier,注册流程可以得到这个数据

请求Header:

参数	类型	是否必填	说明
App-Key	字符串	Y	由平台分配的应用AppKey的值
Authorization	字符串	Y	获取AppToken(2.1)接口返回的access_token字段值

请求响应: JSON

{
  "code": 0,
  "message": "",
  "result": null,
  "data": {
    "identifier": "1-1-relay",
    "name": "TSL-8",
    "description": "模块",
    "version": "1.0.0"
  }
}

2.4 根据设备identifier获取设备当前最新的状态值

请求URL: /application/v1/devices/{identifier}/status/current
请求方法: GET
请求参数: Path参数

参数	类型	是否必填	说明
identifier	字符串	Y	设备的identifier,注册流程可以得到这个数据

请求Header:

参数	类型	是否必填	说明
App-Key	字符串	Y	由平台分配的应用AppKey的值
Authorization	字符串	Y	获取AppToken(2.1)接口返回的access_token字段值

请求响应: JSON

data字符中的具体响应内容是根据产品配置中相应的字段名称生成的，以最终配置为准，平台会以格式化的数据，返回设备的最新状态

{
  "code": 0,
  "message": "",
  "result": null,
  "data": {
    "device_id": 9480,
    "outputState": {
      "route": 2,
      "value": 0
    }
  }
}

2.5 向指定设备发送指令

请求URL: /application/v1/devices/{identifier}/commands
请求方法: POST
请求参数: JSON BODY

参数	类型	是否必填	说明
identifier	字符串	Y	设备的identifier,注册流程可以得到这个数据

BODY体结构: 根据产品的配置文件

{
  "objects": [
    {
      "no": 1,
      "label": "outputState",
      "part": 1,
      "status": [
        {
          "value_type": 7,
          "name": "route"
        },
        {
          "value_type": 7,
          "name": "value"
        }
      ]
    },
    {
      "no": 2,
      "label": "inputState",
      "part": 1,
      "status": [
        {
          "value_type": 7,
          "name": "route"
        },
        {
          "value_type": 7,
          "name": "value"
        }
      ]
    },
    {
      "no": 3,
      "label": "temperature",
      "part": 1,
      "status": [
        {
          "value_type": 1,
          "name": "degrees"
        }
      ]
    },
    {
      "no": 4,
      "label": "humidity",
      "part": 1,
      "status": [
        {
          "value_type": 1,
          "name": "degrees"
        }
      ]
    }
  ],
  "commands": [
    {
      "no": 1,
      "name": "setState",
      "part": 1,
      "priority": 0,
      "params": [
        {
          "value_type": 7,
          "name": "no"
        },
        {
          "value_type": 7,
          "name": "state"
        },
        {
          "value_type": 8,
          "name": "subDeviceID"
        }
      ]
    }
  ],
  "events": []
}

例如上面的产品配置信息，commands字段有一个指令名称为setState,参数有三个，则传输的结构体为

{
  "setState": [
    1,
    1,
    1308
  ]
}

请求Header:

参数	类型	是否必填	说明
App-Key	字符串	Y	由平台分配的应用AppKey的值
Authorization	字符串	Y	获取AppToken(2.1)接口返回的access_token字段值

请求响应: JSON

{
  "code": 0,
  "message": "",
  "result": null
}

apiprovider.md 6.3 KB Állandó hivatkozás Előzmények Nyers