页面树结构
转至元数据结尾
转至元数据起始



概览

  • 本文档包括产品管理与设备管理两个模块接口:
    1. 企业开发者可以调用产品系列接口,进行产品的相关管理,包括产品、产品固件版本、产品数据端点、产品数据的转发规则等相关接口。 
    2. 企业开发者可以调用设备系列接口,进行设备的相关管理,目前设备信息包括以下两种: 
  • 基础字段信息:是指XLink默认给设备的信息,指的是id(设备ID)、mac(设备MAC地址)等。 
  • 扩展字段信息:是指由企业自定义扩展的信息,由企业开发者创建,目前默认提供10个扩展字段。

接口详情

1.添加产品

企业管理员添加一个产品,需指定产品名称、类型以及描述。

Request

URL

POST /v2/product


Header

Content-Type:application/json
Access-Token:"调用凭证"


Content

{
"name": "产品名称",
"description": "产品描述",
"link_type": "设备连接类型",
"mode":"产品型号",
"type":"产品类型",
"os_type":"os类型",
"visibility":"可见范围"
 }



字段是否必须描述
name产品名称,32个字符以内
description产品描述,250个字符以内
link_type设备连接类型,见产品附录1
mode产品的型号,64个字符
type产品类型
os_type

os类型

安卓:Android

苹果:Ios

微软:Windows

Linux:Linux

实时系统:Rtos

其他:Other

visibility

可见范围

0:企业可见

1:企业用户均可见

Response

Header

HTTP/1.1 200 OK

Content

{
	    "id": "产品id",
	    "name": "产品名称",
	    "description": "产品描述",
		"mode":"产品的型号",
	    "key": "产品密钥",
	    "link_type": "设备连接类型",
	    "is_release": "是否发布",
	    "is_registerable": "是否允许用户注册设备",
		"is_active_register":"是否允许通过激活注册设备",
		"is_allow_multi_admin":"是否允许设备多个管理员",
		"create_time":"创建时间,"
		"type":"产品类型",
		"quota":"设备配额总数",
		"pics":["http://www.xlink.cn/pic1","http://www.xlink.cn/pic2"],
		"extend":{{keay}:{value}},
		"device_type":"设备类型",
		"categories":["设备品类"],
		"os_type":"os类型",
        "visibility":"可见范围"
	}


字段是否必须描述
id产品ID,32个字符
name产品名称,32个字符以内
description产品描述,250个字符以内
mode产品的型号,长度在64个字符以内
key产品密钥,16个字符
link_type设备连接类型,见产品附录1
is_release是否发布,布尔类型,true或false
is_registerable是否允许用户注册设备
is_active_register是否允许通过激活注册设备
is_allow_multi_admin否允许设备多个管理员,默认为:true
create_time产品创建时间
type产品类型,见产品附录5
quota设备配额总数,整数
pics产品图片列表
extend扩展属性
device_type设备类型
categories产品品类
os_typeos类型
visibility

可见范围

0:企业可见

1:企业用户均可见

2.删除产品

企业管理员根据产品标识product_id url中删除一个已添加的产品,已发布的产品不可删除。

Request

URL

DELETE /v2/product/{product_id}
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

3.更新产品信息

企业管理员根据产品标识product_id url中修改一个已添加的产品信息,已发布的产品不可修改,<br可修改产品名称、连接类型、描述、是否发布以及是否允许用户注册设备。

Request

URL

PUT /v2/product/{product_id}
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

{
    "name": "产品名称",
    "description": "产品描述",
    "link_type": "设备连接类型",
    "mode":"产品的型号",
    "is_release": "是否发布",
    "is_registerable": "是否允许用户注册设备",
    "is_active_register":"是否允许通过激活注册设备",
    "is_allow_multi_admin":"是否允许设备多个管理员",
    "user_role_authority":"普通用户对设备的权限,默认RW",
    "scan_mode":"扫描订阅策略,枚举值,见附录",
    "type":"产品类型",
    "pics":["http://www.xlink.cn/pic1","http://www.xlink.cn/pic2"],
    "qrcode":"产品二维码",

       "categories":["产品品类","产品品类"],

      "is_device_reset_clean_data":false,

      “os_type”:“os类型”,
      "visibility":"可见范围"

}
字段是否必须描述
name产品名称,32个字符以内
description产品描述,250个字符以内
link_type设备连接类型,见产品附录1
mode产品的型号,长度在64个字符以内
is_release是否发布,布尔类型,true或false
is_registerable是否允许用户注册设备
is_active_register是否允许通过激活注册设备
is_allow_multi_admin否允许设备多个管理员
user_role_authority普通用户对设备的权限,默认RW
scan_mode扫描订阅策略,枚举值,见附录
type产品类型,见产品附录5
pics产品图片列表
qrcode产品二维码
categories产品品类
is_device_reset_clean_data设备重置时是否清除数据
os_typeos类型
visibility

可见范围

0:企业可见

1:企业用户均可见

Response

Header

HTTP/1.1 200 OK

Content

4.获取产品列表

企业管理员获取自己企业下产品的列表信息。

Request

URL

GET /v2/products

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

[
	    {
	        "id": "产品ID",
	        "name": "产品名称",
	        "description": "产品描述",
	        "link_type": "设备连接类型",
			"mode":"产品的型号",
	        "is_release": "是否发布",
	        "is_registerable": "是否允许用户注册设备"
			"is_active_register":"是否允许通过激活注册设备",
			"is_allow_multi_admin":"是否允许设备多个管理员",
			"user_role_authority":"普通用户对设备的权限,默认RW",
			"create_time":"创建时间",
			"type":"产品类型",
			"quota":"设备配额总数",
			"scan_mode":"扫描订阅策略,枚举值,见附录",
			"pics":["http://www.xlink.cn/pic1","http://www.xlink.cn/pic2"],
			"qrcode":"产品二维码",
			"extend":{{keay}:{value}},
			"device_type":"设备类型",
			"mode":"产品型号",
			"extend":"产品拓展信息",
			"is_gateway_device":"是否为网关设备",
			"categories":["产品品类"],
			"visibility":"产品可见权限",
			"is_home_product": "是否为首页产品",
			"browse_time": "2018-05-25T17:58:10.77Z",
			"os_type":"os类型"
	 }
	]


字段是否必须描述
id产品ID
name产品名称,32个字符以内
description产品描述,250个字符以内
link_type设备连接类型,见产品附录1
mode产品的型号,长度在64个字符以内
is_release是否发布,布尔值,true或false
is_registerable是否允许用户注册设备
is_active_register是否允许通过激活注册设备
is_allow_multi_admin否允许设备多个管理员
create_time产品创建时间
user_role_authority普通用户对设备的权限,默认RW
type产品类型,见产品附录5
quota设备配额总数,整数
scan_mode扫描订阅策略,枚举值,见附录
pics产品图片列表
qrcode产品二维码
extend扩展属性
device_type
设备类型
is_gateway_device
是否为网关设备
categories产品品类
visibility产品可见权限
is_home_product是否为首页产品
browse_time最近浏览时间
os_typeos类型

5.获取产品详细信息

企业管理员根据产品标识product_id url中获取单个产品详细信息。

Request

URL

GET /v2/product/{product_id}
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
	    "id": "产品ID",
	    "name": "产品名称",
	    "description": "产品描述",
	    "link_type": "设备连接类型",
		"mode":"产品的型号",
	    "is_release": "是否发布",
	    "is_registerable": "是否允许用户注册设备",
		"is_active_register":"是否允许通过激活注册设备",
		"is_allow_multi_admin":"是否允许设备多个管理员",
		"user_role_authority":"普通用户对设备的权限,默认RW",
		"create_time":"创建时间",
		"type":"产品类型",
		"quota":"设备配额总数",
		"scan_mode":"扫描订阅策略,枚举值,见附录",
		"pics":["http://www.xlink.cn/pic1","http://www.xlink.cn/pic2"],
		"qrcode":"产品二维码",
		"device_type":"设备类型",
		"mode":"产品型号",
		"extend":"产品拓展信息",
		"is_gateway_device":"是否为网关设备",
		"categories":["产品品类"],
		"visibility":"产品可见权限",
		"is_home_product": "是否为首页产品",
		"browse_time": "2018-05-25T17:58:10.77Z",
		"os_type":"os类型"	
 }


字段是否必须描述
id产品ID
name产品名称,32个字符以内
description产品描述,250个字符以内
link_type设备连接类型,见产品附录1
mode产品的型号,长度在64个字符以内
is_release是否发布
is_registerable是否允许用户注册设备
is_active_register是否允许通过激活注册设备
is_allow_multi_admin否允许设备多个管理员
create_time产品创建时间
user_role_authority普通用户对设备的权限,默认RW
type产品类型,见产品附录5
quota设备配额总数,整数
scan_mode扫描订阅策略,枚举值,见附录
pics产品图片列表
qrcode产品二维码
extend扩展属性
device_type
设备类型
is_gateway_device
是否为网关设备
categories产品品类
visibility产品可见权限
is_home_product是否为首页产品
browse_time最近浏览时间
os_typeos类型

6.获取产品密钥

企业管理员根据产品产品标识product_id url中获取产品密钥。

Request

URL

GET /v2/product/{product_id}/key
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
    "key":"产品密钥"
}
字段是否必须描述
key产品密钥

7.添加固件版本

企业管理员为某个产品添加一个固件版本,需要指定固件型号、 固件版本号、固件文件地址、固件文件MD5值、固件文件大小、描述、发布日期以及是否发布。

Request

URL

POST /v2/product/{product_id}/firmware
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

{
    "mod": "固件型号",
    "version": "固件版本号",
    "file_url": "固件文件地址",
    "file_md5": "固件文件MD5值",
    "file_size": "固件文件大小",
    "description": "描述",
    "release_date": "发布日期",
    "is_release": "是否发布",
    "type" : "固件类型",
    "identify":"用来定位多MCU或多子设备的情况"
}
字段是否必须描述
mod固件型号,20个字符以内
version固件版本号,32位整形
file_url固件文件地址,250个字符以内
file_md5固件文件MD5值
file_size固件文件大小
description描述,250字符以内
release_date指定发布日期,例:2015-10-09T08 : 15 : 40.843Z
is_release是否发布,布尔类型,true或false
type固件类型,新增,见附件设备固件类型, 默认为wifi
identify用来定位多MCU或多子设备的情况, 数字, type为mcu或多子设备时必传, version/type/identify联合唯一

Response

Header

HTTP/1.1 200 OK

Content

