概述

本文档适用于智城云平台与第三方云平台的对接的开发、调测，为智城云接入第三方云设备或第三方云平台接入智城云设备提供支撑能力。

协议约定

术语

智能设备：直接接入云平台的智能家居设备，作为云平台的远程控制执行体。包括WiFi智能设备、应用网关等。本分册中简称设备或device。
用户：设备的使用者，可以通过登录APP实现对设备的监控和操作，本文称用户或者user。
主控云：用户连接的物联网云，因为用户可以控制设备，是主要控制方，所以用户所在的云称为主控云，具体信息可以参考下文介绍。
受控云：设备直接连接的物联网云，因为设备总是被控制，所以设备所在的云称为受控云，具体信息可以参考下文介绍。
应用网关：智能设备的一种类型，上层通过WiFi或有线通过家庭智能网关接入到云平台，内部通过不同的无线通信协议（ZigBee，Z-vave、RF等）与智能设备连接通信。
组网终端：在家庭范围内，延伸智能网关网络覆盖的终端设备，主要包括：无线AP、电力猫、无线中继以及具备WiFi能力的EOC终端设备等。
APP：可安装在手机、PAD、电脑和其他移动终端商的智能家居用户控制软件，供用户发送操控指令，获取智能设备状态，提供用户进行设备连接、绑定等管理功能操控界面。本分册中简称APP。
用户鉴权：主控云想要操控受控云设备时需要按照约定验证其身份的合法性。
设备发现：局域网内通过APP搜索设备的过程。
指令：设备可以识别并执行的消息。
设备控制：云平台向设备发送指令，设备接收并执行。
设备状态：设备向云平台发送或反馈的自身状态数据或运行参数。
设备型号：绑定设备时必须要指定的型号信息，用来标识设备的制造商、产品、型号等信息。
设备ID：设备接入到云平台时必须具有的唯一编号，用于平台区分不同的设备，该编号由云平台分配。

名词解释

名词	含义
gid	云平台设备类型ID信息
thirdCloudId	主控方分配给受控方的应用ID，用于受控方上报数据时的身份认证
thirdCloudKey	主控方分配给受控方的应用密钥，用于受控方上报数据时的身份认证
applicationId	受控方分配给主控方的应用ID，用于主控方控制受控方设备时的身份认证
applicationKey	受控方分配给主控方的应用密钥，用于主控方控制受控方设备时的身份认证
userId	主控方的用户唯一标识，用于主控方登录受控方
accessToken	受控方提供的用户的访问凭证
openId	受控方返回的用户唯一标识，主控方用户登录后，受控方会新增相应用户并且返回用户的唯一标识
openKey	受控方返回的用户的访问token，每次调用受控方的设备控制等接口的时候需要使用openKey进行加密

接口规范

命名规范

CloudAPI采用标准的API采用标准的Restful规范定义接口，HTTP请求的几大关键要素：

请求协议
包括安全的和非安全的协议，安全的一般为：HTTPS，非安全的为：HTTP
请求主机域名
请求的域名，决定请求哪种环境，例如：api.machtalk.net，test.api.machtalk.net
请求地址
请求的相对路径，类似 /v1/user,请求地址一般为名词
请求头信息
头信息包括标准的头信息，如：Accept-Language，Keep-Alive等，智城云的标准开放参数也放在头信息中，如openId，openKey，applicationId，applicationKey，开放参数统一使用大写。注意Content-Type头信息对于文本型的请求统一使用application/json
请求方式
请求方式包括四种：GET，POST，PUT，DELETE；标识请求的操作类型

请求方式	含义
GET	获取资源
POST	增加资源
PUT	修改资源
DELETE	删除资源

接口命名规范

使用有含义的英文单词
API中包含版本号
使用请求方式决定操作类型，而不是将操作类型放在API地址上
同一模块尽量使用相同的层级，比如用户模块使用/v1/user/XX/YY，保证可读性
API的参数会进行业务校验

输入和输出

CloudAPI的输入与输出都是JSON，提交的参数以流的形式传参给服务器，服务器会把每个请求都理解为JSON字符串。
CloudAPI采用标准的Restful接口风格，标准的文本类接口的content-type使用application/json，输入和输出均使用标准的JSON格式，设备输入的参数长度不能超过2K。

安全规范

接口请求，必须保证每次请求的安全合法，CloudAPI使用SHA1对请求信息进行运算得到一个摘要进行请求的签名。

CloudAPI分为两类API：需要用户鉴权的和不需要用户鉴权的。

不需要用户鉴权的，例如用户鉴权、设备数据上报等（详情见接口说明），sign加密方法为：SHA1(HTTPMethod(大写)+RequestURI+params+applicationKey) ；
需要用户鉴权的，例如绑定设备、解绑设备等（详情见接口说明），sign加密方法为：SHA1(HTTPMethod(大写)+RequestURI+params+ts+openKey+applicationKey)。

