中国电信物联网开放平台API参考131.docx

1、中国电信物联网开放平台API参考131中国电信物联网开放平台API参考1.3.1（V1） 二一九年三月编制单位：编制单位 修订记录：版本号日期描述012017/11/06中国电信物联网开放平台API参考1.3.1目 录1 Platform API参考(北向) 11.1 前言 11.2 接口列表 11.2.1 应用安全接入 21.2.1.1 Auth(鉴权) 21.2.1.2 Refresh Token(刷新 token) 31.2.1.3 注销 51.2.2 设备管理 61.2.2.1 注册直连设备 61.2.2.2 发现非直连设备 81.2.2.3 查询设备激活状态 111.2.2.4 删除

2、直连设备 131.2.2.5 删除非直连设备 141.2.2.6 修改设备信息 171.2.2.7 刷新设备密钥 191.2.2.8 设置加密 211.2.3 数据采集 231.2.3.1 按条件批量查询设备信息列表 231.2.3.2 查询单个设备信息 271.2.3.3 Application 订阅平台数据 291.2.3.4 查询设备历史数据 301.2.3.5 查询设备能力 351.2.4 信令传送 381.2.4.1 创建设备命令V4 381.2.4.2 查询设备命令V4 411.2.4.3 修改设备命令V4 451.2.4.4 创建设备命令撤销任务V4 471.2.4.5 查询设备

3、命令撤销任务V4 501.2.5 设备服务调用 551.2.5.1 设备服务调用 551.2.6 批量处理 581.2.6.1 创建批量任务 581.2.6.2 查询单个任务信息 611.2.6.3 查询任务详情信息 631.2.7 规则 661.2.7.1 创建规则 661.2.7.2 更新规则 791.2.7.3 修改规则状态 831.2.7.4 删除规则 841.2.7.5 查找规则 851.2.7.6 批量修改规则状态 871.2.8 消息推送 901.2.8.1 注册直连设备的通知 901.2.8.2 发现非直连设备的通知 921.2.8.3 设备信息变化的通知 931.2.8.4

4、设备数据变化的通知 941.2.8.5 删除非直连设备的通知 951.2.8.6 消息确认通知 961.2.8.7 设备响应命令通知 981.2.8.8 设备事件通知 1001.2.8.9 设备服务上报通知 1021.2.8.10 规则事件上报通知 1031.2.8.11 绑定设备通知 1051.2.8.12 批量设备数据变化上报通知 1071.3 常用数据结构体定义 1081.3.1 DeviceInfo结构体说明 1081.3.2 DeviceService结构体说明 1101.3.3 QueryDeviceDTOCloudNA结构体说明 1101.3.4 ServiceCommand结构

5、体说明 1101.3.5 ServiceProperty结构体说明 1111.3.6 DeviceCommandResp 结构体说明 1121.3.7 CommandDTOV4 结构体说明 1131.3.8 GetDeviceRspDTO 结构体说明 1131.3.9 CommandNA2CloudHeader结构体说明 1141.3.10 ApplicationSetEncrtptDTO结构体说明 1141.3.11 PutCarInfoData结构体说明 1141 Platform API参考(北向)1.1 前言1.2 接口列表1.3 常用数据结构体定义1.1 前言本文档系统化描述IoT

6、Platform（下文简称平台）对外开放的能力全集、集成原理和集成参考样例等信息，帮助集成开发者快速而准确的掌握集成方法从而高效实现特定的业务需求。本文档主要包含如下几个部分：一接口列表主要描述能力开放的接口集合，详细介绍每个接口的功能、输入参数、输出参数、和消息样例等信息。二常用数据结构定义是对多个接口都会用到的数据结构做一个详细介绍，方便开发者集中查看。1.2 接口列表Application侧接口除了鉴权接口Auth，其他接口调用都需要在request header中携带参数app_key和Authorization:Bearer accessToken。Authorization中acc

7、essToken的值即为调用Auth接口获取到的accessToken。应用开发语言若是JAVA请使用JDK1.8。北向提供的API 是平台与Application之间的https接口， 请使用安全传输协议TLS 1.1/1.2。1.2.1 应用安全接入Application携带在IoT Platform（下文简称平台）产生的appId和secret过来，调用鉴权接口，获取鉴权token。请参考本文档 2.1.1鉴权章节进行开发。1.2.1.1 Auth(鉴权)接口功能实现第三方系统在访问开放API之前的认证。调用方法POST接口路径https:/server:port/iocm/app/se