{
    "id": "固件版本ID",
    "mod": "固件型号",
    "version": "固件版本号",
    "file_url": "固件文件地址",
    "file_md5": "固件文件MD5值",
    "description": "描述",
    "release_date": "固件发布日期",
    "create_date": "固件创建日期",
    "is_release": "是否发布",
    "type" : "固件类型",
    "identify":"用来定位多MCU或多子设备的情况"
}
字段是否必须描述
id固件ID
mod固件型号,20个字符以内
version固件版本号,32位整形
file_url固件文件地址,250个字符以内
file_md5固件文件MD5值
file_size固件文件大小
description描述,250字符以内
release_date固件发布日期,例:2015-10-09T08 : 15 : 40.843Z
create_date固件创建日期,例:2015-10-09T08 : 15 : 40.843Z
is_release是否发布,布尔值,true或false
type固件类型,新增,见附件设备固件类型, 默认为wifi
identify用来定位多MCU或多子设备的情况, 数字, type为mcu或多子设备时存在, version/type/identify联合唯一, 默认为0

8.编辑固件版本

企业管理员根据产品标识product_id以及版本标识firmware_id url中修改固件版本中的固件型号、固件版本号、固件文件地址、固件文件MD5值、固件文件大小、描述、固件发布日期以及是否发布。

Request

URL

PUT /v2/product/{product_id}/firmware/{firmware_id}
字段是否必须描述
product_id产品ID,32个字符
firmware_id固件版本ID

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

{
    "mod":"固件型号",
    "version":"固件版本号",
    "file_url":"固件文件地址",
    "file_md5":"固件文件MD5值",
    "file_size":"固件文件大小",
    "description":"描述",
    "release_date":"固件发布日期",
    "is_release":"是否发布"
}
字段是否必须描述
mod固件型号,20个字符以内
version固件版本号,32位整形
file_url固件文件地址,250个字符以内
file_md5固件文件MD5值
file_size固件文件大小
description描述,250字符以内
release_date固件发布日期,例:2015-10-09T08 : 15 : 40.843Z
is_release是否发布,布尔值,true或false

Response

Header

HTTP/1.1 200 OK

Content

{
    "id": "固件版本ID",
    "mod": "固件型号",
    "version": "固件版本号",
    "file_url": "固件文件地址",
    "file_md5": "固件文件MD5值",
    "file_size": "固件文件大小",
    "description": "描述",
    "release_date": "固件发布日期",
    "create_date": "固件创建日期",
    "is_release": "是否发布"
}
字段是否必须描述
id固件ID
mod固件型号,20个字符以内
version固件版本号,32位整形
file_url固件文件地址,250个字符以内
file_md5固件文件MD5值
file_size固件文件大小
description描述,250字符以内
release_date固件发布日期,例:2015-10-09T08 : 15 : 40.843Z
create_date固件创建日期,例:2015-10-09T08 : 15 : 40.843Z
is_release是否发布,布尔值,true或false

9.删除固件版本

企业管理员根据产品标识product_id以及版本标识firmware_id url中 删除指定产品的指定固件版本。

Request

URL

DELETE /v2/product/{product_id}/firmware/{firmware_id}
字段是否必须描述
product_id产品ID,32个字符
firmware_id固件版本ID

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

10.获得固件版本列表

企业管理员根据产品标识product_id url中查询产品的所有固件版本。

Request

URL

GET /v2/product/{product_id}/firmwares?offset={offset}&limit={limit}
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Respones

Header

HTTP/1.1 200 OK

Content

[
    {
        "id": "固件版本ID",
        "mod": "固件型号",
        "version": "固件版本号",
        "file_url": "固件文件地址",
        "file_md5": "固件文件MD5值",
        "file_size": "固件文件大小",
        "description": "描述",
        "release_date": "固件发布日期",
        "create_date": "固件创建日期",
        "is_release": "是否发布",
        "type" : "固件类型",
        "identify":"用来定位多MCU或多子设备的情况",
"from_version_by_task":"是否已经被升级任务作为启始版本",
"used_by_running_task":"是否已经被处于升级中的升级任务使用, 可以用于标识改固件不能被编辑" } ]
字段是否必须描述
id固件ID
mod固件型号,20个字符以内
version固件版本号,32位整形
file_url固件文件地址,250个字符以内
description描述,250字符以内
release_date固件发布日期,例:2015-10-09T08 : 15 : 40.843Z
create_date固件创建日期,例:2015-10-09T08 : 15 : 40.843Z
is_release是否发布,布尔值,true或false
file_md5固件文件Md5
file_size固件文件大小
description描述,250字符以内
release_date固件发布日期,例:2015-10-09T08 : 15 : 40.843Z
create_date固件创建日期,例:2015-10-09T08 : 15 : 40.843Z
is_release是否发布,布尔值,true或false
type固件类型,新增,见附件设备固件类型, 默认为wifi
identify用来定位多MCU或多子设备的情况, 数字, version/type/identify联合唯一, 默认为0
from_version_by_task是否已经被升级任务作为启始版本
used_by_running_task是否已经被处于升级中的升级任务使用, 可以用于标识改固件不能被编辑

11.添加数据端点

企业管理员为企业下的某个产品添加一个新的数据端点,包括数据端点名称、数据类型、数据端点索引、描述、符号以及是否收集端点数据。

Request

URL

POST /v2/product/{product_id}/datapoint
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

{
    "name":"数据端点名称",
    "type":"数据类型",
    "index":"数据端点索引",
    "description":"描述",
    "symbol":"符号",
    "is_collect":"是否收集端点数据",
    "min":"数据端点取值范围,最小值",
    "max":"数据端点取值范围,最大值",
    "is_read":"数据端点是否可读",
    "is_write":"数据端点是否可写",
    "default_value":"数据端点默认值",
    "expression":"动态计算数据端点表达式",
    "source":"数据来源类型",
"permission_list":[1,2],
"field_name":"字段名称"
}


字段是否必须描述
name数据端点名称,32个字符以内
type数据类型,见产品附录2
index数据端点索引,32位数字整形
description数据端点描述,250个字符以内
symbol符号,10个字符以内
is_collect是否收集端点数据,默认:否
min数据端点取值范围,最小值
max数据端点取值范围,最大值
is_read布尔值,数据端点是否可读
is_write布尔值,数据端点是否可写
default_valuestring, 数据端点默认值
source数据来源类型,见产品附录6
expressionstring, 数据来源为计算类型时,数据端点表达式, 假如要引用其他数据端点:@index@ + 1, 加入要引用所属产品拓展属性则: #property# + 2
permission_list
可更新该数据端点的权限集合, 1:企业成员,2:企业授权,3:用户, 4:设备, 5:平台, 其中设备上报类型数据端点只能是4, 计算型数据端点只能是5,应用型数据端点可任意
field_name
字段名称

Response

Header

HTTP/1.1 200 OK

Content

{
    "id": "数据端点ID",
    "name": "数据端点名称",
    "type": "数据类型",
    "index": "数据端点索引",
    "description": "描述",
    "symbol": "符号",
    "is_collect": "是否收集端点数据",
    "min":"数据端点取值范围,最小值",
    "max":"数据端点取值范围,最大值",
    "is_read":"数据端点是否可读",
    "is_write":"数据端点是否可写",
    "default_value":"数据端点默认值",
    "expression":"动态计算数据端点表达式",
    "source":"数据来源类型",

       "ui_visible":{
           "state":"设备状态可见",
           "control":"远程控制可见"
       },
      "field_name":"字段名称",
     "is_system":"是否为系统数据端点"

}
字段是否必须描述
id数据端点ID
name数据端点名称,32个字符以内
type数据类型,见产品附录2
index数据端点索引,32位数字整形
description数据端点描述,250个字符以内
symbol符号,10个字符以内
is_collect是否收集端点数据,默认:否
min数据端点取值范围,最小值,默认为0
max数据端点取值范围,最大值,默认为0
is_read布尔值,数据端点是否可读
is_write布尔值,数据端点是否可写
default_valuestring, 数据端点默认值
source数据来源类型,见产品附录6
expressionstring, 数据来源为计算类型时,数据端点表达式, 假如要引用其他数据端点:@index@ + 1, 加入要引用所属产品拓展属性则: #property# + 2
permission_list可更新该数据端点的权限集合, 1:企业成员,2:企业授权,3:用户, 4:设备, 5:平台, 其中设备上报类型数据端点只能是4, 计算型数据端点只能是5,应用型数据端点可任意
ui_visibleui页面是否显示, 布尔值
field_name字段名称
is_system是否为系统数据端点

12.修改数据端点

企业管理员根据产品标识product_id以及数据端点标识datapoint_id url中 进行修改数据端点相应信息,包括数据端点名称、数据类型、数据端点索引、描述、符号、是否收集端点数据,产品已发布情况下不可修改。

Request

URL

PUT /v2/product/{product_id}/datapoint/{datapoint_id}
字段是否必须描述
product_id产品ID,32个字符
datapoint_id数据端点ID

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

{
	    "name": "数据端点名称",
	    "type": "数据类型",
	    "index": "数据端点索引",
	    "description": "描述",
	    "symbol": "符号",
	    "is_collect": "是否收集端点数据",
		"min":"数据端点取值范围,最小值",
		"max":"数据端点取值范围,最大值",
		"is_read":"数据端点是否可读",
		"is_write":"数据端点是否可写",
		"default_value":"数据端点默认值",
		"expression":"动态计算数据端点表达式",
		"ui_visible":{
			"state":"设备状态可见",
			"control":"远程控制可见"
		},
		"field_name":"字段名称"
	}


字段是否必须描述
name数据端点名称,32个字符以内
type数据类型,见产品附录2
index数据端点索引,16位整形
description数据端点描述,250个字符内
symbol符号,10个字符以内
is_collect是否收集端点数据,默认:否,
min数据端点取值范围,最小值,默认为0
max数据端点取值范围,最大值,默认为0
is_read布尔值,数据端点是否可读
is_write布尔值,数据端点是否可写
default_valuestring, 数据端点默认值
expressionstring, 数据来源为计算类型时,数据端点表达式, 假如要引用其他数据端点:@index@ + 1, 加入要引用所属产品拓展属性则: #property# + 2
permission_list可更新该数据端点的权限集合, 1:企业成员,2:企业授权,3:用户, 4:设备, 5:平台, 其中设备上报类型数据端点只能是4, 计算型数据端点只能是5,应用型数据端点可任意
ui_visibleui页面是否显示, 布尔值
field_name字段名称

Response

Header

HTTP/1.1 200 OK

Content

13.删除数据端点

通过产品ID和数据端点标识ID删除数据端点。

Request

URL

DELETE /v2/product/{product_id}/datapoint/{datapoint_id}
字段是否必须描述
product_id产品ID,32个字符
datapoint_id数据端点ID

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

14.获取数据端点

企业管理员根据产品标识product_id以及数据端点标识datapoint_id url中 获取数据端点信息。

Request

URL

