中国电信物联网开放平台API参考131.docx
《中国电信物联网开放平台API参考131.docx》由会员分享，可在线阅读，更多相关《中国电信物联网开放平台API参考131.docx（186页珍藏版）》请在冰豆网上搜索。
中国电信物联网开放平台API参考131
中国电信物联网开放平台API参考1.3.1
（V1）
二〇一九年三月
编制单位：
编制单位
修订记录：
版本号
日期
描述
01
2017/11/06
中国电信物联网开放平台API参考1.3.1
目录
1PlatformAPI参考（北向）1
1.1前言1
1.2接口列表1
1.2.1应用安全接入2
1.2.1.1Auth（鉴权）2
1.2.1.2RefreshToken（刷新token）3
1.2.1.3注销5
1.2.2设备管理6
1.2.2.1注册直连设备6
1.2.2.2发现非直连设备8
1.2.2.3查询设备激活状态11
1.2.2.4删除直连设备13
1.2.2.5删除非直连设备14
1.2.2.6修改设备信息17
1.2.2.7刷新设备密钥19
1.2.2.8设置加密21
1.2.3数据采集23
1.2.3.1按条件批量查询设备信息列表23
1.2.3.2查询单个设备信息27
1.2.3.3Application订阅平台数据29
1.2.3.4查询设备历史数据30
1.2.3.5查询设备能力35
1.2.4信令传送38
1.2.4.1创建设备命令V438
1.2.4.2查询设备命令V441
1.2.4.3修改设备命令V445
1.2.4.4创建设备命令撤销任务V447
1.2.4.5查询设备命令撤销任务V450
1.2.5设备服务调用55
1.2.5.1设备服务调用55
1.2.6批量处理58
1.2.6.1创建批量任务58
1.2.6.2查询单个任务信息61
1.2.6.3查询任务详情信息63
1.2.7规则66
1.2.7.1创建规则66
1.2.7.2更新规则79
1.2.7.3修改规则状态83
1.2.7.4删除规则84
1.2.7.5查找规则85
1.2.7.6批量修改规则状态87
1.2.8消息推送90
1.2.8.1注册直连设备的通知90
1.2.8.2发现非直连设备的通知92
1.2.8.3设备信息变化的通知93
1.2.8.4设备数据变化的通知94
1.2.8.5删除非直连设备的通知95
1.2.8.6消息确认通知96
1.2.8.7设备响应命令通知98
1.2.8.8设备事件通知100
1.2.8.9设备服务上报通知102
1.2.8.10规则事件上报通知103
1.2.8.11绑定设备通知105
1.2.8.12批量设备数据变化上报通知107
1.3常用数据结构体定义108
1.3.1DeviceInfo结构体说明108
1.3.2DeviceService结构体说明110
1.3.3QueryDeviceDTOCloudNA结构体说明110
1.3.4ServiceCommand结构体说明110
1.3.5ServiceProperty结构体说明111
1.3.6DeviceCommandResp结构体说明112
1.3.7CommandDTOV4结构体说明113
1.3.8GetDeviceRspDTO结构体说明113
1.3.9CommandNA2CloudHeader结构体说明114
1.3.10ApplicationSetEncrtptDTO结构体说明114
1.3.11PutCarInfoData结构体说明114
1PlatformAPI参考（北向）
1.1前言
1.2接口列表
1.3常用数据结构体定义
1.1前言
本文档系统化描述IoTPlatform（下文简称平台）对外开放的能力全集、集成原理和集成参考样例等信息，帮助集成开发者快速而准确的掌握集成方法从而高效实现特定的业务需求。
本文档主要包含如下几个部分：
一接口列表
主要描述能力开放的接口集合，详细介绍每个接口的功能、输入参数、输出参数、和消息样例等信息。
二常用数据结构定义
是对多个接口都会用到的数据结构做一个详细介绍，方便开发者集中查看。
1.2接口列表
Application侧接口除了鉴权接口Auth，其他接口调用都需要在requestheader中携带参数app_key和Authorization:
Bearer{accessToken}。
Authorization中{accessToken}的值即为调用Auth接口获取到的accessToken。
应用开发语言若是JAVA请使用JDK1.8。
北向提供的API是平台与Application之间的https接口，请使用安全传输协议TLS1.1/1.2。
1.2.1应用安全接入
Application携带在IoTPlatform（下文简称平台）产生的appId和secret过来，调用鉴权接口，获取鉴权token。
请参考本文档2.1.1鉴权章节进行开发。
1.2.1.1Auth（鉴权）
接口功能
实现第三方系统在访问开放API之前的认证。
调用方法
POST
接口路径
https:
//server:
port/iocm/app/sec/v1.1.0/login
注意事项
鉴权接口是调用其他API的前提，北向接口除了鉴权接口（Auth），其他接口调用都需要在requestheader中携带参数app_key和Authorization:
Bearer{accessToken}。
app_key为参数中的appId，Authorization中{accessToken}的值即为调用Auth接口获取到的accessToken。
如果多次获取令牌，则之前的令牌失效,最后一次获取的令牌才有效。
请勿并发获取令牌。
参数说明
参数
必选/可选
类型
描述
appId
必选
String
用户名，填写应用程序ID
secret
必选
String
登录用户口令，填写应用程序密码
返回结果
字段
类型
描述
scope
String
范围，默认值default
tokenType
String
鉴权token类型，默认值bearer
expiresIn
Integer
平台生成并返回accessToken的有效时间，单位秒
accessToken
String
Oauth2.0鉴权参数
refreshToken
String
Oauth2.0鉴权参数，用来刷新accessToken。
（1个月的有效期）
消息事例
Method：
POST
request：
（非JSON格式）
https:
//server:
port/iocm/app/sec/v1.1.0/login
Content-Type:
application/x-www-form-urlencoded
Body:
appId={appId}&secret={secret}
response：
StatusCode:
200OK
Content-Type:
application/json
Body:
{
"scope":
"default",
"tokenType":
"bearer",
"expiresIn":
"*******",
"accessToken":
"*******",
"refreshToken":
"*******"
}
异常返回码
HttpStatusCode
error_code
error_desc
说明
401
100208
AppIdorsecretisnotright.
appId或secret错误
1.2.1.2RefreshToken（刷新token）
接口功能
accessToken快过期时，第三方系统通过调用此接口，重新获取可用token。
accessToken有效时间参照2.1.1鉴权接口返回字段expiresIn的值。
调用方法
POST
接口路径
https:
//server:
port/iocm/app/sec/v1.1.0/refreshToken
注意事项
Body参数说明
参数
必选/可选
类型
描述
appId
必选
String
用户名，填写应用程序ID
secret
必选
String
登录用户口令，填写应用程序密码
refreshToken
必选
String
刷新令牌，用于获取一个新的accessToken
返回结果
字段
类型
描述
scope
String
范围
tokenType
String
鉴权token类型，默认值bearer
expiresIn
String
平台生成并返回accessToken的有效时间，单位秒
accessToken
String
Oauth2.0鉴权参数
refreshToken
String
刷新令牌，用于获取一个新的accessToken
消息事例
Method：
POST
request：
https:
//server:
port/iocm/app/sec/v1.1.0/refreshToken
Content-Type:
application/json
Body:
{
"appId"="******",
"secret"="******",
"refreshToken":
"******"
}
response：
StatusCode:
200OK
Content-Type:
application/json
Body:
{
"accessToken":
"*******",
"tokenType":
"*******",
"expiresIn":
"*******",
"scope":
”*******”,
"refreshToken":
"*******"
}
异常返回码
HttpStatusCode
error_code
error_desc
说明
400
100022
Theinputisinvalid.
输入参数无效
401
100006
Refreshaccesstokenfailed.
refreshToken无效
401
100208
AppIdorsecretisnotright.
appId或secret错误
1.2.1.3注销
接口功能
NA注销鉴权信息。
调用方法
POST
接口路径
https:
//server:
port/iocm/app/sec/v1.1.0/logout
注意事项
无
参数说明
参数
必选/可选
类型
描述
accessToken
必选
String（256）
调用鉴权接口获取到的Oauth2.0鉴权参数
返回结果
StatusCode:
204NoContent
消息事例
Method:
POST
Request:
https:
//server:
port/iocm/app/sec/v1.1.0/logout
Header：
Content-Type:
application/json
Body:
{
"accessToken":
"*******"
}
Response:
StatusCode:
204NoContent
Content-Type:
application/json
异常返回码
HttpStatusCode
error_code
error_desc
说明
400
100022
Theinputisinvalid.
输入参数无效
1.2.2设备管理
设备管理提供了Application（下文简称App）申请设备的增，删，改，查以及修改设备基本信息的接口。
App向IoTPlatform申请新的设备,IoTPlatform分配对应的设备验证码，待设备携带验证码请求接入平台后，分配其deviceId和secret，允许其使用。
平台提供了增，删，改，查接口，实现对新增设备接入灵活操作。
对设备的管理请参考本文档进行开发。
1.2.2.1注册直连设备
接口功能
应用程序添加设备，获取设备的验证码，并在设备访问南向接口时携带验证码，获取设备唯一标识和密码。
调用方法
POST
接口路径
https:
//server:
port/iocm/app/reg/v1.2.0/devices?
appId={appId}
注意事项
携带头域信息
Header：
"app_key:
{appId}"
"Authorization:
Bearer{accessToken}"
Content-Type:
application/json;
备注：
app_key为参数中的appId，Authorization中{accessToken}的值即为调用Auth接口获取到的accessToken。
参数说明
字段
必选/可选
类型
描述
appId
可选
String
应用唯一标识
verifyCode
可选
String
客户端给出verifyCode则返回的就是这个verifyCode，即使用客户端给出的verifyCode。
如果不指定，系统自动生成。
nodeId
必选
String
设备唯一标识,如：
MAC或SIM卡号或设备esn号等。
与设备对接时，必须与设备上报的nodeId一致。
备注：
nodeId和verifyCode需要填写相同的值，如果南向连接SoftRadio的模拟环境，该值可自行定义，格式为TESTS_XXXXXX。
如果是现网环境，该值通常为设备的IMEI号。
endUserId
可选
String
终端用户Id，如手机号码，email地址
psk
可选
String
psk码，用于生成设备鉴权参数；如不传入，系统自动生成
timeout
可选
Integer
单位秒，不填使用默认值（180s）,填写0则永不过期，非0表示在指定时间内设备进行绑定，超过时间验证码无效
返回结果
字段
类型
描述
deviceId
String
设备唯一标识，1-64个字节
verifyCode
String
申请的临时验证码，设备可以通过验证码获取id和密码
timeout
Integer
验证码有效时间，单位秒，设备需要在有效时间内接入平台
psk
String
psk码，用于生成设备鉴权参数
消息事例
Method：
POST
request：
https:
//server:
port/iocm/app/reg/v1.2.0/devices?
appId={appId}
Header：
"app_key:
{appId}"
"Authorization:
Bearer{accessToken}"
Content-Type:
application/json
Body:
{
"verifyCode":
"AE10-12424-12414",
"nodeId":
"AE10-12424-12414",
"timeout":
300
}
response：
StatusCode:
200OK
Content-Type:
application/json
Body:
{
"deviceId":
"*******",
"verifyCode":
"*******",
"timeout":
300,
"psk":
"******"
}
异常返回码
HttpStatusCode
error_code
error_desc
说明
401
100002
Invalidaccesstoken.
错误的token信息
400
100022
Theinputisinvalid.
输入参数无效
401
100025
AppIdforauthnotexist.
获取不到appId鉴权信息
200
100203
Theapplicationisnotexisted.
应用不存在
200
100217
Theapplicationhasn'tbeenauthorized.
应用未被授权
400
100007
Badrequestmessage.
参数不合法
200
100412
Theamountofdevicehasreachedthelimit.
当前应用下设备数量达到上限
400
100003
Invalidverifycode.
验证码无效
200
100416
Thedevicehasalreadybeenbinded.
设备已经绑定
500
100001
Internalservererror.
服务内部处理错误
200
103026
Thelicenseisnotexist.
License不存在
200
103028
Thelicensepoolresources.
License无资源
200
103027
Thelicensesalesisnotexist.
License的销售项不存在
1.2.2.2发现非直连设备
接口功能
Application发送DISCOVERY命令给网关下的设备。
一般用于通过网关添加传感器，若没有网关，该接口请勿使用。
调用方法
POST
接口路径
https:
//server:
port/iocm/app/signaltrans/v1.1.0/devices/{deviceId}/services/{serviceId}/sendCommand?
appId={appId}
注意事项
http携带头域信息：
Header：
"app_key:
{appId}"
"Authorization:
Bearer{accessToken}"
Content-Type:
application/json;
URL参数说明：
字段
必选/可选
类型
描述
deviceId
必选
String
网关设备唯一标识，1-64个字节
serviceId
必选
String
取值"Discovery"
http消息体说明：
字段
必选/可选
类型
描述
appId
可选
String
应用唯一标识
message
必选
CommandDTONA2Cloud
CommandDTONA2Cloud消息体说明参见下表
CommandDTONA2Cloud消息体说明：
字段
必选/可选
类型
描述
header
必选
CommandNA2CloudHeader
见附录1.3.9CommandNA2CloudHeader结构体说明字段说明
body
可选
ObjectNode
取值长度无要求，消息的消息体
返回结果：
字段
类型
描述
status
String（128）
命令状态：
sent---已发送、delivered---已送达
executed---已执行
timestamp
String（128）
发送命令的时间戳，1-32字节
时间格式：
yyyyMMdd’T’HHmmss’Z’如：
20151212T121212Z
requestId
String（128）
1-32个字节，平台分配的序列号，标识一个命令
需要requestId关联对应命令执行结果
消息事例
Method：
POST
request：
https:
//server:
port/iocm/app/signaltrans/v1.1.0/devices/{deviceId}/services/Discovery/sendCommand?
appId={appId}
Header：
"app_key:
{appId}"
"Authorization:
Bearer{accessToken}"
Content-Type:
application/json;
Body:
{
"header":
{
"mode":
"ACK",
"from":
"************",
"to":
null,
"toType":
null,
"method":
"DISCOVERY",
"requestId":
"*****************************************",
"callbackURL":
"https:
//server:
port/na/iocm/message/confirm"
},
"body":
{
"from":
"************",
"sessionID":
"**********",
"sdp":
"**********"
}
}
response：
StatusCode:
202Accepted
Content-Type:
application/json
Body:
{
"requestId":
"*****************************************",
"status":
"sent",
"timestamp":
"1446202014815"
}
异常返回码
HttpStatusCode
error_code
error_desc
说明
401
100002
Invalidaccesstoken.
错误的token信息
400
100022
Theinputisinvalid.
输入参数无效
200
100203
Theapplicationisnotexisted.
应用不存在
200
100217
Theapplicationhasn'tbeenauthorized.
应用未授权
200
100418
ThedeviceDataisnotexisted.
设备数据不存在
500
100023
ThedataindataBaseisabnomal.
数据库中数据异常
400
102203
CommandNameisinvalid.
命令名称无效
200
100431
TheserviceTypeisnotexist.
服务类型不存在
200
100428
The
升级会员 