文档

# API 列表

# 1. 设备管理

# 1.1 设置设备属性

  • 使用说明：

设置设备属性值。

  • 接口地址：
POST /openapi/v1/things/{device_id}/properties
  • 请求参数：

字段名

类型

位置

是否必填

说明

device_id

string

path

true

设备 id

  • 请求体：

字段名

类型

说明

params

object

设备属性值（具体属性可以查询设备所属产品的物模型）

  • 返回参数：

字段名

类型

说明

message_id

string

当前设备消息唯一 id，用于调试

  • 请求示例：
POST /openapi/v1/things/7e90e6fdf4a543dUeAPS/properties
{
    "params": {
        "property1": 1,
        "property2": "hello"
    }
}
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": {
        "message_id": "1"
    }
}

# 1.2 调用设备服务

  • 使用说明：

调用设备的指定服务。设备的服务定义于设备所属产品的物模型中，调用该接口时，会根据 service_id 值，选择服务对应的调用方式。(目前只支持异步调用)

  • 接口地址：
POST /openapi/v1/things/{device_id}/services/{service_id}
  • 请求参数：

字段名

类型

位置

是否必填

说明

device_id

string

path

true

设备唯一 id

service_id

string

path

true

设备服务 id

  • 请求体：

字段名

类型

说明

params

object

设备服务参数列表（具体属性可以查询设备所属产品的物模型）

  • 返回参数：

字段名

类型

说明

message_id

string

当前设备消息唯一 id，用于调试

  • 请求示例：
POST /openapi/v1/things/7e90e6fdf4a543dUeAPS/services/timer
{
    "params": {
        "param1": 1,
        "param2": "hello"
    }
}
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": {
        "message_id": "1"
    }
}

# 1.3 查询设备详情

# 1.3.1 通过 device_id 查询

  • 接口地址：
GET /openapi/v1/things/{device_id}/detail
  • 返回参数：

字段名

类型

说明

device_info

json

设备详情

device_name

string

设备名（设备三元组之一）

product_key

string

产品唯一标识（设备三元组之一）

device_secret

string

设备密钥（设备三元组之一）

product_secret

string

产品密钥

device_id

string

设备唯一标识

node_type

string

节点类型：direct（直连设备），gateway（网关设备），gateway-sub（网关子设备）

protocol_type

string

协议类型：zigbee，ble

validate_type

string

设备数据校验类型：none（无校验），weak（弱校验）

data_format

string

设备数据格式：json，raw（hex 格式）

product_name

string

产品名称

nickname

string

设备昵称

register_at

date

设备注册日期

updated_at

date

设备最近更新日期

batch_id

int

设备批次号，为 0 则不是批次设备

ip

string

设备 ip 地址

status

string

在线状态：online（在线），offline（离线）

enabled_status

string

可用状态：disable, enable

firmware_version

string

默认模块固件版本号

time_zone

string

设备所在时区

platform

int

当设备属于云平台设备时生效：

0/1： fogcloud 本地设备,

2： 阿里云 iot 平台设备

3：涂鸦 iot 平台设备

4：aws-iot 平台设备

platform_name

string

设备所属 iot 平台名称

data_source

int

0/1：fogcloud 本地设备

2：云云对接设备

3：云网关设备

  • 请求示例：
GET /openapi/v1/things/xxx/detail
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "device_info": {
            "device_secret": "985059b9fa3281ecadc370944c847e1d",
            "device_name": "000001f9",
            "product_key": "9df223b0",
            "device_id": "4523eb29816746b7EG6B",
            "nickname": "",
            "register_at": null,
            "updated_at": null,
            "created_at": "2023-02-16T10:19:43.406764+08:00",
            "ip": "",
            "batch_id": 95,
            "status": "unactive",
            "enabled_status": "enable",
            "firmware_version": "0.0.1",
            "time_zone": "",
            "platform_name": "",
            "access_key": "xgHc40bf04fb020c",
            "product_secret": "fc57ca619c00f063aa90358b3766ce72",
            "product_name": "mesh-gtw",
            "node_type": "gateway",
            "protocol_type": "ble-mesh",
            "validate_type": "none",
            "data_format": "json",
            "auth_type": "",
            "data_source": 1,
            "platform": 1,
            "platform_name": "FogCloud"
        }
    }
}

# 1.3.2 通过 device_name 和 product_key 查询

  • 接口地址：
GET /openapi/v1/products/{product_key}/device-names/{device_name}/detail
  • 请求示例：
GET /openapi/v1/products/xxx/device-names/xxx/detail

# 1.4 查询设备在线状态

  • 使用说明：

查询设备在线状态。

  • 接口地址：
GET /openapi/v1/things/{device_id}/status
  • 请求参数：

字段名

类型

位置

是否必填

说明

device_id

string

path

true

设备唯一 id

  • 返回参数：

字段名

类型

说明

status

string

online，offline

  • 请求示例：
GET /openapi/v1/things/b951e7fd4221460xK2Ni/status
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": {
      "status": "online"
    }
}

# 1.5 修改设备状态

  • 使用说明：

修改设备状态。

  • 接口地址：
PUT /openapi/v1/things/{device_id}/status
  • 请求参数：

字段名

类型

位置

是否必填

说明

device_id

string

path

true

设备唯一 id

  • 请求体：

字段名

类型

说明

action

string

enable（启用）

disble（禁用）

unbind （解绑）

bind (绑定)

  • 请求示例：
PUT /openapi/v1/things/b951e7fd4221460xK2Ni/status
{
    "action": "enable"
}
  • 返回示例：
{
    "code": 0,
    "message": "success"
}

# 1.6 验证蓝牙设备身份

  • 使用说明：

用于设备蓝牙辅助配网时设备身份校验。

  • 接口地址：
POST /openapi/v1/auth/ble/products/{product_key}/identity
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

  • 请求体：

字段名

类型

说明

device_name

string

设备名称

random

string

配网时用户身份标识

cipher

string

密钥，用于校验身份

  • 返回参数：

字段名

类型

说明

ble_key

string

用于设备、app 数据交互

  • 请求示例：
{
    "device_name": "xxx",
    "random": "xxx",
    "cipher": "xxx"
}
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": {
        "ble_key": "xxx"
    }
}

# 1.7 设备拓扑关系管理

# 1.7.1 修改网关设备拓扑动作

  • 使用说明：

用于管理网关设备与子设备的拓扑关系。网关设备收到消息后会进入对应状态。

  • 接口地址：
PUT /openapi/v1/things/{device_id}/topo
  • 请求参数：

字段名

类型

位置

是否必填

说明

device_id

string

path

true

网关设备 id，设备唯一标识

  • 请求体：

字段名

类型

说明

action

string

sub.add.start（开始子设备添加）

sub.add.stop（停止子设备添加）

session_id

string

当动作为 sub.add.stop 时必填

params

object

参数

timeout

int

网关添加子设备超时时间，单位秒; 不传则默认为 60；

product_keys

array

网关添加的子设备类型，即子设备的 product_key

  • 返回参数：

字段名

类型

说明

session_id

string

该次配网请求唯一标识

  • 请求示例：
PUT /openapi/v1/things/5a7060a3822d4b6Yc25j/topo
{
  "action": "sub.add.start",
  "params": {
    "timeout": 10, //网关添加子设备超时时间，单位秒; 不传则默认为60；
    "product_keys": ["xxx", "xxx"]
  }
}
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": {
        "session_id": "xxxx"
    }
}
  • 请求示例：
PUT /openapi/v1/things/5a7060a3822d4b6Yc25j/topo
{
  "action": "sub.add.stop",
  "session_id": "xxx"
}
  • 返回示例：
{
    "code": 0,
    "message": "success"
}

# 1.7.2 删除网关子设备

  • 使用说明：

用于删除网关与子设备的拓扑关系

  • 接口地址：
DELETE /openapi/v1/things/{device_id}/topo/sub-devices
  • 请求体：

字段名

类型

说明

params

list

子设备列表

device_name

string

设备名称

product_key

string

产品唯一标识

  • 请求示例：
DELETE /openapi/v1/things/5a7060a3822d4b6Yc25j/topo/sub-devices
{
  "params": [
    {
      "device_name": "xxx",
      "product_key": "xxx"
    },
    {
      "device_name": "xxx",
      "product_key": "xxx"
    }
  ]
}
  • 返回示例：
{
    "code": 0,
    "message": "success"
}

# 1.7.3 查询网关子设备

  • 使用说明：

用于获取网关设备下的子设备信息

  • 接口地址：