其中，HTTPMethod为GET、POST之类。
RequestURI为URL去掉host部分，如 http://{host}/user/auth，则RequestURI=/user/auth。
params是请求的json参数字符串，保留原始的请求内容，GET、DELETE时可以不拼接。
ts为时间戳，1970年1月1日到当前请求时刻的毫秒数。
applicationKey为企业开放信息Key，可以在企业后台中查看。
openKey为经过鉴权后受控方返回的用户临时访问秘钥。

接口限制

平台的接口调用并不是无限制的。为了防止开发者号的程序错误而引发服务器负载异常，默认情况下，每个应用调用接口都不能超过一定限制，当即将超过一定限制时，调用对应接口会收到错误码，同时会发送告警邮件给企业负责人和平台运维人员，基本的访问限制规则为每5分钟调用接口1000次，超过阈值则抛错，1小时后恢复接口调用。
对于接口请求的IP如果超过一定限制也会放入请求黑名单，同时提供告警。
平台会统计接口响应速度报表，提供接口服务质量依据。

接口调试

注意事项

请求头信息

所有接口都需要鉴权的Headers，基本的Headers应该至少包括如下内容：

Header_Key	Header_Value
applicationId	企业的开放信息账号，可以在企业后台中查看
sign	加密签名，具体算法参考上述安全规范

失败返回

所有接口的请求，失败时会统一返回固定格式：

{
	"code": 0,
	"msg": "error message"
}

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码
msg	失败描述	String	错误描述

请求域名

默认所有API的请求域名为：

1	https://capi.zcyun.cn

请求时请在接口URL加上这个前缀

使用场景

场景一：智城云做受控云

智城云做受控云
智城云作为受控方，设备直连智城云，第三方云可以控制智城云设备，橙色表示智城云需要实现的接口，绿色表示第三方云需要提供的接口。具体接口信息参见下文。
这种情况第三方云需要严格按照智城云的接口进行开发。

场景二：智城云做主控云

智城云做主控云
智城云作为主控方，指智城云用户可以控制第三方云的设备，图中橙色代表第三方云（受控云）提供的接口，绿色表示智城云需要实现的接口。
根据需要，智城云可能会适配第三方云提供的接口格式，也可能第三方云适配智城云对接标准接口。

接口列表

接口名称	接口地址	请求方式	接口含义
数据上报接口	/v1/thirdcloud/device/status	POST	接收第三方设备状态上报（上下线、状态变化）
用户验证接口	/v1/thirdcloud/user/validate	POST	受控云回调主控云该接口，验证用户名、密码是否合法
恢复出厂设置接口	/v1/thirdcloud/device/reset	POST	自定义添加用户记录
用户鉴权接口	/v1/thirdcloud/user/auth	POST	主控云用户登录受控云平台
用户退出接口	/v1/thirdcloud/user/exit	GET	主控云用户退出受控云平台
设备绑定接口	/v1/thirdcloud/device/bind	POST	主控云用户绑定受控云设备
设备解绑接口	/v1/thirdcloud/device/unbind	POST	主控云用户解绑受控云设备
设备控制接口	/v1/thirdcloud/device/control	POST	主控云用户操控受控云设备
设备查询接口	/v1/thirdcloud/device/query	POST	主控云用户查询受控云设备当前状态
设备列表接口	/v1/thirdcloud/device/list	GET	主控云用户查询受控云设备列表

主控云接口

数据上报接口

说明：主控云接收第三方云设备的状态上报，服务器端收到后会解析并属性转换，其后转发到APP。
URL：/v1/thirdcloud/device/status
请求方式：POST
Header参数：参考请求头信息
请求参数：

{
	"deviceId": "deviceId",
	"sid": "sid",
	"gid": "123456",
	"online": 0 / 1,
	"time": "2021-04-08 00:00:00",
	"status": {
		"key1": "v1",
		"key2": "v2"
	}
}

请求参数说明：

参数名称	中文名称	类型	限制	必须	说明
deviceId	设备ID	String	64	是	普通wifi设备或网关ID
sid	子设备ID	String	64	否	子设备ID，存在时deviceId表示其上层网关
gid	型号ID	String	32	是	型号ID
online	在线状态	Integer	1	是	在线标识，0离线 1在线
time	上报时间	String	32	是	上报时间点，格式yyyy-MM-dd HH:mm:ss
status	设备状态	JSON	2048	否	设备状态，key为属性ID或第三方属性名称，value代表其属性值

成功返回：

1
2
3

{
	"code": 0
}

返回说明：

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功

用户验证接口