GET /v2/product/{product_id}/datapoint/{datapoint_id}
字段是否必须描述
product_id产品ID,32个字符
datapoint_id数据端点ID

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
	    "id": "数据端点ID",
	    "name": "数据端点名称",
	    "type": "数据类型",
	    "index": "数据端点索引",
	    "description": "描述",
	    "symbol": "符号",
	    "is_collect": "是否收集端点数据",
		"min":"数据端点取值范围,最小值",
		"max":"数据端点取值范围,最大值",
		"is_read":"数据端点是否可读",
		"is_write":"数据端点是否可写",
		"default_value":"数据端点默认值",
		"expression":"动态计算数据端点表达式",
		"source":"数据来源类型",
		"ui_visible":{
			"state":"设备状态可见",
			"control":"远程控制可见"
		},
		"field_name":"字段名称",
		"is_system":"是否为系统数据端点"
	}


字段是否必须描述
id数据端点ID
name数据端点名称,32个字符以内
type数据类型,见产品附录2
index数据端点索引,16位整形
description数据端点描述,250个字符内
symbol符号,10个字符以内
is_collect是否收集端点数据,默认:否
min数据端点取值范围,最小值
max数据端点取值范围,最大值
is_read布尔值,数据端点是否可读
is_write布尔值,数据端点是否可写
default_valuestring, 数据端点默认值
source数据来源类型,见产品附录6
expressionstring, 数据来源为计算类型时,数据端点表达式, 假如要引用其他数据端点:@index@ + 1, 加入要引用所属产品拓展属性则: #property# + 2
permission_list

可更新该数据端点的权限集合, 1:企业成员,2:企业授权,3:用户, 4:设备, 5:平台, 其中设备上报类型数据端点只能是4, 计算型数据端点只能是5,应用型数据端点可任意

ui_visibleui页面是否显示, 布尔值
field_name字段名称
is_system是否为系统数据端点

15.获取数据端点列表

根据product_id获取某种产品的数据端点列表。

Request

URL

GET /v2/product/{product_id}/datapoints
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"企业调用凭证/用户调用凭证/设备调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

[
	    {
	        "id": "数据端点ID",
	        "name": "数据端点名称",
	        "type": "数据类型",
	        "index": "数据端点索引",
	        "description": "描述",
	        "symbol": "符号",
	        "is_collect": "是否收集端点数据",
			"min":"数据端点取值范围,最小值",
			"max":"数据端点取值范围,最大值",
			"is_read":"数据端点是否可读",
			"is_write":"数据端点是否可写",
			"default_value":"数据端点默认值",
			"expression":"动态计算数据端点表达式",
			"source":"数据来源类型",
			"ui_visible":{
				"state":"设备状态可见",
				"control":"远程控制可见"
			},
			"field_name":"字段名称",
			"is_system":"是否为系统数据端点"
	    }
	]


字段是否必须描述
id数据端点ID
name数据端点名称,32个字符以内
type数据类型,见产品附录2
index数据端点索引,16位整形
description数据端点描述,250个字符内
symbol符号,10个字符以内
is_collect是否收集端点数据,默认:否,
min数据端点取值范围,最小值
max数据端点取值范围,最大值
is_read布尔值,数据端点是否可读
is_write布尔值,数据端点是否可写
default_valuestring, 数据端点默认值
source数据来源类型,见产品附录6
expressionstring, 数据来源为计算类型时,数据端点表达式, 假如要引用其他数据端点:@index@ + 1, 加入要引用所属产品拓展属性则: #property# + 2
permission_list

可更新该数据端点的权限集合, 1:企业成员,2:企业授权,3:用户, 4:设备, 5:平台, 其中设备上报类型数据端点只能是4, 计算型数据端点只能是5,应用型数据端点可任意

ui_visibleui页面是否显示, 布尔值
field_name字段名称
is_system是否为系统数据端点

16.创建数据转发规则

企业管理员为企业下的某个产品添加一个新的数据转发规则,包括转发类型、转发外部URL地址、外部URL地址验证令牌、关注的数据包类型列表,转发规则主要用户收集产品设备产生的相关数据。

Request

URL

POST /v2/product/{product_id}/dds
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

{
    "data_type": [
        "1",
        "2",
        "3",
        "4",
        "5"
    ],
    "destination": {
        "type": "转发类型",
        "url": "转发URL地址",
        "token": "URL地址验证令牌"
    }
}
字段是否必须描述
type转发类型,见产品附录3
url转发外部URL地址
token外部URL地址验证令牌
data_type关注的数据包类型列表,见产品附录4

Response

Header

HTTP/1.1 200 OK

Content

{
    "id": "转发规则ID",
    "data_type": [
        "1",
        "2",
        "3",
        "4",
        "5"
    ],
    "destination": {
        "type": "转发类型",
        "url": "转发URL地址",
        "token": "URL地址验证令牌"
    }
}
字段是否必须描述
id转发规则ID
type转发类型,见产品附录3
url转发外部URL地址
token外部URL地址验证令牌
data_type关注的数据包类型列表,见产品附录4

17.获取数据转发规则列表

企业管理员根据产品标识product_id url中 获取属于该产品的所有转发规则。

Request

URL

GET /v2/product/{product_id}/dds_list
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
    "count": "返回数量",
    "list": {
        "id": "转发规则ID",
  "status":"状态, 1:启用, 2:禁用",
"data_type": [ "1", "2", "3", "4", "5" ], "destination": { "type": "转发类型", "url": "转发URL地址", "token": "URL地址验证令牌" } } }
字段是否必须描述
count返回数量
id转发规则ID
type转发类型,见产品附录3
url转发外部URL地址
token外部URL地址验证令牌
data_type

关注的数据包类型列表,见产品产品附录4

status启用状态

18.修改数据转发规则

企业管理员根据产品标识product_id以及dispatch_id url中修改数据转发规则,可修改的有转发类型、转发外部URL地址、外部URL地址验证令牌以及关注的数据包类型列表。

Request

URL

PUT /v2/product/{product_id}/dds/{dispatch_id}
字段是否必须描述
product_id产品ID,32个字符
dispatch_id数据转发规则ID

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

{
 "data_type": [ "1", "2", "3", "4", "5" ], "destination": { "type": "转发类型", "url": "转发URL地址", "token": "URL地址验证令牌" },
    "status":"状态, 1:启用, 2:禁用"
 }


字段是否必须描述
type转发类型,见产品附录3
url转发外部URL地址
token外部URL地址验证令牌
data_type关注的数据包类型列表,见产品产品附录4
status启用状态

Response

Header

HTTP/1.1 200 OK

Content

{
    "id": "转发规则ID",
 "status":"状态, 1:启用, 2:禁用",
"data_type": [ "1", "2", "3", "4", "5" ], "destination": { "type": "转发类型", "url": "转发URL地址", "token": "URL地址验证令牌" } }
字段是否必须描述
id转发规则ID
type转发类型,见产品附录3
url转发外部URL地址
token外部URL地址验证令牌
data_type关注的数据包类型列表,见产品产品附录4
status启用状态

19.删除数据转发规则

企业管理员根据产品标识product_id以及dispatch_id url中删除数据转发规则。

Request

URL

DELETE /v2/product/{product_id}/dds/{dispatch_id}
字段是否必须描述
product_id产品ID,32个字符
dispatch_id数据转发规则ID

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

20.添加设备

企业管理员指定产品标识product_id url中 为在某个产品下添加一个设备。

Request

URL

POST /v2/product/{product_id}/device
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "mac":"MAC地址",
    "sn":"序列号",
    "name":"设备别名",
    "domain":"自定义域",
    "tags":["tag1","tag2"]
}
字段是否必须描述
macMAC地址(在一个产品下必须唯一)
sn序列号
name设备别名
domain自定义域,一般用于将设备分成不同的范围,以便于管理与查找
tags设备标签

Response

Header

HTTP/1.1 200 OK

Content

{
    "id": "设备ID",
    "mac": "设备MAC地址"
}

21.导入设备

企业管理员指定产品标识product_id url中 为在某个产品 批量导入设备,如果导入的设备已经存在,则忽略。

Request

URL

POST /v2/product/{product_id}/device_batch
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

[
    "MAC地址1",
    "MAC地址2"
]

Response

Header

HTTP/1.1 200 OK

Content

{
    "devices": [
        {
            "id": "设备ID",
            "mac": "设备MAC"
        },
        {
            "id": "设备ID",
            "mac": "设备MAC"
        }
    ]
}

22.获取设备信息

企业管理员根据指定产品标识product_id以及设备标识device_id url中 获取单个设备详细信息。

Request

URL

GET /v2/product/{product_id}/device/{device_id}

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
    "id": "设备ID",
    "mac": "MAC地址",
    "name": "设备名称",
    "is_active": "是否激活",
    "active_date": "激活时间",
    "is_online": "是否在线",
    "last_login": "最近登录时间",
    "last_login_ip": "最近登录IP",
    "mcu_mod": "MCU型号",
    "mcu_version": "MCU版本号",
    "firmware_mod": "固件型号",
    "firmware_version": "固件版本号",
    "corp_id": "企业ID",
    "product_id": "产品ID",
    "region_id": "所在区域ID",
    "sn":"序列号",
    "create_time": "创建时间",
    "creator_id": "创建者ID",
    "creator_type": "创建者类型",
    "tags":["tag1","tag2"],
    "dealer_scope":"经销商可访问的范围",
    "heavy_buyer":"大客户Id",
    "last_reset":"最后激活时间"
}
字段是否必须描述
id设备ID,32位数字整形
mac设备MAC地址,12位十六进制字符
name设备名称
is_active是否已激活,布尔值,true或false
active_date激活时间,例:2014-10-09T08:15:40.843Z
is_online是否在线,布尔值,true或false
last_login最近登录时间
last_login_ip最近登录IP
mcu_modMCU型号,20个字符
mcu_versionMCU软件版本号,32位数字整形
firmware_mod固件型号,20个字符
firmware_version固件版本号,32位数字整形
corp_id企业ID
product_id产品ID
region_id所在区域ID
sn设备序列号
domain
create_time设备创建时间
creator_id设备创建者ID
creator_type设备创建者类型,见设备附录2
tags设备标签
dealer_scope经销商可访问的范围
heavy_buyer大客户Id,
last_reset最后激活时间,例:2014-10-09T08:15:40.843Z
online_count在线总时长

23.修改设备信息

企业管理员根据指定产品标识product_id以及设备标识device_id url中 修改设备名称。

Request

URL

PUT /v2/product/{product_id}/device/{device_id}
字段是否必须描述
product_id产品ID,32个字符
device_id设备ID

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "name": "设备名称",
    "sn": "设备序列号",
    "domain": "域",
    "tags": [
        "tag1",
        "tag2"
    ],
    "groups": [
        "group1",
        "group2"
    ],
    "soft_init_date": "设备软重置的时间",
    "is_active": "true"
}