GET /openapi/v1/things/{device_id}/topo/sub-devices
  • 请求参数：

字段名

类型

位置

是否必填

说明

device_id

string

path

true

网关设备 id，设备唯一标识

session_id

string

query

true

配网动作唯一标识

  • 返回参数：

字段名

类型

说明

device_id

string

子设备 id，设备唯一标识

device_name

string

子设备三元组设备名

product_key

string

子设备三元组产品名

  • 请求示例：
GET /openapi/v1/things/xxx/topo/sub-devices?session_id=xxx
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": {
      "sub_devices": [
        {
          "device_id": "xxx",
          "device_name": "xxx",
          "product_key": "xxx"
        },
        {
          "device_id": "xxx",
          "device_name": "xxx",
          "product_key": "xxx"
        }
      ]
    }
}

# 1.7.4 添加网关子设备

  • 使用说明：

用于添加网关设备子设备

  • 接口地址：
POST /openapi/v1/things/{device_id}/topo/sub-devices
  • 请求参数：

字段名

类型

位置

是否必填

说明

device_id

string

path

true

网关设备 id，设备唯一标识

session_id

string

query

true

配网动作唯一标识

  • 请求体：

字段名

类型

说明

params

list

子设备列表

device_name

string

设备名称

product_key

string

产品唯一标识

sign_method

string

签名方法：hmacmd5, hmacsha1

sign

string

签名

  • 返回参数：

字段名

类型

说明

device_id

string

子设备 id，设备唯一标识

device_name

string

子设备三元组设备名

product_key

string

子设备三元组产品名

  • 请求示例：
POST /openapi/v1/things/xxx/topo/sub-devices
{
    "params": [
        {
            "device_name": "00000001",
            "product_key": "6f2f5483",
            "sign": "96c461b68726be516dda7775c19ebdd47a61b229"
        },
        {
            "device_name": "00000002",
            "product_key": "6f2f5483",
            "sign": "3d35aeed19a7b0e4675c254dae68f7a9d42cb401"
        },
        {
            "device_name": "00000003",
            "product_key": "6f2f5483",
            "sign": "ce2fbbc78cc65d9f16ba6ccf96b7b790be993154"
        }
    ]
}
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": [
        {
            "device_name": "00000001",
            "product_key": "6f2f5483",
            "device_id": "xxxx"
        },
        {
            "device_name": "00000002",
            "product_key": "6f2f5483",
            "device_id": "xxxx"
        },
        {
            "device_name": "00000003",
            "product_key": "6f2f5483",
            "device_id": "xxxx"
        }
    ]
}

# 1.8 查询设备物模型属性

  • 使用说明：

查询设备最新属性。

  • 接口地址：
GET /openapi/v1/things/{device_id}/properties
  • 请求参数：

字段名

类型

位置

是否必填

说明

device_id

string

path

true

设备 id

  • 返回参数：

字段名

类型

说明

properties

object

属性值

  • 请求示例：
GET /openapi/v1/things/xxx/properties
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": {
      "properties": {
        "prop1": 1,
        "prop2": 2,
        "prop3": 3
      }
    }
}

# 1.9 创建设备

  • 接口地址：
POST /openapi/v1/products/{product_key}/things
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

  • 请求体：

字段名

类型

说明

nickname

string

设备昵称，可以为空

clientid

string

云网关设备 MQTT clientid，仅添加云网关产品设备时生效，不能为空；

username

string

云网关设备 MQTT username，仅添加云网关产品设备时生效，不能为空

password

string

云网关设备 MQTT password，仅添加云网关产品设备时生效，可以为空

cloud_gtw_device_uuid

string

云网关设备自定义唯一标识，仅添加云网关产品设备时生效，可以为空

  • 返回参数：

字段名

类型

说明

device_id

string

设备唯一标识

product_key

string

产品唯一标识

device_name

string

设备三元组之一

device_secret

string

设备三元组之一

status

string

设备状态

created_at

string

创建时间

register_at

string

激活时间

updated_at

string

更新时间

batch_id

int

设备批次（为 0 则无批次）

enabled_status

string

设备可用状态：

enable，disable

ip

string

设备 ip 地址

firmware_version

string

设备默认模块固件版本

  • 请求示例：
POST /openapi/v1/products/5949184b/things
{
  "nickname": "device1"
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "device_id": "4ffab68c9486460w6rsP",
        "product_key": "db2724a2",
        "device_name": "00000000",
        "device_secret": "5afeb8575cb142ca26557db6506eaa15",
        "nickname": "",
        "status": "unactive",
        "created_at": "2022-07-14T10:35:36+08:00",
        "register_at": "",
        "updated_at": "",
        "batch_id": 0,
        "firmware_version": "",
        "ip": "",
        "enabled_status": "enable"
    }
}

# 1.10 删除设备

  • 接口地址：
DELETE /openapi/v1/things/{device_id}
  • 请求参数：

字段名

类型

位置

是否必填

说明

device_id

string

path

true

设备唯一 id

  • 请求示例：
DELETE /openapi/v1/things/b951e7fd4221460xK2Ni
  • 返回示例：
{
    "code": 0,
    "message": "success"
}

# 1.11 创建批次设备

  • 接口地址：
POST /openapi/v1/products/{product_key}/batch-things
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

  • 请求体：

字段名

类型

说明

num

int

批次设备数量；最大值为 10000；

desc

string

批次描述

  • 返回参数：

字段名

类型

说明

batch_id

int

批次 id

  • 请求示例：
POST /openapi/v1/products/db2724a2/batch-things
{
    "num": 10000,
    "desc": "第一批次"
}
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": {
      "batch_id": 10 
    }
}

# 1.12 删除批次设备

  • 接口地址：
DELETE /openapi/v1/products/{product_key}/batch-things/{batch_id}
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

batch_id

int

path

true

批次唯一标识

  • 请求示例：
DELETE /openapi/v1/products/db2724a2/batch-things/10
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": {
      "batch_id": 10 
    }
}

# 1.13 查询设备绑定信息

  • 使用说明：

用于直连设备配网时，云端判断设备是否成功绑定用户。random 为云端生成的随机数，设备成功入网后会上报该随机数。

  • 接口地址：
GET /openapi/v1/products/{product_key}/device-names/{device_name}/bind
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

device_name

string

path

true

设备三元组之一

  • 返回参数：

字段名

类型

说明

random

string

用于设备

  • 请求示例：
GET /openapi/v1/products/dda4145a/device-names/00000001/bind
  • 返回示例：
{
    "code": 0,
    "message": "success",
    "data": {
        "random": "xxx"
    }
}

# 1.14 查询设备列表

  • 使用说明：

查看设备列表。

  • 接口地址：
GET /openapi/v1/things
  • 请求参数：

字段名

类型

位置

是否必填

说明

page

int

query

false

当前页数。（不传则默认为 1）

page_size

int

query

false

每页数据量。（不传则默认为 10）

product_key

string

query

false

产品唯一标识，用于查询某一产品下的设备列表

batch_id

int

query

false

设备批次 id，用于查询某一批次的设备列表

enabled_status

string

query

false

可选值：disable,enable，用于按可用状态筛选设备

status

string

query

false

可选值：online,offline，用于按在离线状态筛选设备

  • 返回参数：

字段名

类型

说明

results

list

列表数据

total

int

数据总数

page

int

当前页数

page_size

int

当前页大小

pages

int

总页数

  • results 参数：

字段名

类型

说明

device_id

string

设备唯一标识

product_key

string

产品唯一标识

device_name

string

设备三元组之一

device_secret

string

设备三元组之一

product_secret

string

产品密钥

status

string

设备状态

created_at

string

创建时间（rfc3339 标准格式）

register_at

string

激活时间

updated_at

string

更新时间

batch_id

int

设备批次（为 0 则无批次）

enabled_status

string

设备可用状态：

enable，disable

ip

string

设备 ip 地址

firmware_version

string

设备默认模块固件版本

diagnosis_enabled

bool

是否开启设备远程诊断

data_source

int

0/1：fogcloud 本地设备

2：云云对接设备

3：云网关设备

time_zone

string

设备时区

node_type

string

节点类型

auth_type

string

认证方式

data_format

string

数据格式

protocol_type

string

协议类型

  • 请求示例：