说明：主控云调用第三方云的用户鉴权接口时，第三方云回调主控云该接口，验证用户名、密码是否合法。
URL：/v1/thirdcloud/user/validate
请求方式：POST
Header参数：参考请求头信息
请求参数：

{
	"userId": "abc",
	"accessToken": "abc"
}

请求参数说明：

参数名称	中文名称	类型	限制	必须	说明
userId	用户ID	String	32	是	主控云用户的唯一标识
accessToken	临时秘钥	String	32	是	主控云提供的用户的访问凭证

成功返回

1
2
3

{
	"code": 0
}

返回说明：

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功

恢复出厂设置接口

说明：受控云第三方设备恢复出厂设置时，需要回调主控方云端该接口，实现清理该设备在主控云上的绑定关系。根据实际情况，没有实际需求的话不需要开发此接口。
URL：/v1/thirdcloud/device/reset
请求方式：POST
Header参数：参考请求头信息
请求参数：

{
	"deviceId": "deviceId",
	"gid": "123456"
}

请求参数说明：

参数名称	中文名称	类型	限制	必须	说明
deviceId	设备ID	String	64	是	设备ID
gid	型号ID	String	32	是	该设备对应的型号标识

成功返回

1
2
3

{
    "code": 0
}

返回说明：

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功

受控云接口

用户鉴权接口

说明：主控云用户向受控云发起绑定或其他操作时，需要首先调用受控云该鉴权接口获取其在受控云上的openId(用户ID)和openKey(用户临时访问秘钥)。受控云收到鉴权请求后向主控云请求用户验证接口以确保鉴权请求的用户名密码正确，如果正确，返回给主控方openId和openKey。
URL：/v1/thirdcloud/user/auth
请求方式：POST
Header参数：参考请求头信息
请求参数：

{
	"userId": "abc",
	"accessToken": "123456"
}

请求参数说明：

参数名称	中文名称	类型	限制	必须	说明
userId	用户ID	String	32	是	第三方主控云用户的唯一标识
accessToken	临时秘钥	String	32	是	第三方主控云提供的用户的访问凭证

成功返回

{
	"code": 0,
	"openId": "123456",
	"openKey": "123456",
	"expiredAt": 123456
}

返回说明：

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码
openId	用户ID	String	受控方云端用户的唯一标识
openKey	用户临时秘钥	String	受控方云端用户的临时访问秘钥，一般为32位随机字符串
expiredAt	过期时间点	Long	openKey的失效时间，系统时间戳格式，精确到ms，一般有效期为7天

用户退出接口

说明：主控方用户主动退出后，为了避免受控方openKey信息泄露，需要调用受控方的用户退出接口，使openKey信息失效。
URL：/v1/thirdcloud/user/exit
请求方式：GET
Header参数：参考请求头信息，附加

Header_Key	Header_Value
openId	受控方平台返回的用户唯一ID，主控方在受控方平台鉴权用户后返回
ts	时间戳，请求时的系统时间戳，精确到毫秒，1970年1月1日到请求时刻的毫秒数

请求参数：

成功返回

1
2
3

{
	"code": 0
}

返回说明：

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功

设备绑定接口

说明：主控方APP绑定受控云设备时，由主控云调用受控方该接口将绑定消息通知到受控云，进而实现设备与用户的绑定。主控云与受控云各自独立维护用户与设备的绑定关系。
URL：/v1/thirdcloud/device/bind
请求方式：POST
Header参数：参考请求头信息，附加

Header_Key	Header_Value
openId	受控方平台返回的用户唯一ID，主控方在受控方平台鉴权用户后返回
ts	时间戳，请求时的系统时间戳，精确到毫秒，1970年1月1日到请求时刻的毫秒数

请求参数：

{
	"deviceId": "deviceId",
	"gid": "123456"
}

请求参数说明：

参数名称	中文名称	类型	限制	必须	说明
deviceId	设备ID	String	32	是	受控云设备的唯一标识
gid	型号	String	6	是	APP识别出来的，一般为受控云设备所属型号

成功返回

1
2
3

{
    "code": 0
}

返回说明：

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功

设备解绑接口

说明：主控云APP解绑受控云设备时，由主控云调用受控云该接口将解绑消息通知到受控云，进而实现设备与用户的解绑。
URL：/v1/thirdcloud/device/unbind
请求方式：POST
Header参数：参考请求头信息，附加

Header_Key	Header_Value
openId	受控方平台返回的用户唯一ID，主控方在受控方平台鉴权用户后返回
ts	时间戳，请求时的系统时间戳，精确到毫秒，1970年1月1日到请求时刻的毫秒数

请求参数：

{
    "deviceId": "deviceId",
    "gid": "123456"
}

请求参数说明：