8、c/v1.1.0/login注意事项鉴权接口是调用其他API的前提，北向接口除了鉴权接口（Auth），其他接口调用都需要在request header中携带参数app_key和Authorization:Bearer accessToken。app_key为参数中的appId，Authorization中accessToken的值即为调用Auth接口获取到的accessToken。如果多次获取令牌，则之前的令牌失效, 最后一次获取的令牌才有效。请勿并发获取令牌。参数说明参数必选/可选类型描述appId必选String用户名，填写应用程序IDsecret必选String登录用户口令，填写应用程序

9、密码返回结果字段类型描述scopeString范围，默认值defaulttokenTypeString鉴权token类型，默认值bearerexpiresInInteger平台生成并返回accessToken的有效时间，单位秒accessTokenStringOauth 2.0 鉴权参数refreshTokenStringOauth 2.0 鉴权参数，用来刷新accessToken。（1个月的有效期）消息事例Method：POSTrequest：(非JSON格式)https:/server:port/iocm/app/sec/v1.1.0/login Content-Type:applicat

10、ion/x-www-form-urlencoded Body: appId=appId&secret=secretresponse：Status Code: 200 OK Content-Type: application/json Body: scope:default, tokenType:bearer, expiresIn:*, accessToken:*, refreshToken:* 异常返回码Http Status Codeerror_codeerror_desc说明401100208AppId or secret is not right. appId或secret错误1.2.1

11、.2 Refresh Token(刷新 token)接口功能accessToken快过期时，第三方系统通过调用此接口，重新获取可用token。accessToken有效时间参照2.1.1鉴权接口返回字段expiresIn的值。调用方法POST接口路径https:/server:port/iocm/app/sec/v1.1.0/refreshToken注意事项Body参数说明参数必选/可选类型描述appId必选String用户名，填写应用程序IDsecret必选String登录用户口令，填写应用程序密码refreshToken必选String刷新令牌，用于获取一个新的accessToken返回结

12、果字段类型描述scopeString范围tokenTypeString鉴权token类型，默认值bearerexpiresInString平台生成并返回accessToken的有效时间，单位秒accessTokenStringOauth 2.0 鉴权参数refreshTokenString刷新令牌，用于获取一个新的accessToken消息事例Method：POSTrequest：https:/server:port/iocm/app/sec/v1.1.0/refreshToken Content-Type:application/json Body: appId=*, secret=*, r

13、efreshToken:* response：Status Code: 200 OK Content-Type: application/json Body: accessToken:*, tokenType:*, expiresIn:*, scope:”*”, refreshToken:* 异常返回码Http Status Codeerror_codeerror_desc说明400100022The input is invalid.输入参数无效401100006Refresh access token failed. refreshToken无效401100208AppId or secr

14、et is not right. appId或secret错误1.2.1.3 注销接口功能NA注销鉴权信息。调用方法POST接口路径https:/server:port/iocm/app/sec/v1.1.0/logout注意事项无参数说明参数必选/可选类型描述accessToken必选String(256)调用鉴权接口获取到的Oauth 2.0 鉴权参数返回结果Status Code: 204 No Content消息事例Method: POSTRequest:https:/server:port/iocm/app/sec/v1.1.0/logout Header： Content-Type

15、:application/json Body: accessToken: * Response:Status Code: 204 No Content Content-Type: application/json 异常返回码Http Status Codeerror_codeerror_desc说明400100022The input is invalid. 输入参数无效1.2.2 设备管理设备管理提供了Application（下文简称App）申请设备的增，删，改，查以及修改设备基本信息的接口。App向IoT Platform申请新的设备, IoT Platform分配对应的设备验证码，待设备

16、携带验证码请求接入平台后，分配其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:a