GET /openapi/v1/things
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "page": 1,
        "page_size": 2,
        "pages": 0,
        "results": [
            {
                "device_id": "27c1cf54ba27490fsQrG",
                "product_key": "5930b342",
                "device_name": "00000000",
                "device_secret": "xxxx",
                "nickname": "",
                "status": "unactive",
                "created_at": "2023-02-28T14:44:30+08:00",
                "register_at": "",
                "updated_at": "",
                "batch_id": 0,
                "firmware_version": "",
                "ip": "",
                "enabled_status": "enable",
                "diagnosis_enabled": false,
                "data_source": 1,
                "cloud_gtw_mqtt_param": null,
                "cloud_gtw_device_uuid": "",
                "time_zone": "",
                "product_secret": "xxx",
                "product_name": "sub-json-test",
                "device_type": "",
                "node_type": "gateway-sub",
                "auth_type": "secret",
                "data_format": "json",
                "protocol_type": "zigbee",
                "topics": null,
                "product_id": 416,
                "sub_amount": 0,
                "is_mocker": false,
                "platform_name": "",
                "platform": 0,
                "iot_platform": 0
            },
            {
                "device_id": "4f8e44e3b061428uSd3E",
                "product_key": "cae7e7b8",
                "device_name": "00000000",
                "device_secret": "xxxx",
                "nickname": "",
                "status": "unactive",
                "created_at": "2023-02-24T16:00:49+08:00",
                "register_at": "",
                "updated_at": "",
                "batch_id": 0,
                "firmware_version": "",
                "ip": "",
                "enabled_status": "enable",
                "diagnosis_enabled": false,
                "data_source": 1,
                "cloud_gtw_mqtt_param": null,
                "cloud_gtw_device_uuid": "",
                "time_zone": "",
                "product_secret": "xxx",
                "product_name": "ffcp",
                "device_type": "",
                "node_type": "gateway-sub",
                "auth_type": "secret",
                "data_format": "json",
                "protocol_type": "zigbee",
                "topics": null,
                "product_id": 418,
                "sub_amount": 0,
                "is_mocker": false,
                "platform_name": "",
                "platform": 0,
                "iot_platform": 0
            }
        ],
        "total": 742
    }
}

# 2. 产品相关

# 2.1 查询单个产品详情

  • 接口地址：
GET /openapi/v1/products/{product_key}
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

  • 返回参数：

字段名

类型

说明

product_info

object

产品详情

product_key

string

产品唯一标识

product_secret

string

产品密钥

name

string

产品名称

device_type

string

设备品类

network_type

string

网络类型：wifi，ethernet，cellular，lorawan，others

node_type

string

节点类型：

direct（直连设备），

gateway（网关设备），

gateway-sub（网关子设备）

protocol_type

string

协议类型：zigbee，ble

validate_type

string

设备数据校验类型：

none（无校验），

weak（弱校验）

data_format

string

设备数据格式：

json，raw（hex 格式）

register_at

date

设备注册日期

updated_at

date

产品最近更新日期

created_at

date

产品创建日期

dynamic_register

bool

动态注册开关

status

string

状态：

developing（开发中），

released（已发布）

platform

int

当设备属于云平台设备时生效：

0/1： fogcloud 本地设备,

2： 阿里云 iot 平台设备

3：涂鸦 iot 平台设备

4：aws-iot 平台设备

platform_name

string

设备所属 iot 平台名称

data_source

int

0/1：fogcloud 本地设备

2：云云对接设备

3：云网关设备

  • 请求示例：
GET /openapi/v1/products/6f2f5483
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "product_info": {
            "product_key": "6f2f5483",
            "product_secret": "xxxx",
            "project_id": 0,
            "name": "sub-json-test",
            "device_type": "light",
            "network_type": "",
            "protocol_type": "zigbee",
            "description": "",
            "photo_url": "http://192.168.2.111:4000/api/v1/oss/buckets/fogcloud-config?filename=XuyAq1635839607.png",
            "configuration": "",
            "created_at": "2021-11-02T15:53:32.909771+08:00",
            "updated_at": "2021-11-02T15:53:32.909772+08:00",
            "node_type": "gateway-sub",
            "data_format": "json",
            "auth_type": "secret",
            "status": "developing",
            "dynamic_register": false,
            "data_source": 1,
            "platform": 1,
            "platform_name": "FogCloud"
        }
    }
}

# 2.2 查询产品列表

  • 使用说明：

获取当前项目下产品列表，数据分页返回

  • 接口地址：
GET /openapi/v1/products
  • 请求参数：

字段名

类型

位置

是否必填

说明

page

int

query

false

当前页数。（不传则默认为 1）

page_size

int

query

false

每页数据量。（不传则默认为 10）

  • 返回参数：

字段名

类型

说明

results

list

列表数据

total

int

数据总数

page

int

当前页数

page_size

int

当前页大小

pages

int

总页数

  • 请求示例：
GET /openapi/v1/products?page=1&page_size=2
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "page": 1,
        "page_size": 2,
        "pages": 0,
        "results": [
            {
                "product_key": "1ea2536e",
                "product_secret": "4abb17934225668d617b07d5f3273ee9",
                "project_id": 0,
                "name": "a",
                "device_type": "",
                "network_type": "wifi",
                "protocol_type": "",
                "description": "",
                "photo_url": "http://192.168.2.111:4000/api/v1/oss/buckets/fogcloud-config?filename=v9ZsM1636598368.png",
                "configuration": "",
                "created_at": "2021-11-11T10:39:30.439694+08:00",
                "updated_at": "2021-11-11T10:39:30.439694+08:00",
                "node_type": "direct",
                "data_format": "json",
                "auth_type": "secret",
                "status": "developing",
                "dynamic_register": false,
                "data_source": 1,
                "platform": 1,
                "platform_name": "FogCloud"              
            },
            {
                "product_key": "42a26cb7",
                "product_secret": "edb676e49cc55737429f2b03a2afe4aa",
                "project_id": 0,
                "name": "SK_TEST_VIP",
                "device_type": "",
                "network_type": "wifi",
                "protocol_type": "",
                "description": "",
                "photo_url": "http://192.168.2.111:4000/api/v1/oss/buckets/fogcloud-config?filename=ZuAbs1636532596.png",
                "configuration": "",
                "created_at": "2021-11-10T16:23:17.926998+08:00",
                "updated_at": "2021-11-11T10:39:14.243438+08:00",
                "node_type": "direct",
                "data_format": "json",
                "auth_type": "secret",
                "status": "developing",
                "dynamic_register": false,
                "data_source": 1,
                "platform": 1,
                "platform_name": "FogCloud"              
            }
        ],
        "total": 10
    }
}

# 2.3 创建产品

  • 使用说明：

创建产品

  • 接口地址：
POST /openapi/v1/products
  • 请求体：

字段名

类型

是否必填

说明

name

string

true

产品名称

network_type

string

false

网络类型：wifi，ethernet，cellular，lorawan，wifi+ble-mesh

（注：节点类型为直连设备时必填）

node_type

string

true

节点类型：

direct（直连设备），

gateway（网关设备），

gateway-sub（网关子设备）

protocol_type

string

false

协议类型：zigbee，ble，ble-mesh

（注：节点类型为网关子设备时必填）

validate_type

string

true

设备数据校验类型：

none（无校验），

weak（弱校验），

data_format

string

true

设备数据格式：

json，raw（hex 格式）

dynamic_register

bool

false

动态注册开关

auth_type

string

true

认证类型：

secret（三元组认证）

photo_url

string

false

产品图片 url

description

string

false

产品描述

  • 返回参数：

字段名

类型

说明

product_info

object

产品详情

product_key

string

产品唯一标识

product_secret

string

产品密钥

name

string

产品名称

device_type

string

设备品类

network_type

string

网络类型：

wifi，ethernet，cellular，lorawan，others

（注：当节点类型为网关子设备时为空）

node_type

string

节点类型：

direct（直连设备），

gateway（网关设备），

gateway-sub（网关子设备）

protocol_type

string

协议类型：zigbee，ble

（注：当网关节点类型为直连或者网关设备时为空）

validate_type

string

设备数据校验类型：

none（无校验），

weak（弱校验）

data_format

string

设备数据格式：

json，raw（hex 格式）

register_at

date

设备注册日期

updated_at

date

产品最近更新日期

created_at

date

产品创建日期

dynamic_register

bool

动态注册开关

status

string

状态：

developing（开发中），

released（已发布）

  • 请求示例：