字段是否必须描述
name设备名称
sn设备序列号
domain
tags设备标签
groups设备分组
soft_init_date设备软重置的时间,例:2016-06-02T15:04:02.858Z
is_active设备激活状态

Response

Header

HTTP/1.1 200 OK

Content

{
    "id": "设备ID",
    "mac": "MAC地址",
    "name": "设备名称",
    "is_active": "是否激活",
    "active_date": "激活时间",
    "is_online": "是否在线",
    "last_login": "最近登录时间",
    "last_login_ip": "最近登录IP",
    "mcu_mod": "MCU型号",
    "mcu_version": "MCU版本号",
    "firmware_mod": "固件型号",
    "firmware_version": "固件版本号",
    "corp_id": "企业ID",
    "product_id": "产品ID",
    "region_id": "所在区域ID",
    "sn":"设备序列号",
    "domain":"域",
    "create_time": "创建时间",
    "creator_id": "创建者ID",
    "creator_type": "创建者类型",
    "tags":["tag1","tag2"],
    "dealer_scope":"经销商可访问的范围",
    "heavy_buyer":"大客户Id",
    "groups":["group1","group2"]
}
字段是否必须描述
id设备ID,32位数字整形
mac设备MAC地址,12位十六进制字符
name设备名称
is_active是否已激活,布尔值,true或false
active_date激活时间,例:2014-10-09T08:15:40.843Z
is_online是否在线,布尔值,true或false
last_login最近登录时间
last_login_ip最近登录IP
mcu_modMCU型号,20个字符
mcu_versionMCU软件版本号,32位数字整形
firmware_mod固件型号,20个字符
firmware_version固件版本号,32位数字整形
corp_id企业ID
product_id产品ID
region_id所在区域ID
sn设备序列号
domain
create_time设备创建时间
creator_id设备创建者ID
creator_type设备创建者类型,见设备附录2
tags设备标签
dealer_scope经销商可访问的范围
heavy_buyer大客户Id
groups所属分组列表

24.查询设备列表

企业管理员根据指定产品标识product_id url中 调用本接口获取设备列表,通过自定义查询条件获取设备列表。扩展属性可以作为过滤显示字段,不能作为查询字段。

Request

URL

POST /v2/product/{product_id}/devices
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "offset": "请求列表的偏移量",
    "limit": "请求数量",
    "filter": [
        "字段A",
        "字段B"
    ],
    "query": {
        "filed1": {
            "$like": "字段值"
        },
        "filed3": {
            "$lt": "字段值"
        }
    },
    "order": {
        "filed1": "desc",
        "filed2": "asc"
    }
}
字段是否必须描述
offset从某个偏移量开始请求,默认为0
limit请求的条目数量,默认为10
order可以指定通过设备默认的某个字段排序,desc降序,asc升序
filter字段过滤,集合类型,可以指定返回结果列表的字段,可以
包含扩展属性字段
query查询条件,可以根据不同字段加上不同的比较指令来查询,查
询条件字段包含设备所有默认字段,不支持扩展属性字段,支
持比较指令包含如下:
$in:包含于该列表任意一个值
$lt:小于该字段值
$lte:小于或等于字段值
$gt:大于该字段值
$gte:大于或等于该字段值
$like:模糊匹配该字段值

Response

Header

HTTP/1.1 200 OK

Content

{
    "count": "总数量",
    "list": [
        {
            "id": "设备ID",
            "mac": "MAC地址",
            "name": "设备名称",
            "is_active": "是否激活",
            "active_date": "激活时间",
            "is_online": "是否在线",
            "last_login": "最近登录时间",
            "last_login_ip": "最近登录IP",
            "mcu_mod": "MCU型号",
            "mcu_version": "MCU版本号",
            "firmware_mod": "固件型号",
            "firmware": "固件版本号",
            "product_id": "产品ID",
            "region_id": "所在区域ID",
            "sn":"设备序列号",
            "domain":"域",
            "create_time": "创建时间",
            "creator_id": "创建者ID",
            "creator_type": "创建者类型",
            "tags":["tag1","tag2"],
            "dealer_scope":"经销商可访问的范围",
            "heavy_buyer":"大客户Id",
            "groups":["group1","group2"],
            "last_reset":"最后激活时间",
            "online_count":"在线总时长",
            "gateway_id":"网关ID"
        }
    ]
}
字段是否必须描述
count总数量
list设备列表
id设备ID,32位数字整形
mac设备MAC地址,12位十六进制字符
name设备名称
is_active是否已激活,布尔值,true或false
active_date激活时间,例:2014-10-09T08:15:40.843Z
is_online是否在线
last_login最近登录时间
last_login_ip最近登录IP
mcu_modMCU型号,20个字符
mcu_versionMCU软件版本号,32位数字整形
firmware_mod固件型号,20个字符
firmware_version固件版本号,32位数字整形
product_id产品ID
region_id所在区域ID
sn设备序列号
domain
create_time创建时间
creator_id创建者ID
creator_type创建者类型
tags设备标签
dealer_scope经销商可访问的范围
heavy_buyer大客户Id
groups所属分组列表
last_reset最后激活时间,例:2014-10-09T08:15:40.843Z
online_count在线总时长
gateway_id设备的网关ID

25.删除设备

企业管理员根据指定产品标识product_id以及设备标识device_id url中 彻底删除设备所有信息,已激活的设备不可删除。

Request

URL

DELETE /v2/product/{product_id}/device/{device_id}
字段是否必须描述
product_id产品ID,32个字符
device_id设备ID

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

26.设置设备扩展属性

企业管理员根据指定产品标识product_id以及设备标识device_id url中 设置设备的扩展属性,扩展属性以Key-Value方式设置储存,扩展属性限制为10个。注意:扩展属性字段名不得包含小数点、空字符,不能以美元符号($)开头。

Request

URL

POST /v2/product/{product_id}/device/{device_id}/property
字段是否必须描述
product_id产品ID,32个字符
device_id设备ID

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "{key}": "{value}",
    "{key}": "{value}"
}
字段是否必须描述
{key}扩展属性key值
{value}扩展属性value值

Response

Header

HTTP/1.1 200 OK

Content

{
    "{key}": "{value}",
    "{key}": "{value}"
}
字段是否必须描述
{key}扩展属性key值
{value}扩展属性value值

27.修改设备扩展属性

企业管理员根据指定产品标识product_id以及设备标识device_id url中 修改设备扩展属性值。

Request

URL

PUT /v2/product/{product_id}/device/{device_id}/property
字段是否必须描述
product_id产品ID,32个字符
device_id设备ID

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "{key}": "{value}",
    "{key}": "{value}"
}
字段是否必须描述
{key}扩展属性key值
{value}扩展属性value值

Response

Header

HTTP/1.1 200 OK

Content

28.获取设备扩展属性列表

企业管理员根据指定产品标识product_id以及设备标识device_id url中 获取设备扩展属性列表。

Request

URL

GET /v2/product/{product_id}/device/{device_id}/property
字段是否必须描述
product_id产品ID,32个字符
device_id设备ID

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
    "{key}": "{value}",
    "{key}": "{value}"
}
字段是否必须描述
{key}扩展属性key值
{value}扩展属性value值

29.获取设备单个扩展属性

企业管理员根据指定产品标识product_id、设备标识device_id以及属性key url中 获取设备某个扩展属性。

Request

URL

GET /v2/product/{product_id}/device/{device_id}/property/{key}
字段是否必须描述
product_id产品ID,32个字符
device_id设备ID
key扩展属性key

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
    "{key}": "{value}"
}
字段是否必须描述
{key}扩展属性key值
{value}扩展属性value值

30.删除设备扩展属性

企业管理员根据指定产品标识product_id、设备标识device_id以及属性key url中 删除某个设备扩展属性。

Request

URL

DELETE /v2/product/{product_id}/device/{device_id}/property/{key}
字段是否必须描述
product_id产品ID,32个字符
device_id设备ID
key扩展属性key

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

31. 设备上下线日志查询

用于查询设备的上下线历史日志,默认情况下,返回的列表按时间倒序。

Request

URL

POST /v2/device_session_log

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "offset": "请求的列表偏移量",
    "limit": " 请求的列表数量",
    "query": {
        "id": "标识ID",
        "device_id": "设备ID",
        "product_id": "产品ID",
        "ip": "ip地址",
        "cm_id": "CM服务器ID",
        "status": "在线状态",
        "code": "引起状态变化的原因"
    },
    "order": {
        "id": "desc",
        "device_id": "asc",
        ...
    }

}
字段是否必须描述
offset请求列表的偏移量,默认为0
limit请求列表的数量,默认为10
query查询条件,可以通过字段查询结果,不指定这返回所有结果
order排序条件,可以通过任意字段排序。

Response

Header

HTTP/1.1 200 OK

Content

{
    "count": "总数量",
    "list": [
        {
            "id": "标识ID",
            "device_id": "设备ID",
            "product_id": "产品ID",
            "ip": "ip地址",
            "cm_id": "CM服务器ID",
            "status": "在线状态",
            "create_time": "创建时间",
            "code": "引起状态变化的原因"
        }
    ]
}
字段是否必须描述
id日志的标识ID
device_id设备ID
product_id产品ID
ipip地址
cm_id设备所在服务器ID
status在线状态,0:离线,1:在线
create_time日志创建时间,例:2014-10-09T08:15:40.843Z
code引起状态变化的原因,见附录

32.固件版本设备统计

统计出产品中每个固件版本对应的设备数量.

Request

URL

GET /v2/product/{product_id}/firmware/statistics
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
    "{firmware_version}": "{number}",
    "{firmware_version}": "{number}"
}
字段是否必须描述
{firmware_version}固件版本号
{number}固件版本号对应的设备数

33.获取设备地理信息

  • 获取设备的地理信息

Request

URL

GET /v2/product/{product_id}/device/{device_id}/geography

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
    "device_id": "设备ID",
    "lon" : 经度,
    "lat" : 纬度,
    "update_time" : "最后一次更新时间",
    "country":"设备所在国家",
    "province":"设备所在省",
    "city":"设备所在市",
    "district":"设备所在区"
}
字段是否必须描述
device_id设备ID
lon设备经度;如果没有信息,返回空
lat设备纬度;如果没有信息,返回空
update_time更新时间,例:2014-10-09T08:15:40.843Z;如果没有信息,返回空
country设备所在国家
province设备所在省
city设备所在市
district设备所在区

34.设置设备地理信息

  • 手动设置一个设备的地理信息

Request

URL

PUT /v2/product/{product_id}/device/{device_id}/geography

Header

Content-Type:"application/json"
Access-Token:"企业调用凭证/用户调用凭证"

Content

