文档中心

# 云端API

# 使用说明

IOT平台提供项目、设备、服务等云端API，帮助快速开发应用，满足场景业务需求。

公共请求说明

API接口请求参数包括公共参数和自定义业务参数两部分。公共请求参数是调用每个API时都需要携带的请求参数, 包括服务命名空间、接口名称。自定义业务参数由各接口定义，根据调用方法不同，需要将参数携带至请求路径或者请求体中。API接口公共参数调用如下所示:

http://open-api.iot.aiqianqiu.com/v1/${namespace}?action=${action}

参数说明

序号 参数 类型 必填 备注
1 namespace String 是 接口类别
设备管理：device
场景管理：scene
2 action String 是 接口名称

公共响应说明

成功响应：

{
  "requestId": "8906582E6722409AA6C40E7863B733A5",
  "status": "success",
  "data": {
    "deviceName": "202152458412"
  }
}

失败响应：

{
  "requestId": "8906582E6722409AA6C40E7863B733A5",
  "data": {
    "msg": "认证失败，无法访问系统资源",
    "code": 100001
  },
  "status": "fail"
}

参数说明

序号 参数 类型 备注
1 requestId String 请求ID，调用API时由平台生成唯一请求标识
2 status String 接口调用状态是否成功
3 data Object 接口调用后，返回的数据，成功返回业务数据，失败返回错误信息
4 data.msg String 接口调用失败描述
5 data.code Integer 接口错误编码

# API安全鉴权

平台需要对API调用方进行资源权限校验，使用API时需要在请求header中携带统一的安全鉴权信息。

安全鉴权机制

安全鉴权Authorization由多个参数构成，每个参数均采用key=value的形式表示，并用&作为分隔符：

Authorization:accessID=wn8hxu48ugaw5t8dass9&action=AddProduct&et=1537255523123&method=sha1&version=1.0.0&sign=S04GcvafYIjtAMHJthkGPevbNwE%3D

token 计算

token由多个参数构成，如下表：

名称 类型 必传 说明 示例
accessID String 是 项目AccessID wn8hxu48ugaw5t8dass9
accessSecret String 是 项目AccessSecret c4b60cd69e2661e302459f00485fc4be
method String 是 加密方法md5/sha1/sha256 sha1
et int 是 过期时间，时间戳毫秒，最多不超过2小时TimeZone("Asia/Shanghai") 1537255523123
action String 是 接口名称 AddProduct
version String 是 API版本号 1.0.0
sign String 是 计算签名 ZjA1NzZlMmMxYzIOTg3MjBzNjYTI2MjA4Yw=

sign签名算法

参数sign的生成算法为： sign = base64(hmac_<method>(base64decode(accessSecret),utf-8(StringForSignature)))

  • accessSecret为系统项目资源分配的唯一访问密钥，其作为签名算法参数之一参与签名计算，为保证访问安全，请妥善保管。
  • accessSecret参与计算前应先进行base64decode操作
  • 用于计算签名的字符串StringForSignature的组成顺序按照参数名称ASCII进行字符串排序，以'\n' 作为参数分隔，当前版本中按照如下顺序进行排序：accessID、action、et、method、version StringForSignature示例： StringForSignature = accessID + '\n' + action + '\n' + et + '\n' + method + '\n' + version

# 设备管理类

# 设备详情

接口名称: DeviceDetail

请求方法: GET

请求参数:

参数名称 类型 必填 备注
product_id String 是 产品id
device_name String 是 设备名称

请求示例:

GET /device?action=DeviceDetail&product_id=YP0B76&device_name=6359745

响应示例:

{
  "status": "success",
  "requestId": "8906582E6722409AA6C40E7863B733A5",
  "data": {
    "device_name": "202152458412",
    "product_id": "YP0B76",
    "product_name": "水表",
    "active_at": "2022-09-29 15:02:49",
    "created_at": "2022-09-29 15:02:49",
    "last_online_at": "2022-09-29 15:02:49",
    "desc": "智能水表",
    "status": "2",
    "node_type": "1",
    "protocol": "MQTT",
    "imei": "366322456556584",
    "sec_key": "aWFvU1RYeVJ1aHRkeGdCMWVlTStyVWhMYTNTMncxOTM="
  }
}

响应数据:

参数名称 类型 描述
status String 接口调用状态
requestId String 调用API时生成的请求标识
data Object 调用成功返回业务数据
data.device_name String 设备名称
data.product_id String 产品id
data.product_name String 产品名称
data.active_at String 激活时间
data.created_at String 创建时间
data.last_online_at String 最后上线时间
data.desc String 备注信息
data.status String 设备状态 0未激活，1在线，2离线
data.node_type String 节点类型 1网关，2直连设备，3子设备
data.protocol String 接入协议
data.imei String 设备IMEI（设备ID，系统分配设备唯一标识）
data.sec_key String 设备密钥

# 设备属性设置

接口名称: SetDeviceProperty

请求方法: POST

请求示例:

POST /device?action=SetDeviceProperty
Content-type: application/json

{
  "product_id": "Y6T9KG",
  "device_name": "2022010411",
  "params": {
    "switch": 1,
    "value": 39.5,
    "event": {
      "click": 1
    }
  }
}

请求参数:

参数名称 类型 必填 备注
product_id String 是 产品id
device_name String 是 设备名称
params Object 是 设置的属性值，数据格式为json对象，形式为key:value，key为属性功能点标识，value为属性值，取值符合物模型定义的数据类型和取值范围，例如{"switch": 1}

响应示例:

{
  "status": "success",
  "requestId": "8906582E6722409AA6C40E7863B733A5",
  "data": {
    "id": "155",
    "code": 200,
    "msg": "OK"
  }
}

响应数据:

参数名称 类型 描述
status String 接口调用状态
requestId String 调用API时生成的请求标识
data Object 调用成功返回业务数据

# 设备属性获取

接口名称: DevicePropertyDetail

请求方法: POST

请求示例:

POST /device?action=DevicePropertyDetail
Content-type: application/json

{
  "product_id": "Y6T9KG",
  "device_name": "2022010411",
  "params": [
    "switch",
    "value"
  ]
}

请求参数:

参数名称 类型 必填 备注
product_id String 是 产品id
device_name String 是 设备名称
params Array 是 属性数据数组：["switch", "value"]

响应示例:

{
  "status": "success",
  "requestId": "8906582E6722409AA6C40E7863B733A5",
  "data": {
    "switch": 1,
    "value": 0.68
  }
}

响应数据:

参数名称 类型 描述
status String 接口调用状态
requestId String 调用API时生成的请求标识
data Object 调用成功返回业务数据

# 设备属性历史查询

接口名称: DevicePropertyHistory

请求方法: GET

请求示例:

GET /device?action=DevicePropertyHistory&product_id=YP0B76&device_name=6359745&property=number&sort=1&offset=40&limit=20

请求参数:

参数名称 类型 必填 备注
product_id String 是 产品id
device_name String 是 设备名称
property String 是 属性功能标识
start_at Integer 否 查询起始时间，毫秒时间戳，与查询结束时间成对出现，最长不超过7天
end_at Integer 否 查询结束时间，毫秒时间戳，与查询开始时间成对出现，最长不超过7天
sort Integer 否 排序 1正序，2倒序，系统只按时间节点排序，默认1
offset Integer 否 请求起始位置，默认0
limit Integer 否 查询记录数，默认10，范围支持[1，100]

响应示例:

{
  "status": "success",
  "requestId": "8906582E6722409AA6C40E7863B733A5",
  "data": {
    "items": [
      {
        "value": 0.58,
        "_at": 1592810751988
      },
      {
        "value": 0.73,
        "_at": 1592810746988
      }
    ],
    "meta": {
      "total": 569,
      "offset": 40,
      "limit": 20
    }
  }
}

响应数据:

参数名称 类型 描述
status String 接口调用状态
requestId String 调用API时生成的请求标识
data Object 调用成功返回业务数据
data.items Array 设备属性历史数据集合
items.value - 设备属性值
items._at Integer 设备上报属性值对应毫秒时间戳
data.meta Object 分页信息
meta.total Integer 查询结果总数
meta.offset Integer 查询起始位置
meta.limit Integer 返回查询记录数

# 设备事件历史查询

接口名称: DeviceEventHistory

请求方法: GET

请求示例:

GET /device?action=DeviceEventHistory&product_id=YP0B76&device_name=6359745&sort=1&offset=40&limit=20