POST /openapi/v1/products
{
  "product_key": "6f2f5483",
  "product_secret": "xxxx",
  "name": "sub-json-test",
  "device_type": "light",
  "network_type": "",
  "protocol_type": "zigbee",
  "description": "",
  "photo_url": "http://192.168.2.111:4000/api/v1/oss/buckets/fogcloud-config?filename=XuyAq1635839607.png",
  "node_type": "gateway-sub",
  "data_format": "json",
  "auth_type": "secret",
  "dynamic_register": false
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "product_info": {
            "product_key": "6f2f5483",
            "product_secret": "xxxx",
            "name": "sub-json-test",
            "device_type": "light",
            "network_type": "",
            "protocol_type": "zigbee",
            "description": "",
            "photo_url": "http://192.168.2.111:4000/api/v1/oss/buckets/fogcloud-config?filename=XuyAq1635839607.png",
            "configuration": "",
            "created_at": "2021-11-02T15:53:32.909771+08:00",
            "updated_at": "2021-11-02T15:53:32.909772+08:00",
            "node_type": "gateway-sub",
            "data_format": "json",
            "auth_type": "secret",
            "status": "developing",
            "dynamic_register": false
        }
    }
}

# 2.4 删除产品

  • 接口地址：
DELETE /openapi/v1/products/{product_key}
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

  • 请求示例：
DELETE /openapi/v1/products/b951e7fd
  • 返回示例：
{
    "code": 0,
    "message": "success"
}

# 2.5 修改产品

  • 接口地址：
PUT /openapi/v1/products/{product_key}
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

  • 请求体：

字段名

类型

是否必填

说明

name

string

true

产品名称

dynamic_register

bool

true

动态注册开关

photo_url

string

true

产品图片 url

description

string

false

产品描述

  • 请求示例：
PUT /openapi/v1/products/b951e7fd
{
  "name": "彩灯",
  "dynamic_register": true,
  "photo_url": "xxx.com/photos/xxx",
  "description": ""
}
  • 返回示例：
{
    "code": 0,
    "message": "success"
}

# 2.6 修改产品发布状态

  • 接口地址：
PUT /openapi/v1/products/{product_key}/status
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

  • 请求体：

字段名

类型

是否必填

说明

status

string

true

产品发布状态：

developing, released

  • 请求示例：
PUT /openapi/v1/products/b951e7fd/status
{
  "status": "released"
}
  • 返回示例：
{
    "code": 0,
    "message": "success"
}

# 3. 物模型

# 3.1 查询产品物模型

  • 接口地址：
GET /openapi/v1/products/{product_key}/thing-model
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

model_type

string

query

true

物模型数据格式：metadata，tsl

  • 返回参数：

完整物模型数据格式见 物模型文档 (opens new window)

字段名

类型

说明

thing_model

object

物模型详情

properties说明：

字段名

类型

说明

id

string

属性唯一标识

name

string

属性名称

required

bool

是否必填

funcType

string

元素类型：property, event, service

accessMode

string

读写类型：

r（只读）,

w（只写），

rw （读写）

dataType

object

数据格式

  • 请求示例：
GET /openapi/v1/products/6f2f5483/thing-model?model_type=metadata
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "thing_model": {
            "properties": [
                {
                    "id": "param1",
                    "name": "param1",
                    "required": false,
                    "standard": false,
                    "funcType": "property",
                    "accessMode": "rw",
                    "dataType": {
                        "type": "int",
                        "size": 10,
                        "length": 10240,
                        "elementType": "int"
                    }
                }
            ],
            "events": [
                {
                    "id": "post",
                    "name": "post",
                    "required": true,
                    "standard": false,
                    "funcType": "event",
                    "desc": "属性上报",
                    "method": "thing.event.property.post",
                    "eventType": "info",
                    "outputData": [
                        {
                            "id": "param1",
                            "name": "param1",
                            "dataType": {
                                "type": "int",
                                "size": 10,
                                "length": 10240,
                                "elementType": "int"
                            }
                        }
                    ]
                }
            ],
            "services": [
                {
                    "id": "set",
                    "name": "set",
                    "required": true,
                    "standard": false,
                    "funcType": "service",
                    "desc": "属性设置",
                    "method": "thing.service.property.set",
                    "eventType": "",
                    "outputData": [],
                    "callType": "async",
                    "inputData": [
                        {
                            "id": "param1",
                            "name": "param1",
                            "dataType": {
                                "type": "int",
                                "size": 10,
                                "length": 10240,
                                "elementType": "int"
                            }
                        }
                    ]
                }
            ]
        }
    }
}

# 3.2 增加物模型元素

  • 接口地址：
POST /openapi/v1/products/{product_key}/thing-model-element

  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

  • 请求体：

# 3.3 修改物模型元素

  • 接口地址：
PUT /openapi/v1/products/{product_key}/thing-model-element

# 3.4 删除物模型元素

  • 接口地址：
DELETE /openapi/v1/products/{product_key}/thing-model-element

# 3.5 导入物模型

  • 接口地址：
POST /openapi/v1/products/{product_key}/thing-model
  • 请求体：

字段名

类型

是否必填

说明

model_type

string

true

物模型语法格式：

metadata, tsl, sdf

model_data

string

true

物模型内容

# 3.6 导出物模型

  • 接口地址：
GET /openapi/v1/products/{product_key}/thing-model
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

model_type

string

query

true

物模型语法格式：

metadata, tsl, sdf

# 3.7 拷贝物模型

  • 接口地址：
PUT /openapi/v1/products/{product_key}/thing-model
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

source_product_key

string

query

true

被拷贝的产品唯一标识

# 3.8 删除物模型

  • 接口地址：
DELETE /openapi/v1/products/{product_key}/thing-model
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

# 4. 设备影子查询

# 4.1 查询设备影子

  • 接口说明：

设备影子包含设备最新的属性值、期望的属性值、在线状态，和属性更新时间戳。

  • 接口地址：
GET /openapi/v1/things/{device_id}/shadow
  • 返回参数： 设备影子数据格式见文档

  • 请求示例：
GET /openapi/v1/things/4b1da8c4faee4deP1Ljl/shadow
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "thing_shadow": {
            "state": {
                "desired": {
                    "brightness": 777,
                    "switch": 1
                },
                "reported": {}
            },
            "metadata": {
                "desired": {
                    "brightness": {
                        "timestamp": 1635478451
                    },
                    "switch": {
                        "timestamp": 1635478451
                    }
                },
                "reported": {}
            },
            "id": 0,
            "timestamp": 1635478451,
            "status": "offline"
        }
    }
}

# 4.2 更新设备影子期望值

  • 接口说明：

设置设备影子期望值，可用于设备离线时进行控制指令缓存，设备恢复网络连接后可以根据期望值进行属性更新。

  • 接口地址：
PUT /openapi/v1/things/{device_id}/shadow
  • 请求体：

字段名

类型

说明

state

json 对象

期望的设备属性数据

  • 请求示例：
PUT /openapi/v1/things/4b1da8c4faee4deP1Ljl/shadow
{
    "state": {
        "desired": {
            "switch": 1,
            "brightness": 666
        }
    }
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS"
}

# 5. 固件升级相关

固件状态和验证/升级任务状态枚举：

枚举值

说明

0

待验证

1

验证中

2

验证成功

3

验证失败

4

已取消

升级任务枚举：

枚举值

说明

0

待进行

1

任务进行中

2

任务已完成

3

任务已失败

4

任务已取消

设备升级状态枚举：

枚举值

说明

1

待升级

2

升级中

3

升级成功

4

升级失败

5

升级取消

# 5.1 检查设备更新

  • 接口地址：
GET /openapi/v1/things/{device_id}/upgrade
  • 请求参数

字段名

类型

位置

是否必填

说明

device_id

string

path

true

设备唯一 id

module

string

query

false

模块名称（不传则默认为 default）

  • 返回参数：

字段名

类型

说明

size

int32

固件大小，单位 byte

sign

string

固件 md5 签名

sign_method

string

摘要算法，固定为 md5

version

string

固件版本，采用"x.y.z"格式

url

string

固件下载 url

module

string

模块名称

task_id

int

当前固件升级任务唯一标识

description

string

固件描述

need_app_confirm

bool

是否需要 app 确认（4.13.0 新增）

is_app_confirmed

bool

app 是否已经确认（4.13.0 新增）

  • 请求示例：
GET /openapi/v1/things/60ff5696991b405bkmhn/upgrade?module=mcu1
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "size": 0,
        "sign": "90d5683b2887b65fc65b5a4b93248fd0",
        "sign_method": "MD5",
        "version": "1.0.1",
        "url": "http://example.com/api/v1/oss/buckets/fogcloud-firmware?filename=f4e7b826/1635748072ekh3Yt.zip",
        "module": "mcu1",
        "task_id": 15,
        "description": "xxxx",
        "need_app_confirm": true,
        "is_app_confirmed": false
    }
}