{
    "lon" : 经度,
    "lat" : 纬度,
    "country":"设备所在国家",
    "province":"设备所在省",
    "city":"设备所在市",
    "district":"设备所在区"
}
字段是否必须描述
lon设备经度;
lat设备纬度;
country设备所在国家
province设备所在省
city设备所在市
district设备所在区

Response

Header

HTTP/1.1 200 OK

Content

35.通过地理信息查询设备

  • 通过地理信息查询设备

Request

URL

POST /v2/product/{product_id}/devices/geography

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

当type = polygon时,

{
    "type" : "polygon",
    "coord" : [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0  ] ] ],
    "limit" : 查询返回量,
    "query" : {
        "field": {
            "$lt": "字段值"
        }
    }
}

当type = spherical,
{
    "type":"spherical",
    "spherical" : true,
    "coord" : [ 经度, 纬度 ],
    "max_dist" : "最远距离",
    "min_dist" : "最近距离",
    "limit" : 查询返回量,
    "query" : {
        "field": {
            "$lt": "字段值"
        }
    }
}
字段是否必须描述
type支持spherical(圆形区域),polygon(坐标点集合),默认为spherical
spherical以圆形方式查找,暂时只支持使用圆形方式查找;
coord查找圆心的经度和维度;
max_dist查找范围离圆心的最大值,距离为米;
min_dist查找范围离圆心的最小值,距离为米,默认为0;min_dist必须小于max_dist
如果min_distmax_dist都有设置,那么会查找一个圆环区域的设备;
limit查询返回量,默认100个
query查询条件,可以根据不同字段加上不同的比较指令来查询,查
询条件字段包含设备所有默认字段,不支持扩展属性字段,支
持比较指令包含如下:
$in:包含于该列表任意一个值
$lt:小于该字段值
$lte:小于或等于字段值
$gt:大于该字段值
$gte:大于或等于该字段值
$like:模糊匹配该字段值

Response

Header

HTTP/1.1 200 OK

Content

{
    "count" : 查找到的设备个数,
    "devices" : [
        {
            "device_id": "设备ID",
            "lon" : 经度,
            "lat" : 纬度,
            "update_time" : "最后一次更新时间",
            "country":"设备所在国家",
            "province":"设备所在省",
            "city":"设备所在市",
            "district":"设备所在区"
        },
    ]
}
字段是否必须描述
count查找到的设备个数
devices返回的设备列表,如果count == 0,则为空
device_id设备ID
lon设备经度;
lat设备纬度;
update_time更新时间,例:2014-10-09T08:15:40.843Z;如果没有信息,返回空
country设备所在国家
province设备所在省
city设备所在市
district设备所在区

36. 设备上下线日志下载

用于下载设备的上下线历史日志,默认情况下,返回的列表按时间倒序,下载格式为cvs

Request

URL

GET /v2/device_session_log/download?body=xxxx
字段是否必须描述
body以下参数的的base64编码值
token调用凭证
offset请求列表的偏移量,默认为0
limit请求列表的数量,默认为10
query查询条件,可以通过字段查询结果,不指定这返回所有结果
order排序条件,可以通过任意字段排序。
{
    "token":"调用凭证",
    "offset": "请求的列表偏移量",
    "limit": " 请求的列表数量",
    "query": {
        "id": "标识ID",
        "device_id": "设备ID",
        "product_id": "产品ID",
        "ip": "ip地址",
        "cm_id": "CM服务器ID",
        "status": "在线状态",
        "code": "引起状态变化的原因"
    },
    "order": {
        "id": "desc",
        "device_id": "asc",
        ...
    }
}

Header

Content-Type:"application/cvs"

Content

Response

Header

HTTP/1.1 200 OK

Content

cvs文件

37.设备列表导出

企业管理员根据指定产品标识product_id url中 调用本接口导出设备列表,通过自定义查询条件获取设备列表。扩展属性可以作为过滤显示字段,不能作为查询字段

Request

URL

GET /v2/product/{product_id}/devices/download?body=xxxx
字段是否必须描述
product_id产品ID,32个字符
bodybase64请求参数和token得到值

body包含内容:

{
    "token" : "调用凭证",
    "offset": "请求列表的偏移量",
    "limit": "请求数量",
    "filter": [
        "字段A",
        "字段B"
    ],
    "query": {
        "filed1": {
            "$like": "字段值"
        },
        "filed3": {
            "$lt": "字段值"
        }
    },
    "order": {
        "filed1": "desc",
        "filed2": "asc"
    }
}
字段是否必须描述
offset从某个偏移量开始请求,默认为0
limit请求的条目数量,默认为10
order可以指定通过设备默认的某个字段排序,desc降序,asc升序
filter字段过滤,集合类型,可以指定返回结果列表的字段,可以
包含扩展属性字段,包含不限于id,name,mac,is_active,active_date
query查询条件,可以根据不同字段加上不同的比较指令来查询,查
询条件字段包含设备所有默认字段,不支持扩展属性字段,支
持比较指令包含如下:
$in:包含于该列表任意一个值
$lt:小于该字段值
$lte:小于或等于字段值
$gt:大于该字段值
$gte:大于或等于该字段值
$like:模糊匹配该字段值
其中"is_online":{“$in”:[true或者false]}必须指定,
即是"query":{“is_online”:{“$in”:[true或者false]}}必备

Header

Content-Type:"application/json"

Response

Header

HTTP/1.1 200 OK

Content

cvs文件

38. 获取设备的订阅信息

获取订阅该设备的用户详细列表。

Request

URL

GET /v2/product/{product_id}/device/{device_id}/subscribes

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
    "list": [
        {
            "user_id": "用户ID",
            "role": "角色权限",
            "from_id":"来源用户ID"
            "create_date": "订阅时间,例2015-10-09T08:15:40.843Z"
        }
    ]
}

39.通过csv批量导入设备

企业管理员指定产品标识product_id url中 为在某个产品 批量导入设备, 导入时可以设置属性, 包括不限于sn/name, 如果导入的设备MAC已经存在(如果导入信息包括sn,sn也不允许重复), 则导入失败。

Request

URL

POST /v2/product/{product_id}/device_import_batch
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

[
    {
       "mac":"mac地址",
       "sn":"序列号",
       "name":"名字"
    },
    {
       "mac":"mac地址",
       "sn":"序列号",
       "name":"名字"
    }
]
字段是否必须描述
mac设备mac地址
sn设备序列号
name设备名称

Response

Header

HTTP/1.1 200 OK

Content

{
    "import_record_id":"导入记录id",
    "devices": [
        {
            "id": "设备ID",
            "mac": "设备MAC"
        },
        {
            "id": "设备ID",
            "mac": "设备MAC"
        }
    ]
}

导入设备的MAC或者SN重复时:

Header

HTTP/1.1 400 Bad Request

Content

{
"error" : {
        "code" : 4001021,
        "msg" : "[duplicate_mac1,duplicate_mac2,...],[duplicate_sn1,duplicate_sn2,...]"
        }
}
字段是否必须描述
import_record_id导入记录id
id设备ID
mac设备mac地址

40.查询导入设备历史纪录

企业管理员指定产品标识product_id url中 为在某个产品 , 查询该产品下产品导入记录

Request

URL

POST /v2/product/{product_id}/device_import/records
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "offset": "请求列表的偏移量",
    "limit": "请求数量",
    "filter": [
        "字段A",
        "字段B"
    ],
    "query": {
        "filed1": {
            "$like": "字段值"
        },
        "filed3": {
            "$lt": "字段值"
        }
    },
    "order": {
        "filed1": "desc",
        "filed2": "asc"
    }
}
字段是否必须描述
offset从某个偏移量开始请求,默认为0
limit请求的条目数量,默认为10
order可以指定通过设备默认的某个字段排序,desc降序,asc升序
filter字段过滤,集合类型,可以指定返回结果列表的字段,可以
包含扩展属性字段
query查询条件,可以根据不同字段加上不同的比较指令来查询,查
询条件字段包含设备所有默认字段,不支持扩展属性字段,支
持比较指令包含如下:
$in:包含于该列表任意一个值
$lt:小于该字段值
$lte:小于或等于字段值
$gt:大于该字段值
$gte:大于或等于该字段值
$like:模糊匹配该字段值

Response

Header

HTTP/1.1 200 OK

Content

{
    "count": "总数量",
    "list": [
        {
            "_id":"记录id",
            "auth_number":"授权数量",
            "auth_member":"授权人成员账号",
            "create_time":"授权时间",
            "product_id":"产品id"
        }
    ]
}
字段是否必须描述
id记录ID
auth_number授权数量
auth_member授权人成员账号
create_time授权时间
product_id产品id

41.查询导入设备记录详情

企业管理员指定产品标识product_id url中 为在某个产品, 查询该产品下产品某个导入记录

Request

URL

POST /v2/product/{product_id}/device_import/{import_id}
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "limit":"请求数量",
    "offset":"请求开始位置"
}

Response

Header

HTTP/1.1 200 OK

Content

{
    "id":"记录id",
    "auth_number":"授权数量",
    "auth_member":"授权人成员账号",
    "create_time":"授权时间",
    "product_id":"产品id",
    "attribute":[
        {
            "mac":"设备地址",
            "name":"设备名称",
            "sn":"设备序列号",
            "device_id":"设备ID"
        }
    ]
}
字段是否必须描述
id记录ID
auth_number授权数量
auth_member授权人成员账号
create_time授权时间
product_id产品id
attribute设备导入时的参数
mac设备地址
device_id设备ID
sn设备名称
name设备序列号

42. 批量导出设备二维码

批量导出设备二维码,导出后接口以文件的格式返回。

Request

URL

GET /v2/product/{product_id}/export/device_qrcode?query={query}
字段描述
query查询指令,内容为JSON,见如下说明,经过BASE64编码后赋值到本字段

JSON格式说明:

{
    "offset": "请求列表的偏移量",
    "limit": "请求数量",
    "query": {
        "filed1": {
            "$like": "字段值"
        },
        "filed3": {
            "$lt": "字段值"
        }
    },
    "custom_field": [
        "id",
        "mac",
        "pid",
        "sn"
    ],
    "custom_property": {
        "{key}": "{value}"
    },
    "format":{
        "prefix":"前缀字符串",
        "suffix":"后缀字符串",
        "encode":"对二维码数据进行编码,不包括前缀后缀"
    },
    "access_token":"调用凭证"
}
字段是否必须说明
custom_field二维码字段,为设备字段
custom_property自定义附加字段
format.prefix在生成的二维码数据加前缀字符串
format.suffix在生成的二维码数据加后缀字符串
encode对生成的二维码数据进行编码,可选值是:source,base64

Header

默认

Content

Response

Header

HTTP/1.1 200 OK
Content-Type:application/csv;charset=utf-8
Content-Disposition:inline; {filename}.csv

Content

CSV文件格式,返回CSV文件列名:id,mac,qrcode

43. 刷新设备二维码

