# 阿里智能云的 OpenAPI 使用文档

# 1 认证密钥

# 1.1 加密参数获取

（1）accessKey&accessSecret

登录成功后，将鼠标移动到账号上，查看和复制 accessKey&accessSecret

{ "accessKey": "TH9cTq8g1boonH_******", "accessSecret": "RFzxoX****tHtMdHz0yCHypOI*****E7ck2sODT3" }

（2）iotInstanceId

选择实例，查看实例 ID

（3）timestamp

使用代码工具获取调用接口时的当前时间戳（毫秒级，13 位）

# 1.2 生成认证密钥

（1）认证密钥：sign

注意：timestamp 参与生成的认证密钥，“sign”的有效期为 5 分钟

private String calculate(String accessKey, String accessSecret, String iotInstanceId, String timestamp) throws Exception {
    if (StringUtils.isEmpty(accessKey) || StringUtils.isEmpty(accessSecret) || 										StringUtils.isEmpty(iotInstanceId) || StringUtils.isEmpty(timestamp)) {
        return "";
    }
    String signStr = "accessKey" + accessKey + "&" + "iotInstanceId" + iotInstanceId + "&" + "timestamp" + timestamp;
    return hmacSha256(signStr, accessSecret);
}

private String hmacSha256(String plainText, String key) throws Exception {
    return hmac(plainText, key, "HmacSHA256", "%064x");
}

private String hmac(String plainText, String key, String algorithm, String format) throws Exception {
    if (StringUtils.isEmpty(plainText)) {
        return "";
    }
    byte[] hmacResult;
    Mac mac = Mac.getInstance(algorithm);
    SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(), algorithm);
    mac.init(secretKeySpec);
    hmacResult = mac.doFinal(plainText.getBytes());
    return String.format(format, new BigInteger(1, hmacResult));
}

（2）示例

accessKey:TH9cTq8****onH_JW2**5Q
accessSecret:RFzxoXOOxL**tHtMdHz0yCH****QpV4mZE7ck2s***5
iotInstanceId:17*****721767915520
timestamp:1721467385000

拼接后的字符:accessKeyTH9cTq8****onH_JW2**5Q&iotInstanceId17*****721767915520&timestamp1721467385000

加密生成的sign:71ae648ce2adab37fde7576111512dee81ccf7ad6a605765a77faf82d0d8bd3b

# 1.3 请求头携带认证参数

参数名称	参数说明	请求类型	是否必须	数据类型
AccessKey	accessKey	Header	true	String
IotInstanceId	实例 ID	Header	true	String
Timestamp	时间戳（毫秒级）	Header	true	String
Sign	认证密钥	Header	true	String

# 2 自定义 topic 使用 OpenApi 下发到指定设备

# 2.1 接口地址

POST：https://api.aliyun.yoo.cn/iot/expose/customizeTopicPub

请求数据类型：application/json

# 2.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
customizeTopicPublishDto	OpenApi 自定义 topic 下发执行参数	body	true	CustomizeTopicPublishDto
topicFullName	要接收消息的设备的自定义 Topic 完全名称,例:/{productId}/{serialNumber}/user/update		true	String
messageContent	消息内容(平台会将字符串转字节数组进行下发)		true	String
qos	指定消息的发送方式。取值: 0：最多发送一次。1：最少发送一次。如果 QoS=1 消息未接收到 PUBACK 消息，会在设备重连时，重新推送给设备		true	Integer
isHexString	下发数据是否为hex字符串		false	Boolean

示例：

{
  "messageContent": "",
  "qos": 0,
  "topicFullName": "",
  "isHexString":true
}

# 2.3 返回参数

参数名称	参数说明
messageId	下发消息的消息 ID

# 2.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 3 自定义 topic 使用 OpenApi 批量下发到指定产品下的设备

# 3.1 接口地址

POST：https://api.aliyun.yoo.cn/iot/expose/customizeTopicBatchPub

请求数据类型：application/json

# 3.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
customizeTopicBatchPublishDto	OpenApi 自定义 topic 批量下发执行参数	body	true	CustomizeTopicBatchPublishDto
productId	要指定下发的产品 Id		true	Long
topicShortName	要接收消息的设备的自定义 Topic 简短名称,例:user/update		true	String
messageContent	消息内容(平台会将字符串转字节数组进行下发)		true	String
qos	指定消息的发送方式。取值: 0：最多发送一次。1：最少发送一次。如果 QoS=1 消息未接收到 PUBACK 消息，会在设备重连时，重新推送给设备		true	Integer
isHexString	下发数据是否为hex字符串		false	Boolean

示例：

{
    "messageContent": "",
    "productId": 0,
    "qos": 0,
    "topicShortName": ""
}

# 3.3 返回参数

参数名称	参数说明	数据类型
Key：serialNumber	设备编号	String
Value：messageId	对应设备的下发消息的消息 ID	String

# 3.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 4 设备文件上传

# 4.1 接口地址

POST：https://api.aliyun.yoo.cn/iot/expose/file/upload

请求数据类型：x-www-form-urlencoded