请求参数:

参数名称 类型 必填 备注
product_id String 是 产品id
device_name String 是 设备名称
identifier String 否 属性功能标识
event_type Integer 否 事件类型1-信息 2-告警 3-故障
start_at Integer 否 查询起始时间，毫秒时间戳，与查询结束时间成对出现，最长不超过7天
end_at Integer 否 查询结束时间，毫秒时间戳，与查询开始时间成对出现，最长不超过7天
sort Integer 否 排序 1正序，2倒序，系统只按时间节点排序，默认1
offset Integer 否 请求起始位置，默认0
limit Integer 否 查询记录数，默认10，范围支持[1，100]

响应示例:

{
  "status": "success",
  "requestId": "8906582E6722409AA6C40E7863B733A5",
  "data": {
    "items": [
      {
        "name": "操作故障",
        "identifier": "valve",
        "type": 3,
        //开阀故障
        "value": "{\"status\":1}",
        "_at": 1592810751988
      },
      {
        "name": "操作故障",
        "identifier": "valve",
        "type": 3,
        //关阀故障
        "value": "{\"status\":3}",
        "_at": 1592810747852
      }
    ],
    "meta": {
      "total": 569,
      "offset": 40,
      "limit": 20
    }
  }
}

响应数据:

参数名称 类型 描述
status String 接口调用状态
requestId String 调用API时生成的请求标识
data Object 调用成功返回业务数据
data.items Array 设备属性历史数据集合
items.name String 事件功能点名称
items.identifier String 事件功能点标识
items.type Integer 事件功能点类型1-信息 2-告警 3-故障
items.value Object 事件上报数据
items._at Integer 设备上报属性值对应毫秒时间戳
data.meta Object 分页信息
meta.total Integer 查询结果总数
meta.offset Integer 查询起始位置
meta.limit Integer 返回查询记录数

# 获取网关子设备

接口名称: GetSubDevice

请求方法: GET

请求示例:

GET /device?action=GetSubDevice&product_id=YP0B76&device_name=6359745

请求参数:

参数名称 类型 必填 备注
product_id String 是 产品id
device_name String 是 设备名称

响应示例:

{
  "status": "success",
  "requestId": "8906582E6722409AA6C40E7863B733A5",
  "data": {
    "items": [
      {
        "device_name": "设备名称",
        "product_id": "产品id",
        "product_name": "产品名称",
        "active_at": "最近活跃时间",
        "created_at": "创建时间",
        "last_online_at": "最近登录时间",
        "desc": "描述",
        "status": "状态",
        "node_type": "设备类型",
        "protocol": "设备协议",
        "imei": "平台设备ID",
        "sec_key": "设备秘钥"
      }
    ]
  }
}

响应数据:

参数名称 类型 描述
status String 接口调用状态
requestId String 调用API时生成的请求标识
data Object 调用成功返回业务数据
data.items Array 设备属性历史数据集合
items.device_name String 子设备名称
items.product_id String 子设备产品ID
items.product_name String 子设备产品名称
items.active_at String 最近活跃时间
items.created_at String 子设备创建时间
items.last_online_at String 子设备最后上线时间
items.desc String 子设备描述
items.status String 子设备状态
items.node_type String 子设备类型
items.protocol String 子设备协议
items.imei String 子设备平台ID
items.sec_key String 子设备秘钥

# 触发设备服务

接口名称: DeviceServiceInvoke

请求方法: POST

请求示例:

POST /device?action=DeviceServiceInvoke
Content-type: application/json

请求参数:

{
  "product_id": "Y6T9KG",
  "device_name": "2022010411",
  "identifier": "openDoor",
  "params": {
    "key": "52623365"
  }
}
参数名称 类型 必填 备注
product_id String 是 产品id
device_name String 是 设备名称
identifier String 是 服务标识符
params Object 否 服务调用参数;无调用参数数时可为空

响应示例:

{
  "status": "success",
  "requestId": "8906582E6722409AA6C40E7863B733A5",
  "data": {
    "msg": "ok"
  }
}

响应数据:

参数名称 类型 描述
status String 接口调用状态
requestId String 调用API时生成的请求标识
data Object 调用成功返回业务数据

# 场景类

# 创建场景

← 物模型协议 →