Request

URL

POST /v2/product/{product_id}/device/{device_id}/refresh_qrkey

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

44. 通过设备导入记录批量导出二维码

Request

URL

GET /v2/product/{product_id}/export/qrcode_by_import_record?query={query}
字段描述
query查询指令,内容为JSON,见如下说明,经过BASE64编码后赋值到本字段

JSON格式说明:

{
    "record_id":"导入设备记录ID",
    "custom_field": [
        "id",
        "mac",
        "pid",
        "sn"
    ],
    "custom_property": {
        "{key}": "{value}"
    },
    "format":{
        "prefix":"前缀字符串",
        "suffix":"后缀字符串",
        "encode":"对二维码数据进行编码,不包括前缀后缀"
    },
    "access_token":"调用凭证"
}
字段是否必须说明
custom_field二维码字段,为设备字段
custom_property自定义附加字段
format.prefix在生成的二维码数据加前缀字符串
format.suffix在生成的二维码数据加后缀字符串
encode对生成的二维码数据进行编码,可选值是:source,base64

Header

默认

Content

Response

Header

HTTP/1.1 200 OK

Content

CSV文件格式,返回CSV文件列名:id,mac,qrcode

45.获得固件版本列表

企业管理员根据产品标识product_id url中查询产品的所有固件版本。

Request

URL

POST /v2/product/{product_id}/firmwares
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

{
    "offset":"请求偏移量",
    "limit":"每页请求量",
    "type":"请求固件版本列表"
}
字段是否必须描述
offset请求偏移量, 默认值0
limit每页请求量, 默认值10
type不传时,为全部类型

Respones

Header

HTTP/1.1 200 OK

Content

{
    "count":"返回数量",
    "list":[
                {
                    "id": "固件版本ID",
                    "mod": "固件型号",
                    "version": "固件版本号",
                    "file_url": "固件文件地址",
                    "file_md5": "固件文件MD5值",
                    "file_size": "固件文件大小",
                    "description": "描述",
                    "release_date": "固件发布日期",
                    "create_date": "固件创建日期",
                    "is_release": "是否发布",
                    "type" : "固件类型",
                    "identify":"用来定位多MCU或多子设备的情况",
"from_version_by_task":"是否已经被升级任务作为启始版本",
"used_by_running_task":"是否已经被处于升级中的升级任务使用, 可以用于标识改固件不能被编辑" } ] }
字段是否必须描述
count总数
id固件ID
mod固件型号,20个字符以内
version固件版本号,32位整形
file_url固件文件地址,250个字符以内
description描述,250字符以内
release_date固件发布日期,例:2015-10-09T08 : 15 : 40.843Z
create_date固件创建日期,例:2015-10-09T08 : 15 : 40.843Z
is_release是否发布,布尔值,true或false
file_md5固件文件Md5
file_size固件文件大小
description描述,250字符以内
release_date固件发布日期,例:2015-10-09T08 : 15 : 40.843Z
create_date固件创建日期,例:2015-10-09T08 : 15 : 40.843Z
is_release是否发布,布尔值,true或false
type固件类型,新增,见附件设备固件类型, 默认为wifi
identify用来定位多MCU或多子设备的情况, 数字, version/type/identify联合唯一, 默认为0
from_version_by_task是否已经被升级任务作为启始版本
used_by_running_task是否已经被处于升级中的升级任务使用, 可以用于标识改固件不能被编辑

46.获取固件版本

企业管理员获取固件的详细信息

Request

URL

GET /v2/product/{product_id}/firmware/{firmware_id}
字段是否必须描述
product_id产品ID,32个字符
firmware_id固件版本ID

Header

Content-Type:application/json
Access-Token:"调用凭证"

Content

Response

Header

HTTP/1.1 200 OK

Content

{
    "id": "固件版本ID",
    "mod": "固件型号",
    "version": "固件版本号",
    "file_url": "固件文件地址",
    "file_md5": "固件文件MD5值",
    "file_size": "固件文件大小",
    "description": "描述",
    "release_date": "固件发布日期",
    "create_date": "固件创建日期",
    "is_release": "是否发布",
    "type" : "固件类型",
    "identify":"用来定位多MCU或多子设备的情况"
}
字段是否必须描述
id固件ID
mod固件型号,20个字符以内
version固件版本号,32位整形
file_url固件文件地址,250个字符以内
file_md5固件文件MD5值
file_size固件文件大小
description描述,250字符以内
release_date固件发布日期,例:2015-10-09T08 : 15 : 40.843Z
create_date固件创建日期,例:2015-10-09T08 : 15 : 40.843Z
is_release是否发布,布尔值,true或false
type固件类型,新增,见附件设备固件类型, 默认为wifi
identify用来定位多MCU或多子设备的情况, 数字, version/type/identify联合唯一, 默认为0

47.获取产品扩展属性

企业管理员根据指定产品标识product_id设置产品的扩展属性,扩展属性以Key-Value方式设置储存,扩展属性限制为10个。注意:扩展属性字段名不得包含小数点、空字符,不能以美元符号($)开头。

注意:设置产品的扩展属性,使用设置产品个性化设置接口实现

Request

URL

G /v2/product/{product_id}/property
字段是否必须描述
product_id产品ID,32个字符
device_id设备ID

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content


Response

Header

HTTP/1.1 200 OK

Content

{
    "{key}": "{value}",
    "{key}": "{value}"
}
字段是否必须描述
{key}扩展属性key值
{value}扩展属性value值

48.设置设备数据端点值指令

设置设备数据端点值指令, 提供可回写至设备端, 亦可不回写至设备端。

Request

URL

POST /v2/device/command/{device_id}/datapoint
字段是否必须描述
device_id设备ID

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
  "source":"数据来源类型"
  "write_back":"true",
  "command":[
    {
      "index":0,
      "value":true
    },
    {
      "index":1,
      "value":12
    }
  ],
  "sync_expire":"指令过期时间"
}
字段是否必须描述
source需要设置数据端点的来源类型, 见产品附录6
command需要设置的数据端点列表
index数据端点索引
value数据端点值
write_back是否回写至设备端, 默认为false
sync_expire 指令过期时间, 只针对需要回写的指令, 默认为当前时间, 例:2014-10-09T08:15:40.843Z

Response

Header

HTTP/1.1 200 OK

Content

49.获取设备数据端点值同步状态

获取设备数据端点值的同步状态。

Request

URL

POST /v2/device/command/{device_id}/datapoint/status
字段是否必须描述
device_id设备ID

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "filter": [
        "字段A",
        "字段B"
    ]
}
字段是否必须描述
filter字段过滤,集合类型,可以指定返回结果的字段, target中的内容由指定的数据端点下标决定

Response

Header

HTTP/1.1 200 OK

Content

{
    "current":{
        "device_id":"设备id",
        "cm_id":"cm服务器id",
        "ip":"设备所在Ip",
        "online":"是否在线",
        "online_count":"在线时长",
        "last_login":"最近一次上线时间",
        "last_logout":"最近一次下线时间",
        "last_update":"最近一次上报数据时间",
        "1":"数据端点1的值"
    },
    "target_list":[
        {
            "index":"数据端点下标",
            "target":"目标值",
            "status":"同步状态"
        },
        {
            "index":"数据端点下标",
            "target":"目标值",
            "status":"同步状态"
        }
    ]
}
字段是否必须描述
current虚拟设备当前值
current.device_id虚拟设备id
target_list虚拟设备目标值
target_list.index数据端点索引
target_list.target数据端点目标值
target_list.status同步状态

50. 生成单个设备二维码

Request

URL

POST /v2/product/{product_id}/device/{device_id}/qrcode

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "authority": "读写权限, R:只读;W:只写;RW:可读写,默认是RW",
    "custom_field": [
        "id",
        "mac",
        "pid",
        "sn"
    ],
    "custom_property": {
        "{key}": "{value}"
    },
    "format": {
        "prefix": "前缀字符串",
        "suffix": "后缀字符串",
        "encode": "对二维码数据进行编码,不包括前缀后缀"
    }
}
字段是否必须说明
authority读写权限, R:只读;W:只写;RW:可读写,默认是RW
custom_field二维码字段,为设备字段
custom_property自定义附加字段
format.prefix在生成的二维码数据加前缀字符串
format.suffix在生成的二维码数据加后缀字符串
encode对生成的二维码数据进行编码,可选值是:source,base64

Response

Header

HTTP/1.1 200 OK

Content

{
    "qrcode": "生成的设备二维码"
}

51. 设备聚合接口

设备聚合接口, 用于查询设备列表, 可多个维度进行聚合字段, 目前支持基础字段和数据端点聚合。

Request

URL