# 5.2 升级设备

  • 接口地址：
POST /openapi/v1/things/{device_id}/upgrade
  • 请求体

字段名

类型

说明

task_id

int

固件升级任务唯一标识

  • 请求示例：
POST /openapi/v1/things/60ff5696991b405bkmhn/upgrade
{
    "task_id": 1
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS"
}

# 5.3 查询设备升级进度

  • 接口地址：
GET /openapi/v1/things/{device_id}/upgrade-step
  • 请求参数

字段名

类型

位置

是否必填

说明

device_id

string

path

true

设备唯一 id

task_id

int

query

false

任务 id

  • 返回参数：

字段名

类型

说明

step

int32

升级进度。-1（升级失败），0~100（升级进度百分比）

  • 请求示例：
GET /openapi/v1/things/60ff5696991b405bkmhn/upgrade-step?task_id=1
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "step": 10
    }
}

# 5.4 查询设备固件版本号

  • 接口地址：
GET /openapi/v1/things/{device_id}/version
  • 请求参数

字段名

类型

位置

是否必填

说明

module

string

query

false

模块名称（默认为 default）

  • 返回参数：

字段名

类型

说明

version

string

版本号

  • 请求示例：
GET /openapi/v1/things/60ff5696991b405bkmhn/version?module=mcu
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "version": "1.2.1"
    }
}

# 5.5 查询固件详情

  • 接口地址：
GET /openapi/v1/ota/firmwares/{firmware_id}
  • 请求参数：

字段名

类型

位置

是否必填

说明

firmware_id

int

param

true

固件唯一 id

  • 返回参数：

字段名

类型

说明

id

int

固件唯一 id

name

string

固件名称

oss_path

string

固件下载地址

algorithms

int

摘要算法：1-md5

hash

string

摘要值

status

int

固件状态：

0-待验证

1-验证中

2-验证成功

3-验证失败

4-已取消

remark

string

备注

module

string

固件所属模块名称

created_at

date

创建日期

updated_at

date

更新日期

product_key

string

产品唯一标识

  • 请求示例：
GET /openapi/v1/ota/firmwares/1
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "id": 40,
        "name": "o6",
        "version": "1.2.7",
        "oss_path": "http://localhost:4000/api/v1/oss/buckets/fogcloud-firmware?filename=2259e91f/16523470485CWtlv.zip",
        "algorithms": 1,
        "hash": "3ec754fdd76d7ff260528d19cbe7f3a3",
        "status": 2,
        "remark": "for test",
        "module": "default",
        "created_at": "2022-05-12T17:17:31.508216+08:00",
        "updated_at": "2022-05-12T17:17:31.508217+08:00",
        "product_key": "2259e91f",
        "product_name": "wifi灯"
    }
}

# 5.6 查询固件列表

  • 接口地址：
GET /openapi/v1/ota/firmwares
  • 请求参数：

字段名

类型

位置

是否必填

说明

page

int

query

false

当前页数。（不传则默认为 1）

page_size

int

query

false

每页数据量。（不传则默认为 10）

product_key

string

query

false

固件所属产品唯一标识

name

string

query

false

固件名称

  • 请求示例：
GET /openapi/v1/ota/firmwares?name=o&page_size=2
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "page": 1,
        "page_size": 2,
        "pages": 0,
        "results": [
            {
                "id": 40,
                "name": "o6",
                "version": "1.2.7",
                "oss_path": "http://localhost:4000/api/v1/oss/buckets/fogcloud-firmware?filename=2259e91f/16523470485CWtlv.zip",
                "algorithms": 1,
                "hash": "3ec754fdd76d7ff260528d19cbe7f3a3",
                "status": 2,
                "remark": "tr",
                "module": "default",
                "created_at": "2022-05-12T17:17:31.508216+08:00",
                "updated_at": "2022-05-12T17:17:31.508217+08:00",
                "product_key": "2259e91f",
                "product_name": "wifi灯"
            },
            {
                "id": 39,
                "name": "o5",
                "version": "1.2.6",
                "oss_path": "http://localhost:4000/api/v1/oss/buckets/fogcloud-firmware?filename=2259e91f/1652336768dcQdFo.zip",
                "algorithms": 1,
                "hash": "3ec754fdd76d7ff260528d19cbe7f3a3",
                "status": 0,
                "remark": "df",
                "module": "default",
                "created_at": "2022-05-12T14:26:10.455418+08:00",
                "updated_at": "2022-05-12T14:26:10.455419+08:00",
                "product_key": "2259e91f",
                "product_name": "wifi灯"
            }
        ],
        "total": 20
    }
}

# 5.7 新增固件

  • 接口地址：
POST /openapi/v1/products/{product_key}/ota/firmwares
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

param

true

产品唯一标识

  • 请求体：

字段名

类型

说明

name

string

固件名称

version

string

固件版本，采用"x.y.z"格式

oss_path

string

固件下载地址

algorithms

int

摘要算法：1-md5

hash

string

摘要值

remark

string

备注

module

string

固件所属模块名称

  • 请求示例：
POST /openapi/v1/products/{product_key}/ota/firmwares
{
    "name": "o6",
    "version": "1.2.7",
    "oss_path": "http://localhost:4000/api/v1/oss/buckets/fogcloud-firmware?filename=2259e91f/16523470485CWtlv.zip",
    "algorithms": 1,
    "hash": "3ec754fdd76d7ff260528d19cbe7f3a3",
    "remark": "for test",
    "module": "default"
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "id": 39,
        "name": "o5",
        "version": "1.2.6",
        "oss_path": "http://localhost:4000/api/v1/oss/buckets/fogcloud-firmware?filename=2259e91f/1652336768dcQdFo.zip",
        "algorithms": 1,
        "hash": "3ec754fdd76d7ff260528d19cbe7f3a3",
        "status": 0,
        "ongoing": false,
        "remark": "df",
        "module": "default",
        "created_at": "2022-05-12T14:26:10.455418+08:00",
        "updated_at": "2022-05-12T14:26:10.455419+08:00",
        "product_key": "2259e91f",
        "product_name": "wifi灯"
    }
}

# 5.8 删除固件

  • 接口地址：
DELETE /openapi/v1/ota/firmwares/{firmware_id}
  • 请求参数：

字段名

类型

位置

是否必填

说明

firmware_id

int

param

true

固件唯一 id

  • 请求示例：
DELETE /openapi/v1/firmwares/1
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {}
}

# 5.9 创建固件验证任务

  • 接口地址：
POST /openapi/v1/ota/firmwares/{firmware_id}/verify-task
  • 请求参数：

字段名

类型

位置

是否必填

说明

firmware_id

int

param

true

固件唯一 id

  • 请求体：

字段名

类型

说明

device_ids

array

需要升级的设备 id 列表

upgrade_type

int

升级方式：1-静态升级

cloud_push

bool

是否云端主动推送升级任务

timeout

int

升级超时时间，单位秒

need_app_confirm

bool

是否需要 app 确认升级；若为 true，则需要调用设备升级确认接口后，云端才能向设备推送升级

  • 返回参数：

字段名

类型

说明

data

array

成功创建任务的设备 id 列表

  • 请求示例：
POST /openapi/v1/ota/firmwares/1/verify-task
{
    "device_ids": ["xxxx", "xxxxx", "xxxx"],
    "cloud_push": true,
    "timeout": 1200,
    "need_app_confirm": false
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": ["xxx", "xxxx", "xxxx"]
}

# 5.10 创建固件升级任务

  • 接口地址：
POST /openapi/v1/ota/firmwares/{firmware_id}/upgrade-tasks
  • 请求参数：

字段名

类型

位置

是否必填

说明

firmware_id

int

param

true

固件唯一 id

  • 请求体：

字段名

类型

说明

cloud_push

bool

是否云端主动推送升级任务

timeout

int

升级超时时间，单位秒

upgrade_type

int

升级方式：1-静态升级

scope_mode

int

升级范围：0-全部，1-定向

device_ids

array

需要升级的设备 id 列表

need_app_confirm

bool

是否需要 app 确认升级；若为 true，则需要调用设备升级确认接口后，云端才能向设备推送升级

  • 返回参数：

字段名

类型

说明

task_id

int

升级任务唯一 id

  • 请求示例：
POST /openapi/v1/ota/firmwares/1/upgrade-tasks
{
    "device_ids": ["xxxx", "xxxxx", "xxxx"],
    "cloud_push": true,
    "timeout": 1200,
    "upgrade_type": 1,
    "scope_mode": 1,
    "device_ids": ["xx", "xx"],
    "need_app_confirm": false
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "task_id": 11
    }
}