参数名称	中文名称	类型	限制	必须	说明
deviceId	设备ID	String	32	是	受控云设备的唯一标识
gid	型号	String	6	是	受控云设备所属型号

成功返回

1
2
3

{
    "code": 0
}

返回说明：

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功

设备控制接口

说明：主控云APP操控受控云设备时，由主控云调用受控云该接口实现设备的操控。设备响应成功后会把变化的状态通过HTTP推送到主控云数据上报接口上。
URL：/v1/thirdcloud/device/control
请求方式：POST
Header参数：参考请求头信息，附加

Header_Key	Header_Value
openId	受控方平台返回的用户唯一ID，主控方在受控方平台鉴权用户后返回
ts	时间戳，请求时的系统时间戳，精确到毫秒，1970年1月1日到请求时刻的毫秒数

请求参数：

{
	"deviceId": "deviceId",
	"sid": "sid",
	"gid": "123456",
	"command": {
		"key1": "v1",
		"key2": "v2"
	}
}

请求参数说明：

参数名称	中文名称	类型	限制	必须	说明
deviceId	设备ID	String	32	是	WiFi设备或网关设备的唯一标识
sid	子设备ID	String	64	否	网关下子设备的唯一标识
gid	型号	String	6	是	受控云设备所属型号
command	设备属性信息	JSON	256	是	操控设备属性信息，key为属性ID，value代表其属性值

成功返回

1
2
3

{
    "code": 0
}

返回说明：

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功

设备查询接口

说明：主控云APP查询受控云设备状态时，由主控云调用受控云该接口实现设备完整数据的查询。
URL：/v1/thirdcloud/device/query
请求方式：POST
Header参数：参考请求头信息，附加

Header_Key	Header_Value
openId	受控方平台返回的用户唯一ID，主控方在受控方平台鉴权用户后返回
ts	时间戳，请求时的系统时间戳，精确到毫秒，1970年1月1日到请求时刻的毫秒数

请求参数：

{
    "deviceId": "deviceId",
    "sid": "sid",
    "gid": "123456"
}

请求参数说明：

参数名称	中文名称	类型	限制	必须	说明
deviceId	设备ID	String	32	是	WiFi设备或网关设备的唯一标识
sid	网关ID	String	64	否	网关下子设备的唯一标识
gid	型号	String	6	是	受控云设备所属型号

成功返回：

{
	"code": 0,
	"data": {
		"status": { //网关或WiFi设备本身状态
			"key1": "value1",
			"key2": "value2"
		},
		"gid": "xx",
		"online": 0 / 1,
		"childs": [ //子设备状态
		{
			"deviceId": "sid1",
			"gid": "xx",
			"online": 0 / 1,
			"status": {
				"key3": "value3",
				"key4": "value4"
			}
		},
		{
			"deviceId": "sid2",
			"gid": "xx",
			"online": 0 / 1,
			"status": {
				"key5": "value5",
				"key6": "value6"
			}
		}]
	}
}

返回说明：

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功，非0表示失败错误码
status	设备状态	JSON	设备属性状态集
online	在线标识	Integer	0离线 1在线
gid	型号ID	String	设备型号标识
childs	子设备集合	Array	当查询的是网关设备时，返回下边的子设备状态列表

设备列表接口

说明：主控方通过该接口获取受控云上的绑定设备列表。
URL：/v1/thirdcloud/device/list
请求方式：GET
Header参数：参考请求头信息，附加

Header_Key	Header_Value
openId	受控方平台返回的用户唯一ID，主控方在受控方平台鉴权用户后返回
ts	时间戳，请求时的系统时间戳，精确到毫秒，1970年1月1日到请求时刻的毫秒数

请求参数：

成功返回：

{
	"code": 0,
	"data": [{
		"deviceId": "deviceId1",
		"bindTime": "2021-4-8 12:12:12",
		"deviceName": "deviceId1",
		"gid": "123456",
		"online": 0,
		"childs": [{
			"deviceId": "deviceId1",
			"bindTime": "2021-4-8 12:12:12",
			"deviceName": "deviceId1",
			"gid": "123456",
			"online": 0
		}]
	},
	{
		"deviceId": "deviceId2",
		"bindTime": "2021-4-8 12:12:12",
		"deviceName": "deviceId2",
		"gid": "123456",
		"online": 0
	}]
}

返回说明：

参数名称	中文名称	类型	说明
code	成功标识	Integer	0成功
deviceId	设备ID	String	设备ID
bindTime	绑定时间	String	绑定时间，格式yyyy-MM-dd HH:mm:ss
deviceName	设备名称	String	设备名称
gid	型号ID	String	设备型号标识
online	在线标识	Integer	0离线 1在线
childs	子设备集合	Array	当查询的是网关设备时，返回下边的子设备状态列表