POST /v2/product/{product_id}/aggregate/devices

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "offset": "请求列表的偏移量",
    "limit": "请求数量",
    "filter":{
        "device": [
            "id",
            "mac",
            "name",
            "is_active",
            "active_date",
            "mcu_mod",
            "mcu_version",
            "firmware_mod",
            "firmware_version",
            "product_id",
            "region_id",
            "sn",
            "domain",
            "create_time",
            "creator_id",
            "creator_type",
            "tags",
            "dealer_scope",
            "heavy_buyer",
            "groups",
            "last_reset"
        ],
        "vdevice": [
            "cm_id",
            "ip",
            "online_count",
            "last_login",
            "last_logout",
            "last_update",
            "1",
            "2"
        ],
        "online": [
            "is_online",
            "last_login",
            "last_login_ip"
        ],
        "geography": [
            "country",
            "province",
            "city",
            "district",
            "lng",
            "lat"
        ],
        "subscribe": [
            "user_id",
            "nickname",
            "phone",
            "email",
            "role",
            "from_id",
            "create_date"
        ],
        "heavy_buyer": [
            "id",
            "name",
            "industry",
            "location",
            "contacter",
            "contact_way",
            "status",
            "create_time",
            "device_sum",
            "country",
            "province",
            "city"
        ],
        "dealer": [
            "id",
            "name",
            "email",
            "phone",
            "address",
            "status",
            "dealer_code",
            "upper_dealer_code",
            "create_time",
            "country",
            "province",
            "city",
            "region",
            "saled_amount"
        ],
        "snapshot_shuffle": [
            "statistic_rule_id",
            "index",
            "fineness",
            "date_start",
            "date_end",
            "sum",
            "max",
            "min",
            "avg"
        ]
    },
    "query": {
        "$logical": "AND/OR",
        "device": {
            "filed1": {
                "$gt": "字段值",
                "$lt": "字段值"
            },
            "filed2": {
                "$gt": "字段值",
                "$lt": "字段值"
            }
        },
        "vdevice": {
            "filed1": {
                "$gt": "字段值",
                "$lt": "字段值"
            }
        },
        "online": {
            "is_online": {
                "$eq": "字段值"
            }
        },
        "geography":{
            "country":{
                "$like":"中国"
            },
            "province":{
                "$eq":"广东"
            },
            "city":{
                "$like":"广州"
            },
            "district":{
                "$like":"海珠"
            }
        },
        "subscribe":{
            "user_id":{
                "$eq":"用户id"
            },
            "role":{
                "$eq":0
            },
            "from_id":{
                "$eq":推荐者
            },
            "create_date":{
                "$lt":"订阅时间"
            }
        },
        "heavy_buyer":{
            "email": {
                "$in": "字段值",
                "$like": "字段值"
            }
        },
        "dealer":{
            "name":{
                "$like":"广东一级代理",
                "$eq":"广东一级代理"
            }
        },
        "snapshot_shuffle":[
            {
                "index":{
                    "$eq":"数据端点id, 如需查询统计数据index必须传"
                },
                "fineness":{
                    "$eq":"统计粒度, 如需查询统计数据fineness必须传"
                },
                "statistic_rule_id":{
                    "$eq":"快照统计规则id, 如需查询统计数据statistic_rule_id必须传"
                },
                "date":{
                    "$lt":"维度开始时间,如需查询统计数据必须传",
                    "$gt":"维度开始时间,如需查询统计数据必须传"
                }
            },{
                "index":{
                    "$eq":"数据端点id, 如需查询统计数据index必须传"
                },
                "fineness":{
                    "$eq":"统计粒度, 如需查询统计数据fineness必须传"
                },
                "statistic_rule_id":{
                    "$eq":"快照统计规则id, 如需查询统计数据statistic_rule_id必须传"
                },
                "date":{
                    "$lte":"维度开始时间,如需查询统计数据必须传, 改选项只允许$lte和$gte",
                    "$gte":"维度开始时间,如需查询统计数据必须传, 改选项只允许$lte和$gte"
                }
            }
        ]
    },
    "order": {
        "device": {
            "filed1": "desc/asc"
        },
        "vdevice": {
            "filed1": "desc/asc"
        }
    }
}
字段是否必须描述
offset从某个偏移量开始请求,默认为0
limit请求的条目数量,默认为10
order可以指定通过设备默认的某个字段排序, desc降序/asc升序, 目前仅支持一个组vdevice或者device
order.device基础字段排序
order.vdevice基础字段排序,目前不支持
filter字段过滤,集合类型,可以指定返回结果列表的字段
filter.device字段过滤,集合类型,可以指定返回设备基础字段列表的字段
filter.vdevice字段过滤,集合类型,可以指定返回设备数据端点列表的字段
filter.online字段过滤,集合类型, 关于设备在线信息字段
filter.geography字段过滤, 集合类型, 设备地理位置信息字段
filter.subscribe字段过滤, 集合类型, 设备被订阅信息字段
filter.heavy_buyer字段过滤, 集合类型, 设备所属大客户字段
filter.dealer字段过滤, 集合类型, 设备所属经销商字段
filter.snapshot_shuffle字段过滤, 集合类型, 设备统计信息字段, 如需此字段, 则query.snapshot_shuffle必须传输, 统计粒度fineness尽量使用周、月、年, 小时、日会导致传输数据很大
query查询条件,可以根据不同字段加上不同的比较指令来查询
query.$logicalquery存在时, 必须存在$logical。表示所有查询条件之间的关系
query.device_query设备基础字段查询条件
query.online_query设备是否在线查询条件,目前仅有一个is_online查询字段
query.vdevice_query数据端点字段查询条件
query.geography 设备地理位置查询条件, 可传输条件见上
query.subscribe设备订阅信息查询条件, 可传输条件见上
query.heavy_buyer设备所属大客户信息查询条件
query.dealer设备所属经销商信息查询条件
query.snapshot_shuffle此条件不用于搜索设备, 仅用于查询设备的统计信息, 统计粒度fineness尽量使用周、月、年, 小时、日会导致传输数据很大, 如snapshot_shuffle有则文档提到的四个条件必须传输, date选项只允许$lte和$gte

Response

Header

HTTP/1.1 200 OK

Content

{
    "count": "100",
    "list": [
        {
            "device": {
                "id":"设备id",
                "mac":"mac地址",
                "name":"设备名称",
                "is_active":"是否激活",
                "active_date":"激活时间",
                "mcu_mod":"mcu",
                "mcu_version":"mcu版本",
                "firmware_mod":"firmware",
                "firmware_version":"软件版本",
                "product_id":"产品id",
                "region_id":"区域id",
                "sn":"sn码",
                "domain":"区域",
                "create_time":"导入系统时间",
                "creator_id":"创建者",
                "creator_type":"创建方式",
                "tags":"标签",
                "dealer_scope":"所属经销商",
                "heavy_buyer":"所属大客户",
                "groups":"组",
                "last_reset":"最后激活时间"
            },
            "vdevice": {
                "cm_id":"所在cm服务器",
                "ip":"所用ip",
                "online_count":"在线时长",
                "last_login":"最近登录时间",
                "last_logout":"最近登出时间",
                "last_update":"最近更新时间",
                "1": 23,
                "2": 452,
                "3": "中国大地"
            },
            "online":{
                "is_online":"是否在线",
                "last_login":"最近登录时间",
                "last_login_ip":"登录ip"
            },
            "geography":{
                "country":"所在国家",
                "province":"所在省份",
                "city":"所在城市",
                "district":"所在地址",
                "lng":"纬度",
                "lat":"经度"
            },
            "subscribe":{
                "list":[
                    {
                        "user_id":"用户id",
                        "role":"角色",
                        "from_id":"推荐者id",
                        "create_date":"创建时间",
                        "nickname":"昵称",
                        "phone":"手机",
                        "email":"邮箱"
                    }
                ]
            },
            "heavy_buyer":{
                "id":"大客户id",
                "name":"大客户名称",
                "industry":"行业",
                "location":"地址",
                "contacter":"联系人",
                "contact_way":"联系方式",
                "status":"状态",
                "create_time":"创建时间",
                "device_sum":"拥有设备数",
                "country":"所属国家",
                "province":"所属省份",
                "city":"所属城市"
            },
            "dealer":{
                "id":"经销商id",
                "name":"经销商名称",
                "email":"邮箱",
                "phone":"手机",
                "address":"地址",
                "status":"状态",
                "dealer_code":"经销商代码",
                "upper_dealer_code":"上级经销商代码",
                "create_time":"经销商创建时间",
                "country":所属国家"",
                "province":"所属省份",
                "city":"所属城市",
                "region":"区域",
                "saled_amount":"销售数量"
            },
            "snapshot_shuffle":{
                "list":[
                    "statistic_rule_id":"统计规则id",
                    "index":"数据端点下标",
                    "fineness":"统计维度",
                    "date_start":"开始时间",
                    "date_end":"结束时间",
                    "sum":"平均值",
                    "max":"最大值",
                    "min":"最小值",
                    "avg":"平均值"
                ]
            }
        }
    ]
}

查询已删除的设备列表

Request

URL

POST /v2/corp/device_recycle_list
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
    "offset": "请求列表的偏移量",
    "limit": "请求数量",
    "filter": [
        "字段A",
        "字段B"
    ],
    "query": {
        "filed1": {
            "$like": "字段值"
        },
        "filed3": {
            "$lt": "字段值"
        }
    },
    "order": {
        "filed1": "desc",
        "filed2": "asc"
    }
}
字段是否必须描述
offset从某个偏移量开始请求,默认为0
limit请求的条目数量,默认为10
order可以指定通过设备默认的某个字段排序,desc降序,asc升序
filter字段过滤,集合类型,可以指定返回结果列表的字段,可以
包含扩展属性字段
query查询条件,可以根据不同字段加上不同的比较指令来查询,查
询条件字段包含设备所有默认字段,不支持扩展属性字段,支
持比较指令包含如下:
$in:包含于该列表任意一个值
$lt:小于该字段值
$lte:小于或等于字段值
$gt:大于该字段值
$gte:大于或等于该字段值
$like:模糊匹配该字段值

Response

Header

HTTP/1.1 200 OK

Content

{
    "count": "总数量",
    "list": [
        {
            "id": "设备ID",
            "mac": "MAC地址",
            "name": "设备名称",
            "is_active": "是否激活",
            "active_date": "激活时间",
            "last_login": "最近登录时间",
            "last_login_ip": "最近登录IP",
            "mcu_mod": "MCU型号",
            "mcu_version": "MCU版本号",
            "firmware_mod": "固件型号",
            "firmware": "固件版本号",
            "product_id": "产品ID",
            "region_id": "所在区域ID",
            "sn":"设备序列号",
            "domain":"域",
            "create_time": "创建时间",
            "creator_id": "创建者ID",
            "creator_type": "创建者类型",
            "tags":["tag1","tag2"],
            "dealer_scope":"经销商可访问的范围",
            "heavy_buyer":"大客户Id",
            "groups":["group1","group2"]
        }
    ]
}
字段是否必须描述
count总数量
list设备列表
id设备ID,32位数字整形
mac设备MAC地址,12位十六进制字符
name设备名称
is_active是否已激活,布尔值,true或false
active_date激活时间,例:2014-10-09T08:15:40.843Z
last_login最近登录时间
last_login_ip最近登录IP
mcu_modMCU型号,20个字符
mcu_versionMCU软件版本号,32位数字整形
firmware_mod固件型号,20个字符
firmware_version固件版本号,32位数字整形
product_id产品ID
region_id所在区域ID
sn设备序列号
domain
create_time创建时间
creator_id创建者ID
creator_type创建者类型
tags设备标签
dealer_scope经销商可访问的范围
heavy_buyer大客户Id
groups所属分组列表

53.重试设置数据端点指令

重试设置设备数据端点值, 重试的数据端点必须是处于回写同步异常状态。

Request

URL

PUT /v2/device/command/{device_id}/datapoint
字段是否必须描述
device_id设备ID

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

{
  "index":[0, 1]
}
字段是否必须描述
index要进行重新设置数值的数据端点索引, 这些数据端点必须是处于同步异常状态

Response

Header

HTTP/1.1 200 OK

Content

54.批量修改设备的应用型数据端点值

企业管理员批量修改设备的应用类型数据端点

Request

URL

POST /v2/product/{product_id}/app_datapoint_value
字段是否必须描述
device_id设备ID

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

[{
    "mac":"设备MAC地址",
    "datapoints":[
            {"index":0,"value":"数据端点的值"},
            {"index":1,"value":"数据端点的值"}
        ]
},
]
字段是否必须描述
index要进行重新设置数值的数据端点索引, 这些数据端点必须是处于同步异常状态

Response

Header

HTTP/1.1 200 OK

Content

55.新版批量导入设备

企业管理员指定产品标识product_id url中 为在某个产品 批量导入设备, 导入时可以设置属性, 包括不限于sn/name,并返回每一个设备的导入结果。
一次最多只能导入2000个设备。