# 5.11 查询固件验证任务详情

  • 接口地址：
GET /openapi/v1/ota/firmwares/{firmware_id}/verify-task
  • 请求参数：

字段名

类型

位置

是否必填

说明

firmware_id

int

param

true

固件唯一 id

rejected_thing_status

string

query

false

排除的设备状态：online, offline, unactive

  • 返回参数：

字段名

类型

说明

results

list

列表数据

total

int

数据总数

page

int

当前页数

page_size

int

当前页大小

pages

int

总页数

task_id

int

升级任务唯一 id

  • results 参数说明：

字段名

类型

说明

device_id

string

设备唯一 id

device_name

string

设备名

version

string

设备当前固件版本

step

int

设备更新进度

status

int

设备升级状态：

1-待升级，

2-升级中，

3-升级成功，

4-升级失败，

5-升级取消，

updated_at

time

更新时间

thing_status

string

设备状态：online, offline, unactive

need_app_confirm

bool

是否需要 app 确认升级

is_app_confirm

bool

是否已经确认升级；（need_app_confirm=true 时生效

  • 请求示例：
GET /openapi/v1/ota/firmwares/1/verify-task
  • 返回示例：
{
    "code": 0,
    "message": "请求成功",
    "data": {
        "page": 1,
        "page_size": 10,
        "pages": 0,
        "results": [
            {
                "device_id": "4b1da8c4faee4deP1Ljl",
                "device_name": "00000000",
                "version": "1.2.4",
                "step": 0,
                "updated_at": "",
                "status": 1,
                "thing_status": "offline",
                "need_app_confirm": true,
                "is_app_confirm": false
            }
        ],
        "total": 1,
        "task_id": 93
    }
}

# 5.12 查询固件升级任务详情

  • 接口地址：
GET /openapi/v1/ota/upgrade-tasks/{task_id}
  • 请求参数：

字段名

类型

位置

是否必填

说明

task_id

int

param

true

升级任务唯一 id

rejected_thing_status

string

query

false

排除的设备状态：online, offline, unactive

  • 返回参数：

字段名

类型

说明

results

list

列表数据

total

int

数据总数

page

int

当前页数

page_size

int

当前页大小

pages

int

总页数

  • results 参数说明：

字段名

类型

说明

device_id

string

设备唯一 id

device_name

string

设备名

version

string

设备当前固件版本

step

int

设备更新进度

status

int

设备任务状态：

1-待升级，

2-升级中，

3-升级成功，

4-升级失败，

updated_at

time

更新时间

thing_status

string

设备状态：online, offline, unactive

need_app_confirm

bool

是否需要 app 确认升级

is_app_confirm

bool

是否已经确认升级（need_app_confirm=true 时生效

  • 请求示例：
GET /openapi/v1/ota/upgrade-tasks/10

  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "page": 1,
        "page_size": 10,
        "pages": 0,
        "results": [
            {
                "device_id": "6f1aebf2be664edPgac7",
                "device_name": "00000003",
                "version": "",
                "step": 100,
                "updated_at": "",
                "status": 3,
                "thing_status": "offline",
                "need_app_confirm": true,
                "is_app_confirm": false

            },
            {
                "device_id": "10a7786818f84f1yY1ZZ",
                "device_name": "00000004",
                "version": "",
                "step": 0,
                "updated_at": "",
                "status": 4,
                "thing_status": "offline",
                "need_app_confirm": true,
                "is_app_confirm": false
            }
        ],
        "total": 2
    }
}

# 5.13 查询固件升级任务列表

  • 接口地址：
GET /openapi/v1/ota/firmwares/{firmware_id}/upgrade-tasks
  • 返回参数：

字段名

类型

位置

是否必填

说明

firmware_id

int

param

true

固件唯一 id

status

int

query

false

固件状态：

0-待验证

1-验证中

2-验证成功

3-验证失败

4-已取消

task_id

int

query

false

升级任务唯一 id

page

int

query

false

当前页数。（不传则默认为 1）

page_size

int

query

false

每页数据量。（不传则默认为 10）

product_key

string

query

false

固件所属产品唯一标识

name

string

query

false

固件名称

  • results 参数说明：

字段名

类型

说明

task_id

int

升级任务唯一 id

firmware_id

int

固件唯一 id

upgrade_type

int

升级方式：1-静态升级（暂不支持该功能）

status

int

任务状态：

0-待进行

1-任务进行中

2-任务已完成

3-任务已失败

4-任务已取消

scope_mode

int

升级范围: 0-全部, 1-定向

updated_at

time

更新时间

created_at

time

创建时间

need_app_confirm

bool

是否需要 app 确认升级

is_app_confirmed

bool

是否已经确认升级；（need_app_confirm=true 时生效）

  • 请求示例：
GET /openapi/v1/ota/firmwares/1/upgrade-tasks
  • 返回示例：
{
    "code": 0,
    "message": "请求成功",
    "data": {
        "page": 1,
        "page_size": 10,
        "pages": 0,
        "results": [
            {
                "task_id": 90,
                "firmware_id": 40,
                "upgrade_type": 1,
                "upgrade_policy": 1,
                "status": 2,
                "scope_mode": 1,
                "created_at": "2022-05-17T17:20:13.884146+08:00",
                "updated_at": "2022-06-06T15:38:33.537029+08:00",
                "need_app_confirm": true,
                "is_app_confirmed": true
            },
            {
                "task_id": 99,
                "firmware_id": 40,
                "upgrade_type": 1,
                "upgrade_policy": 1,
                "status": 1,
                "scope_mode": 1,
                "created_at": "2022-12-20T17:40:09.43792+08:00",
                "updated_at": "2022-12-20T17:40:09.437923+08:00",
                "need_app_confirm": false,
                "is_app_confirmed": false
            }
        ],
        "total": 2
    }
}

# 5.14 删除固件任务

  • 接口地址：
DELETE /openapi/v1/ota/tasks/{task_id}
  • 请求参数：

字段名

类型

位置

是否必填

说明

task_id

int

param

true

升级任务唯一 id

  • 请求示例：
DELETE /openapi/v1/ota/tasks/1
  • 返回示例：
{
    "code": 0,
    "message": "请求成功",
    "data": {}
}

# 5.15 验证固件任务

  • 接口地址：
PUT /openapi/v1/ota/verify-tasks/{task_id}
  • 请求体：

字段名

类型

是否必填

说明

result

bool

true

验证是否通过

  • 请求示例：
PUT /openapi/v1/ota/verify-tasks/1
{
    "result": true
}
  • 返回示例：
{
    "code": 0,
    "message": "请求成功",
    "data": {}
}

# 5.16 取消固件升级任务

  • 接口地址：
PUT /openapi/v1/ota/upgrade-tasks/{task_id}/status
  • 请求参数：

字段名

类型

位置

是否必填

说明

task_id

int

param

true

升级任务唯一 id

  • 请求示例：
PUT /openapi/v1/ota/upgrade-tasks/1/status
  • 返回示例：
{
    "code": 0,
    "message": "请求成功",
    "data": {}
}

# 5.17 取消设备升级任务

  • 接口地址：
PUT /openapi/v1/ota/upgrade-tasks/{task_id}/things/{device_id}/status
  • 请求参数：

字段名

类型

位置

是否必填

说明

task_id

int

param

true

升级任务唯一 id

device_id

string

param

true

设备唯一 id

  • 请求示例：
PUT /openapi/v1/ota/upgrade-tasks/1/things/xxxx
  • 返回示例：
{
    "code": 0,
    "message": "请求成功",
    "data": {}
}

# 5.18 固件升级任务确认

  • 接口地址：
PUT /openapi/v1/ota/upgrade-tasks/{task_id}/confirmation
  • 请求参数：

字段名

类型

位置

是否必填

说明

task_id

int

param

true

升级任务唯一 id

  • 请求示例：
PUT /openapi/v1/ota/upgrade-tasks/1/confirmation
  • 返回示例：
{
    "code": 0,
    "message": "请求成功",
    "data": {}
}

# 5.19 设备升级任务确认

  • 接口地址：
PUT /openapi/v1/ota/upgrade-tasks/{task_id}/things/{device_id}/confirmation
  • 请求参数：

字段名

类型

位置

是否必填

说明

task_id

int

param

true

升级任务唯一 id

device_id

string

param

true

设备唯一 id

  • 请求示例：
PUT /openapi/v1/ota/upgrade-tasks/1/things/xxxx/confirmation
  • 返回示例：
{
    "code": 0,
    "message": "请求成功",
    "data": {}
}