# 4.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
file	@RequestParam("file")		true	MultipartFile
customUploadFileDto	单个文件上传参数	body	true	CustomUploadFileDto
deviceId	文件上传指定的设备 Id		true	Long

# 4.3 返回参数

参数名称	参数说明
msg	文件上传情况

# 4.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 5 设备文件列表

# 5.1 接口地址

GET：https://api.aliyun.yoo.cn/iot/expose/file/list

请求数据类型：x-www-form-urlencoded

# 5.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
deviceId	设备 Id	query	true	Long
filename	文件名称	query	false	String
pageNum	分页页数	query	false	Integer
pageSize	分页大小	query	false	Integer

# 5.3 返回参数

参数名称	参数说明	数据类型
id	文件记录 id	String
deviceId	设备 id	Long
filename	文件名称	String
originalFilename	原文件名称	String
url	文件访问地址	String
fileSize	文件大小，单位 mb	BigDecimal
createTime	上传时间	Date

# 5.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 6 删除设备文件

# 6.1 接口地址

POST：https://api.aliyun.yoo.cn/iot/expose/file/del

请求数据类型：application/json

# 6.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
customDelFileDto	客户删除文件 Dto	body	true	CustomDelFileDto
deviceId	设备 Id		true	Long
ids	文件记录 id 列表		true	List

# 6.3 返回参数

参数名称	参数说明
msg	文件删除情况

# 6.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 7 云台方向控制

# 7.1 接口地址

POST：https://api.aliyun.yoo.cn/iot/expose/sip/ptz/direction/{channelSipId}

请求数据类型：application/json

# 7.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
channelSipId	通道 sipId	path	true	String
ptzDirectionInput	云台方向控制参数	body	true	PtzDirectionInput
leftRight	水平方向,1 right,2 left		false	int
upDown	垂直方向,1 up,2 down		false	int
moveSpeed	移动速度,单次移动距离		true	int

# 7.3 返回参数

参数名称	参数说明
msg	success!,指令下发成功
data	true 指令执行成功, false 指令执行失败

# 7.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 8 查询视频裁剪合并任务

# 8.1 接口地址

POST：https://api.aliyun.yoo.cn/iot/expose/sip/addTaskForDownload

请求数据类型：application/json

# 8.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
taskForDownloadDto	视频裁剪合并任务参数	body	true	TaskForDownloadDto
channelSipId	通道 sipId		true	String
startTime	合并开始时间		false	String
endTime	合并截止时间		true	String

# 8.3 返回参数

参数名称	参数说明
taskId	裁剪合并任务 id

# 8.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 9 获取合并录像

# 9.1 接口地址

GET：https://api.aliyun.yoo.cn/iot/expose/sip/getTaskListForDownload

请求数据类型：x-www-form-urlencoded

# 9.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
taskId	视频裁剪合并任务 id	query	true	String
channelSipId	通道 sipId	query	true	String

# 9.3 返回参数

参数名称	参数说明
mediaAddress	录像下载地址

# 9.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 10 获取 webrtc 推流地址

# 10.1 接口地址

GET：https://api.aliyun.yoo.cn/iot/expose/sip/getWebRtcAddr/{channelSipId}

请求数据类型：x-www-form-urlencoded

# 10.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
Username	固定传“1”	query	true	String
channelSipId	通道 sipId	path	true	String

# 10.3 返回参数

参数名称	参数说明
webRtcAddr	webrtc 推流地址

# 10.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 11 录像文件列表

# 11.1 接口地址

POST：https://api.aliyun.yoo.cn/iot/expose/sip/record/file/list

请求数据类型：application/json

# 11.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
recordListDto	查询录像列表参数	body	true	RecordListDto
channelSipId	通道 sipId		true	String
startTime	开始时间		true	String
endTime	结束时间		true	String
pageNum	分页页数		true	Integer
pageSize	分页大小		true	Integer

# 11.3 返回参数

参数名称	参数说明
uri	录像文件地址

# 11.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 12 截图

# 12.1 接口地址

GET：https://api.aliyun.yoo.cn/iot/expose/sip/screenshots/{channelSipId}

请求数据类型：x-www-form-urlencoded

# 12.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
channelSipId	通道 sipId	path	true	String

# 12.3 返回参数

参数名称	参数说明
uri	截图地址

# 12.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 13 拉流直播接口

# 13.1 接口地址

GET：https://api.aliyun.yoo.cn/iot/expose/sip/stream/{channelSipId}

请求数据类型：x-www-form-urlencoded

# 13.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
channelSipId	通道 sipId	path	true	String

# 13.3 返回参数

参数名称	参数说明
Stream	直播流

# 13.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

# 14 第三方推流截图接口

# 14.1 接口地址

GET：https://api.aliyun.yoo.cn/iot/expose/sip/otherScreenshots/{channelSipId}

请求数据类型：x-www-form-urlencoded

# 14.2 接口参数

参数名称	参数说明	请求类型	是否必须	数据类型
channelSipId	通道 sipId	path	true	String

# 14.3 返回参数

参数名称	参数说明
data:url	截图地址

# 14.4 响应状态

状态码	说明
200	OK
401	Unauthorized
403	Forbidden
404	Not Found

← WIFI云音响