17、pplication/json;备注：app_key为参数中的appId，Authorization中accessToken的值即为调用Auth接口获取到的accessToken。参数说明字段必选/可选类型描述appId可选String应用唯一标识verifyCode可选String客户端给出verifyCode则返回的就是这个verifyCode，即使用客户端给出的verifyCode。如果不指定，系统自动生成。nodeId必选String设备唯一标识, 如：MAC或SIM卡号或设备esn号等。与设备对接时，必须与设备上报的nodeId一致。备注：nodeId和verifyCode需要填写相

18、同的值，如果南向连接SoftRadio的模拟环境，该值可自行定义，格式为TESTS_XXXXXX。如果是现网环境，该值通常为设备的IMEI号。endUserId可选String终端用户Id，如手机号码，email地址psk可选Stringpsk码，用于生成设备鉴权参数；如不传入，系统自动生成timeout可选Integer单位秒，不填使用默认值(180s), 填写0则永不过期，非0表示在指定时间内设备进行绑定，超过时间验证码无效返回结果字段类型描述deviceIdString设备唯一标识，1-64个字节verifyCodeString申请的临时验证码，设备可以通过验证码获取id和密码timeo

19、utInteger验证码有效时间，单位秒，设备需要在有效时间内接入平台pskStringpsk码，用于生成设备鉴权参数消息事例Method：POSTrequest：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 r

20、esponse：Status Code: 200 OK Content-Type: application/json Body: deviceId:*, verifyCode:*, timeout:300, psk:* 异常返回码Http Status Codeerror_codeerror_desc说明401100002Invalid access token.错误的token信息400100022The input is invalid. 输入参数无效401100025AppId for auth not exist. 获取不到appId鉴权信息200100203The applicati

21、on is not existed. 应用不存在200100217The application hasnt been authorized. 应用未被授权400100007Bad request message. 参数不合法200100412The amount of device has reached the limit.当前应用下设备数量达到上限400100003Invalid verify code. 验证码无效200100416The device has already been binded. 设备已经绑定500100001Internal server error. 服务内部

22、处理错误200103026The license is not exist. License不存在200103028The license pool resources. License无资源200103027The license sales is not exist. License的销售项不存在1.2.2.2 发现非直连设备接口功能Application发送DISCOVERY命令给网关下的设备。一般用于通过网关添加传感器，若没有网关，该接口请勿使用。调用方法POST接口路径https:/server:port/iocm/app/signaltrans/v1.1.0/devices/dev

23、iceId/services/serviceId/sendCommand?appId=appId注意事项http携带头域信息： Header： app_key:appId Authorization:Bearer accessToken Content-Type:application/json;URL参数说明：字段必选/可选类型描述deviceId必选String网关设备唯一标识，1-64个字节serviceId必选String取值Discoveryhttp消息体说明：字段必选/可选类型描述appId可选String应用唯一标识message必选CommandDTONA2CloudComma

24、ndDTONA2Cloud消息体说明参见下表CommandDTONA2Cloud消息体说明：字段必选/可选类型描述header必选CommandNA2CloudHeader见附录1.3.9 CommandNA2CloudHeader结构体说明字段说明body可选ObjectNode取值长度无要求，消息的消息体返回结果：字段类型描述statusString(128)命令状态：sent - 已发送、delivered - 已送达executed - 已执行timestampString(128)发送命令的时间戳，1-32字节时间格式：yyyyMMddTHHmmssZ 如： 20151212T121

25、212ZrequestIdString(128)1-32个字节，平台分配的序列号，标识一个命令需要requestId关联对应命令执行结果消息事例Method：POSTrequest：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: mo

26、de: ACK, from: *, to: null, toType: null, method: DISCOVERY, requestId: *, callbackURL: https:/server:port/na/iocm/message/confirm , body: from: *, sessionID: *, sdp: * response：Status Code: 202 Accepted Content-Type: application/json Body: requestId:*, status:sent, timestamp:1446202014815 异常返回码Http

27、 Status Codeerror_codeerror_desc说明401100002Invalid access token. 错误的token信息400100022The input is invalid. 输入参数无效200100203The application is not existed. 应用不存在200100217The application hasnt been authorized. 应用未授权200100418The deviceData is not existed. 设备数据不存在500100023The data in dataBase is abnomal. 数据库中数据异常400102203CommandName is invalid. 命令名称无效200100431The serviceType is not exist. 服务类型不存在200100428The