Request

URL

POST /v2/product/{product_id}/device_import_batch_2
字段是否必须描述
product_id产品ID,32个字符

Header

Content-Type:"application/json"
Access-Token:"调用凭证"

Content

[
    {
       "mac":"mac地址",
       "sn":"序列号",
       "name":"名字"
    },
    {
       "mac":"mac地址",
       "sn":"序列号",
       "name":"名字"
    }
]
字段是否必须描述
mac设备mac地址
sn设备序列号
name设备名称

Response

Header

HTTP/1.1 200 OK

Content

{
    "import_record_id":"导入记录id",
    "resp": [
        {
            "info":{
                "id": "设备ID",
                "mac": "设备MAC",
                "sn" : "设备序列号"
            },
            "errcode":0,
            "errmsg":""
        },
        {
            "info":{
                "mac": "设备MAC",
                "sn" : "设备序列号"
            },
            "errcode":4001147,
            "errmsg":"duplicate mac",
        }
    ]
}
字段是否必须描述
import_record_id导入记录id
id设备ID,只有导入成功才返回设备ID
mac设备mac地址
sn设备序列号,如果导入时有输入序列号,就返回。
errcode如果成功,返回0,如果失败,返回平台对应的错误码。
errmsg错误信息。

errcode说明

描述
0导入成功
4001002参数值为null
4001001参数校验失败
4001147导入设备的mac地址或者sn重复
4001021mac已存在
4001148sn已存在
4041033设备配额已经用完

56. 设备在线状态设置

提供一种以企业账号的权限进行对设备的在线状态进行设置,可对某一设备记录的在线显示进行设置;

若对离线设备设置为在线,可在设备列表中查看到设备状态为在线,但并非真实设备连接,此时对设备的控制或者其他实时操作无效;

若对在线设备设置为离线,此时设备依然保持连接正常通讯,此时设备列表中设备状态为离线;

若对已经在线或离线设备进行设置相同状态,接口设置无效,不覆盖设备当前状态,接口会返回成功;

若经本接口对设备进行设备状态进行设置之后,设备在线状态发生了变化,那么设备列表中的设备状态以真实设备为准。

接口权限:企业账号、企业授权

Request

URL

    PUT /v2/product/{prouct_id}/device/{device_id}/online_state

Header

    Content-Type:"application/json"

    Access-Token:"调用凭证"

Content

{
    "online_state": 1
}
字段是否必须说明
online_state枚举值,1:在线;0:离线


Response

Header

    HTTP/1.1 200 OK

Content

{
    "id": "设备ID",
    "mac": "MAC地址",
    "name": "设备名称",
    "is_active": "是否激活",
    "active_date": "激活时间",
    "is_online": "是否在线",
    "last_login": "最近登录时间",
    "last_login_ip": "最近登录IP",
    "mcu_mod": "MCU型号",
    "mcu_version": "MCU版本号",
    "firmware_mod": "固件型号",
    "firmware_version": "固件版本号",
    "corp_id": "企业ID",
    "product_id": "产品ID",
    "region_id": "所在区域ID",
    "sn": "序列号",
    "create_time": "创建时间",
    "creator_id": "创建者ID",
    "creator_type": "创建者类型",
    "tags": [
        "tag1",
        "tag2"
    ],
    "dealer_scope": "经销商可访问的范围",
    "heavy_buyer": "大客户Id",
    "last_reset": "最后激活时间",
	"online_count":""
}


字段是否必须描述
id设备ID,32位数字整形
mac设备MAC地址,12位十六进制字符
name设备名称
is_active是否已激活,布尔值,true或false
active_date激活时间,例:2014-10-09T08:15:40.843Z
is_online是否在线,布尔值,true或false
last_login最近登录时间
last_login_ip最近登录IP
mcu_modMCU型号,20个字符
mcu_versionMCU软件版本号,32位数字整形
firmware_mod固件型号,20个字符
firmware_version固件版本号,32位数字整形
corp_id企业ID
product_id产品ID
region_id所在区域ID
sn设备序列号
domain
create_time设备创建时间
creator_id设备创建者ID
creator_type设备创建者类型,见设备附录2
tags设备标签
dealer_scope经销商可访问的范围
heavy_buyer大客户Id,
last_reset最后激活时间,例:2014-10-09T08:15:40.843Z
online_count在线时长

57.查询宽表设备列表

根据查询条件查询宽表设备,请求条件/排序条件为宽表设备中的字段

Request

URL

POST /v2/wide-devices


Header

Content-Type:"application/json"

Access-Token:"调用凭证"

Content

{
    "offset": "请求列表的偏移量",
    "limit": "请求数量",
    "filter": [
        "字段A",
        "字段B"
    ],
    "query": {
        "filed1": {
            "$like": "字段值"
        },
        "filed3": {
            "$lt": "字段值"
        }
    },
    "order": {
        "filed1": "desc",
        "filed2": "asc"
    }
}

123

字段是否必须描述
offset从某个偏移量开始请求,默认为0
limit请求的条目数量,默认为10
order可以指定通过设备默认的某个字段排序,desc降序,asc升序
filter字段过滤,集合类型,可以指定返回结果列表的字段,可以
包含扩展属性字段
query查询条件,可以根据不同字段加上不同的比较指令来查询,查
询条件字段包含设备所有默认字段,不支持扩展属性字段,支
持比较指令包含如下:
$in:包含于该列表任意一个值
$lt:小于该字段值
$lte:小于或等于字段值
$gt:大于该字段值
$gte:大于或等于该字段值
$like:模糊匹配该字段值

Response

Header

    HTTP/1.1 200 OK

Content

{
	"count": "总数量",
	"list": [{
		"id": "设备ID",
		"product_id": "产品标识",
		"name": "设备名称",
		"sn": "设备序列号",
		"mac": "设备mac地址",
		"is_active": "是否激活",
		"organization_id": "组织标识",
		"product_name": "产品名称",
		"product_mode": "产品型号",
		"is_exception": "是否异常",
		"country": "所属国家",
		"province": "所属省份",
		"city": "所属城市",
		"is_online": "是否上线",
		"online_time": "上线时间",
		"active_date": "激活时间",
		"create_time": "设备创建时间",
		"project_ids": "设备所在项目列表"
	}]
}


字段是否必须描述
count总数量
list设备列表
id设备ID,32位数字整形
product_id产品ID
mac设备MAC地址,12位十六进制字符
name设备名称
sn设备序列号
is_active是否已激活,布尔值,true或false
active_date激活时间,例:2014-10-09T08:15:40.843Z
organization_id组织标识
product_name产品名称
product_mode产品型号
is_exception设备是否异常
country设备所在国家
province设备所在省份
city设备所在城市
is_online设备是否在线
online_time设备上线时间
create_time设备创建时间
project_ids设备所属项目

58. 设置产品的设备类型

  • 设置或者替换产品所属设备类型
  • 设置产品类型,先删除该产品下已有数据端点,再将设备类型下的通用数据端点加入到该产品下

Request

URL

PUT /v2/product/{product_id}/device-type

Header

Content-Type:application/json
Access-Token:"企业/经销商/大客户级别token"

Content

{
	"device_type":"SmartWaterMeter, 见设备类型附录"
}

Response

Header

HTTP/1.1 200 OK

Content


约定

产品附录

1.设备连接类型

枚举值说明
1wifi设备
2Zigbee设备
3蓝牙设备
4蓝牙Mesh设备
5PC设备

2.数据类型

枚举值说明
1布尔类型
2单字节(无符号)
316位短整型(有符号)
432位整型(有符号)
5浮点
6字符串
7字节数组
816位短整型(无符号)
932位整型(无符号)

3.转发规则类型

枚举值说明
1外部转发
2内部转发

4.转发规则数据类型

4.转发规则数据类型

枚举值说明
1设备上线
2设备下线
3设备激活
4Pipe透传
5设备同步包
6用户上线
7用户下线

5.产品类型

枚举值说明
0其他
1消费电子
2智能家居
3智能安防
4商用/工控设备
5照明/电工
6生活电器
7暖通空气

6.数据端点来源类型

枚举值说明
-1未知
1设备上报
2动态计算
3应用设置

7.数据端点目标值同步状态

枚举值说明
-1未知
1不需要下发到设备
2等待下发到设备
3下发到设备异常
4下发到设备成功

设备附录

1.设备查询支持字段

设备查询支持所有扩展字段,但只支持部分基础信息字段:
字段说明
id设备ID
mac设备MAC地址
is_online设备在线状态
firmware_version固件版本号

2.设备创建者类型

枚举值说明
1企业管理台成员创建
2用户创建

3.设备在线状态变化原因

枚举值说明
0正常
1网络异常


3.设备类型

枚举值说明
unkown未知
AirPurifier空气净化器
AirQualityInspection空气质量检测
AlarmPile报警桩
BluetoothWeightScale蓝牙体重秤
CarWashingMachine洗车机
CentralAirConditioning中央空调
ChargePile充电桩
CommercialWaterPurifier净水机
CurtainMachine窗帘机
DelayDetector延误探测器
DisinfectionCabinet消毒柜
DoorMagneticSensor门磁传感器
DrinkingMachine饮水机
ElectricCooker电饭煲
ElectricKettle电热水壶
Elevator电梯
FaceRecognition人脸识别
FireAlarm火警报警器
FireHydrant消防栓
GasDetector气体探测器
GasMeter燃气表
Gateway网关
HeaterMachine暖风机
Hoods抽油烟机
Humidifier加湿器
ImmersionDetector水浸探测器
InfraredDetector红外探测器
LandscapeIrrigation园林喷灌
Lawnmower割草机
Microwave微波炉
Outlet插座
Oven烤箱
ParkingLaneBrake停车道闸
PetFeeder宠物喂食器
PowerDistribution供配电
ServiceCabinet服务柜
SmartAccess智能门禁
SmartDoorLock智能门锁
SmartElectricalMeter智能电表
SmartLamp智能路灯
SmartLighting智能照明
SmartSwitch智能开关
SmartWaterMeter智能水表
SmartWellCover智能井盖
SolarEnergyStorage光伏储能
Sphygmomanometer血压计
SteamedCarton蒸箱
SurveillanceCameras监控摄像头
SweepingRobot扫地机器人
TrackingSystem追日系统
VendingMachine自动售货机
VoiceSpeaker语音音响
WaterHeater热水器
WaterPurifier净水机
WaterQualityMonitor水质检测
WaterSupply给排水

升级附录

1.设备固件类型

枚举值说明
1WIFI
2MCU
3子设备

2.设备升级任务类型

枚举值说明
1WIFI
2MCU
3子设备

产品扫描订阅策略类型

枚举值说明
1只允许扫描一次
2允许扫描多次




  • 无标签