# 5.20 批量检查设备更新

  • 接口地址：
GET /openapi/v1/things/upgrade
  • 请求参数

字段名

类型

位置

是否必填

说明

device_ids

string

path

true

设备唯一 id

module

string

query

false

模块名称（不传则默认为 default）

  • 请求体：

字段名

类型

是否必填

说明

device_ids

array

true

设备 id 列表

  • 返回参数：

字段名

类型

说明

size

int32

固件大小，单位 byte

sign

string

固件 md5 签名

sign_method

string

摘要算法，固定为 md5

version

string

固件版本，采用"x.y.z"格式

url

string

固件下载 url

module

string

模块名称

task_id

int

当前固件升级任务唯一标识

description

string

固件描述

need_app_confirm

bool

是否需要 app 确认（4.13.0 新增）

is_app_confirmed

bool

app 是否已经确认（4.13.0 新增）

注：只返回有更新的设备的固件信息；

  • 请求示例：
GET /openapi/v1/things/upgrade?module=mcu1
{
    "device_ids": ["13adba9ca44842agHfKU", "60ff5696991b405bkmhn"]
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "things_upgrade_job": {
            "13adba9ca44842agHfKU": {
                "60ff5696991b405bkmhn":  "size": 0,
                "sign": "90d5683b2887b65fc65b5a4b93248fd0",
                "sign_method": "MD5",
                "version": "1.0.1",
                "url": "http://example.com/api/v1/oss/buckets/fogcloud-firmware?filename=f4e7b826/1635748072ekh3Yt.zip",
                "module": "mcu1",
                "task_id": 15,
                "description": "xxxx",
                "need_app_confirm": true,
                "is_app_confirmed": false
         }
       }
    }
}

# 6. 规则引擎

# 6.1 新增场景

  • 接口地址：
POST /openapi/v1/rule-engine/scenes
  • 请求参数：

字段名

类型

位置

是否必填

说明

name

string

body

true

场景名称，具有唯一性

desc

string

body

false

场景描述

status

string

body

true

场景状态。取值：enable（启用），disable（禁用）

triggers

array

body

false

触发条件

conditions

array

body

false

执行条件

actions

array

body

false

执行动作

  • 触发条件字段说明：

字段名

类型

位置

是否必填

说明

URI

enum

body

true

触发类型：

"trigger/device/property"（设备属性），

"trigger/device/event"（设备事件），

"trigger/device/status"（设备状态），

"trigger/cron"（定时器）

params

struct

body

true

详细触发参数

params.product_key

string

body

true

产品身份标识，三元组之一

params.device_name

string

body

true

设备身份标识，三元组之一

（注：设置为"*"时，表示产品下任意设备）

params.property_id

string

body

false

设备属性 id

（注：设置为"*"时，表示任意属性）

params.event_id

string

body

false

设备事件 id

（注：设置为"*"时，表示任意事件）

params.status

enum

body

false

设备状态：

"online"（在线）

"offline"（离线）

"*"（任意状态）

（注：触发类型为设备状态时可用）

params.compare_type

enum

body

false

比较类型：

"=="（等于）

"!="（不等于）

">"（大于）

">="（大于或等于）

"<"（小于）

"<="（小于或等于）

"between"（闭区间）

"in"（在......之中）

"notIn"（不在......之中）

"like"（字符串 like 匹配）

params.compare_val

string

body

false

比较值

params.cron

string

body

false

标准 cron 表达式（支持秒）

（注：触发类型为定时器时可用）

  • 执行条件字段说明：

字段名

类型

位置

是否必填

说明

URI

enum

body

true

执行条件类型：

"condition/device/property"（设备属性），

"condition/device/status"（设备状态），

"condition/time/range"（时间范围）

params

struct

body

true

详细触发参数

params.product_key

string

body

true

产品身份标识，三元组之一

params.device_name

string

body

true

设备身份标识，三元组之一；

（注：设置为"*"时，表示产品下任意设备）

params.property_id

string

body

false

设备属性 id

（注：设置为"*"时，表示任意属性）

params.status

enum

body

false

设备状态：

"online"（在线）

"offline"（离线）

"*"（任意状态）

（注：执行条件类型为设备状态时可用）

params.status_duration

int

body

false

设备状态持续时间，单位分钟；

（注：执行条件类型为设备状态时可用）

params.compare_type

string

body

false

比较类型：

"=="（等于）

"!="（不等于）

">"（大于）

">="（大于或等于）

"<"（小于）

"<="（小于或等于）

"between"（闭区间）

"in"（在......之中）

"notIn"（不在......之中）

"like"（字符串 like 匹配）

params.compare_val

string

body

false

比较值

  • 执行动作字段说明：

字段名

类型

位置

是否必填

说明

URI

enum

body

true

执行动作类型：

"action/device/property"（设置设备属性），

"action/device/service"（调用设备服务），

"action/rule"（触发其他场景）

"action/webhook"（触发 webhook）

params

struct

body

true

详细触发参数

params.scene_id

string

body

false

被触发的其他场景 id

（注：当执行动作为触发其他场景时必填）

params.device_id

string

body

false

设备唯一标识

（注：当执行动作为设备相关时必填）

params.service_id

string

body

false

设备服务 id

params.property_id

string

body

false

设备属性 id

params.items

object

body

false

设备服务调用入参或设备属性设置值

params.URL

string

body

false

webhook 的 URL

（注：当执行动作为 wehook 时必填）

params.method

string

body

false

webhook 请求方法

（注：当执行动作为 wehook 时必填）

params.desc

string

body

false

webhook 描述

（注：当执行动作为 wehook 时可用）

params.connect_timeout

int

body

false

webhook 连接超时时间，单位秒

（注：当执行动作为 wehook 时可用）

params.request_timeout

int

body

false

webhook 请求超时时间，单位秒

（注：当执行动作为 wehook 时可用）

  • 请求示例：
POST /openapi/v1/rule-engine/scenes
{
    "name": "rule_1",
    "status": "enable",
    "triggers": [
        {
            "URI": "trigger/device/property",
            "params": {
                "type": "trigger/device/property",
                "product_key": "de8d0d3f",
                "device_name": "00002697",
                "property_id": "prop1",
                "compare_type": "==",
                "compare_val": "100"
            }
        },
        {
            "URI": "trigger/device/event",
            "params": {
                "type": "trigger/device/event",
                "product_key": "de8d0d3f",
                "device_name": "0000270e",
                "event_id": "*"
            }
        },
        {
            "URI": "trigger/device/status",
            "params": {
                "type": "trigger/device/status",
                "time_range": {},
                "items": {},
                "product_key": "de8d0d3f",
                "device_name": "0000270f",
                "status": "online"
            }
        },
        {
            "URI": "trigger/cron",
            "params": {
                "type": "trigger/cron",
                "cron": "5 * * * * *"
            }
        }
    ],
    "conditions": [
        {
            "URI": "condition/device/property",
            "params": {
                "type": "condition/device/property",
                "product_key": "de8d0d3f",
                "device_name": "0000270e",
                "property_id": "prop2",
                "compare_type": "<",
                "compare_val": "10"
            }
        },
        {
            "URI": "condition/device/status",
            "params": {
                "type": "condition/device/status",
                "product_key": "de8d0d3f",
                "device_name": "0000270b",
                "status": "online",
                "status_duration": 10
            }
        },
        {
            "URI": "condition/time/range",
            "params": {
                "type": "condition/time/range",
                "time_range": {
                    "start_timestamp": 1646296350,
                    "end_timestamp": 1647073950
                }
            }
        }
    ],
    "actions": [
        {
            "URI": "action/device/service",
            "params": {
                "type": "action/device/service",
                "items": {
                    "prop2": "17"
                },
                "product_key": "de8d0d3f",
                "device_id": "fab44c87bf7948f6M0WI",
                "service_id": "prop2"
            }
        },
        {
            "URI": "action/webhook",
            "params": {
                "type": "action/webhook",
                "URL": "https://demo.webhook.com",
                "method": "POST",
                "connect_timeout": 10,
                "request_timeout": 10,
                "desc": "for example"
            }
        }
    ]
}

# 6.2 删除场景

  • 接口地址：
DELETE /openapi/v1/rule-engine/scenes/{id}

# 6.3 更新场景

  • 接口地址：
PUT /openapi/v1/rule-engine/scenes/{id}

请求参数同新增场景

# 6.4 查询场景详情

  • 接口地址：
GET /openapi/v1/rule-engine/scenes/{id}
  • 请求示例：
