更新时间:2022-02-24 GMT+08:00

查询设备服务能力

典型场景

应用服务器若需要了解设备可上报哪些服务属性数据,以及设备支持下发哪些命令,可调用此接口在物联网平台查询设备的Profile文件中定义的设备服务能力信息。

接口功能

支持应用服务器在物联网平台查询设备的服务属性、设备命令等服务能力信息。

接口原型

请求方法

GET

请求地址

https://server:port/iocm/app/data/v1.1.0/deviceCapabilities?appId={appId}&gatewayId={gatewayId}&deviceId={deviceId}

传输协议

HTTPS

请求参数

参数

必选/可选

类型

位置

描述

app_key

必选

String

header

访问物联网平台的应用ID,在物联网平台创建应用时由平台分配获得。

Authorization

必选

String

header

访问物联网平台的认证信息,值为“Bearer {accessToken}”,其中{accessToken}为调用鉴权接口返回的accessToken。

gatewayId

可选

String

query

网关ID,用于标识一个网关设备。当设备是直连设备时,gatewayId与设备的deviceId一致。当设备是非直连设备时,gatewayId为设备所关联的直连设备(即网关)的deviceId。

appId

可选

String

query

访问物联网平台的应用ID,在物联网平台创建应用时由平台分配获得。此处填写授权应用的appId。

deviceId

可选

String

query

设备ID,用于唯一标识一个设备,在注册设备时由物联网平台分配获得。

响应参数

参数

类型

描述

deviceCapabilities

List<DeviceCapabilityDTO>

查询结果列表。

DeviceCapabilityDTO:

参数

类型

描述

deviceId

String(256)

设备ID,用于唯一标识一个设备,在注册设备时由物联网平台分配获得。

serviceCapabilities

List<ServiceCapabilityDTO>

设备的服务能力列表。

ServiceCapabilityDTO:

参数

类型

描述

serviceId

String(256)

设备的服务标识。

serviceType

String(256)

设备的服务类型。

option

String(256)

服务选项。

description

String(10240)

设备服务描述信息。

commands

List<ServiceCommand>

支持的命令名称列表。

properties

List<ServiceProperty>

支持的属性名称列表。

ServiceCommand:

参数

类型

描述

commandName

String(256)

命令名称。

paras

List<ServiceCommandPara>

属性列表。

responses

List<ServiceCommandResponse>

响应列表。

ServiceCommandPara:

参数

类型

描述

paraName

String(256)

参数名称。

dataType

String(256)

数据类型。

required

Boolean

是否必选。

min

String

属性最小值。

max

String

属性最大值。

step

Double

步长。

maxLength

Integer

最大长度。

unit

String

单位(符号)。

enumList

List<String>

枚举类型列表。

ServiceCommandResponse:

参数

类型

描述

responseName

String(256)

响应名称。

paras

List<ServiceCommandPara>

属性列表。

ServiceProperty:

参数

类型

描述

propertyName

String(256)

属性名称。

dataType

String(256)

数据类型。

required

Boolean

是否必选。

min

String

属性最小值。

max

String

属性最大值。

step

Double

步长。

maxLength

Integer

最大长度。

method

String(256)

访问方法。

  • R:可读
  • W:可写
  • E:可观察

unit

String

单位(符号)。

enumList

List<String>

枚举类型列表。

请求示例

Method: GET
request:
https://server:port/iocm/app/data/v1.1.0/deviceCapabilities?appId={appId}&gatewayId={gatewayId}&deviceId={deviceId}
Header:
app_key: ******
Authorization: Bearer *****
Content-Type: application/json

响应示例

response:
Status Code: 200 OK
Content-Type: application/json
Body:
{
    "deviceCapabilities":[
        {
            "deviceId":"****",
            "serviceCapabilities":[
                {
                    "serviceId":"****",
                    "serviceType":"****",
                    "option":"****",
                    "description":"****",
                    "commands":[
                        {
                            "commandName":"*****",
                            "paras":[
                                {
                                    "paraName":"*****",
                                    "dataType":"*****",
                                    "required":"Ture",
                                    "min":"*****",
                                    "max":"*****",
                                    "step":"*****",
                                    "maxLength":1111111,
                                    "unit":"*****",
                                    "enumList":[
                                        {

                                        }
                                    ]
                                }
                            ],
                            "responses":[
                                {
                                    "responseName":"***",
                                    "paras":[
                                        {
                                            "paraName":"*****",
                                            "dataType":"*****",
                                            "required":"Ture",
                                            "min":"*****",
                                            "max":"*****",
                                            "step":"*****",
                                            "maxLength":1111111,
                                            "unit":"*****",
                                            "enumList":[
                                                {

                                                }
                                            ]
                                        }
                                    ]
                                }
                            ],
                            "properties":[
                                {
                                    "propertyName":"*****",
                                    "dataType":"*****",
                                    "required":"Ture",
                                    "min":"*****",
                                    "max":"*****",
                                    "step":"*****",
                                    "maxLength":1111111,
                                    "method":"*****",
                                    "unit":"*****",
                                    "enumList":[
                                        {

                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

错误码

Http状态码

错误码

错误描述

说明

400

100022

The input is invalid.

输入参数无效。

处理建议:请检查接口调用请求中携带参数的合法性。

403

100203

The application is not existed.

应用不存在。

处理建议:

  • 请检查HTTP请求头域中携带的appId是否有误。
  • 请检查请求路径(url)中传入的appId是否有误。

403

100217

The application hasn't been authorized.

应用未被授权。

处理建议:若非应用授权场景,请确认请求参数中的appId为空。

403

1010009

app throttle exceed.

应用调用接口过于频繁,超过流控值(默认值是100次/60s)。

处理建议:联系物联网平台维护人员调大流控阈值或者控制接口的调用频率。

403

1010005

App_key or access_token is invalid.

错误的token信息。

处理建议:请检查接口请求中所携带的accessToken是否有误。

500

100203

The application is not existed.

应用不存在。

处理建议:

  • 请检查HTTP请求头域中携带的appId是否有误。
  • 请检查请求路径(url)中传入的appId是否有误。

500

50252

Internal server error.

服务器运行内部错误。

处理建议:物联网平台内部错误,请联系物联网平台维护人员处理。