GET /openapi/v1/rule-engine/scenes/61e521e7f0988d8865d42864
  • 返回示例：
{
    "code": 0,
    "message": "请求成功",
    "data": {
        "id": "61e521e7f0988d8865d42864",
        "created_at": 1642406375,
        "updated_at": 1646382807,
        "name": "rule_1",
        "status": "enable",
        "triggers": [
            {
                "URI": "trigger/device/property",
                "params": {
                    "product_key": "de8d0d3f",
                    "device_name": "00002697",
                    "property_id": "prop1",
                    "compare_type": "==",
                    "compare_val": "100"
                }
            },
            {
                "URI": "trigger/device/event",
                "params": {
                    "product_key": "de8d0d3f",
                    "device_name": "0000270e",
                    "event_id": "*"
                }
            },
            {
                "URI": "trigger/device/status",
                "params": {
                    "product_key": "de8d0d3f",
                    "device_name": "0000270f",
                    "status": "online"
                }
            },
            {
                "URI": "trigger/cron",
                "params": {
                    "cron": "5 * * * * *",
                    "cron_id": "1499664307204395008"
                }
            }
        ],
        "conditions": [
            {
                "URI": "condition/device/property",
                "params": {
                    "product_key": "de8d0d3f",
                    "device_name": "0000270e",
                    "property_id": "prop2",
                    "compare_type": "==",
                    "compare_val": "10"
                }
            },
            {
                "URI": "condition/device/status",
                "params": {
                    "product_key": "de8d0d3f",
                    "device_name": "0000270b",
                    "status_duration": 10,
                    "status": "online"
                }
            },
            {
                "URI": "condition/time/range",
                "params": {
                    "time_range": {
                        "start_timestamp": 1646296350,
                        "end_timestamp": 1647073950
                    }
                }
            }
        ],
        "actions": [
            {
                "URI": "action/device/service",
                "params": {
                    "service_id": "prop2",
                    "device_id": "fab44c87bf7948f6M0WI",
                    "product_key": "de8d0d3f",
                    "items": {
                        "prop2": "17"
                    }
                }
            },
            {
                "URI": "action/webhook",
                "params": {
                    "URL": "https://demo.webhook.com",
                    "method": "POST",
                    "desc": "for example",
                    "connect_timeout": 10,
                    "request_timeout": 10
                }
            }
        ]
    }
}

# 6.5 查询场景列表

  • 接口地址：
GET /openapi/v1/rule-engine/scenes

# 6.6 手动执行场景动作

  • 接口地址：
POST /openapi/v1/rule-engine/scenes/{id}/actions

# 6.7 更新场景状态

  • 接口地址：
PUT /openapi/v1/rule-engine/scenes/{id}/status
  • 请求体：

字段名

类型

是否必填

说明

status

string

true

启用-enable,

禁用-disable

  • 请求示例：
POST /openapi/v1/rule-engine/scenes/xxx/status
{
    "status": "enable"
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {}
}

# 7. 对象存储服务

# 7.1 上传对象

  • 接口地址：
POST /openapi/v1/oss
  • 请求表单

字段名

类型

说明

file

binary

文件，通过 form 表单提交

  • 返回参数：

字段名

类型

说明

url

string

文件下载 url

md5

string

文件 md5 摘要

  • 请求示例：
POST /openapi/v1/oss
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "url": "xxx",
        "md5": "xxx"
    }
}

说明：返回的 url 支持请求头 GET/DELETE

# 7.2 上传 ota 固件

  • 接口地址：
POST /openapi/v1/oss/ota/{product_key}
  • 请求参数

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

  • 请求表单

字段名

类型

说明

file

binary

文件，通过 form 表单提交

  • 返回参数：

字段名

类型

说明

filename

string

文件下载 url

size

int64

文件大小（字节）

md5

string

文件 md5 摘要

  • 请求示例：
POST /openapi/v1/oss/ota/248e7a12
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "filename": "xxx",
        "md5": "xxx",
        "size": 1024
    }
}

# 8. mesh 相关

# 8.1 创建 mesh_network

  • 接口地址：
POST /openapi/v1/mesh/networks
  • 请求体：

字段名

类型

是否必填

说明

network_key

string

false

若为空则自动生成

app_key

string

false

若为空则自动生成

  • 返回参数：

字段名

类型

说明

app_key

string

network_key

string
  • 请求示例：
POST /openapi/v1/mesh/networks
{
    "network_key": "f3724cc131364ec7aaa428ec874d4496",
    "app_key": "61161029b31b412dafb05d1b793b8246"
}

  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "network_key": "f3724cc131364ec7aaa428ec874d4496",
        "app_key": "61161029b31b412dafb05d1b793b8246"
    }
}

# 8.2 查询 mesh_network

  • 接口地址：
GET /openapi/v1/mesh/networks/{network_key}
  • 请求参数：

字段名

类型

位置

是否必填

说明

network_key

string

path

true

mesh 网络唯一标识

  • 返回参数：

字段名

类型

说明

app_key

string

network_key

string

unicast_cursor

int

provisioner_cursor

int

created_at

date

updated_at

date
  • 请求示例：
GET /openapi/v1/mesh/networks/acea3bcdcd8d4fd286de80a57fee188a
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "network_key": "acea3bcdcd8d4fd286de80a57fee188a",
        "app_key": "5a856251bc3e4f60af8a8b16a2b17c3c",
        "unicast_cursor": 261,
        "provisioner_cursor": 3,
        "created_at": "2022-08-01T10:03:03.982405+08:00",
        "updated_at": "2022-08-01T10:03:03.982424+08:00"
    }
}

# 8.3 删除 mesh_network

  • 接口地址：
DELETE /openapi/v1/mesh/networks/{network_key}
  • 请求参数：

字段名

类型

位置

是否必填

说明

network_key

string

path

true

mesh 网络唯一标识

  • 请求示例：
DELETE /openapi/v1/mesh/networks/acea3bcdcd8d4fd286de80a57fee188a
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS"
}

# 8.4 添加 mesh_node

  • 接口地址：
POST /openapi/v1/mesh/networks/{network_key}/nodes
  • 请求参数：

字段名

类型

位置

是否必填

说明

network_key

string

path

true

mesh 网络唯一标识

  • 请求体：

字段名

类型

说明

product_key

string

device_name

string

sign

string

设备签名

sign_method

string

消息摘要算法：hmacsha1, hmacmd5, aescmac

mesh_addr

int

node_type

int

mesh 节点类型：1-子设备, 2-网关设备

  • 请求示例：
POST /openapi/v1/mesh/networks/acea3bcdcd8d4fd286de80a57fee188a/nodes
{
    "product_key": "6f2f5483",
    "device_name": "00000044",
    "sign": "xxxx",
    "mesh_addr": 300,
    "node_type": 1
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS"
}

# 8.5 删除 mesh_node

  • 接口地址：
DELETE /openapi/v1/mesh/networks/{network_key}/nodes/{device_id}
  • 请求参数：

字段名

类型

位置

是否必填

说明

network_key

string

path

true

mesh 网络唯一标识

device_id

string

path

true

设备唯一标识

  • 请求示例：
DELETE /openapi/v1/mesh/networks/acea3bcdcd8d4fd286de80a57fee188a/nodes/xxxxx
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS"
}

# 8.6 透传网关数据

  • 接口说明：

直接向 mesh 网关发送数据，可用于 mesh 组控、mesh 本地场景等功能。

  • 接口地址：
POST /openapi/v1/mesh/networks/{network_key}/raw-data
  • 请求体：

字段名

类型

说明

raw_data

string
  • 请求示例：
POST /openapi/v1/mesh/networks/acea3bcdcd8d4fd286de80a57fee188a/raw-data
{
    "raw_data": "020e3f"
}
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS"
}

# 9. 设备配网相关

# 9.1 查询设备配网结果

  • 接口说明：

查看设备配网时的绑定随机码，若接口返回成功，则表示设备配网成功

  • 接口地址：
GET /openapi/v1/products/{product_key}/device-names/{device_name}/bind
  • 请求参数：

字段名

类型

位置

是否必填

说明

product_key

string

path

true

产品唯一标识

device_name

string

path

true

设备 device_name

  • 返回参数：

字段名

类型

说明

random

string

该设备本次配网的标识

  • 请求示例：
GET /openapi/v1/products/020e5412/device-names/00000020/bind
  • 返回示例：
{
    "code": 0,
    "message": "SUCCESS",
    "data": {
        "random": "string"
    }
}
更新时间: 2023/3/16 下午6:19:02

← 错误码 →