文档首页/ IoT物联网/ API参考/ 应用侧API参考（联通用户专用）/ 数据采集/ 查询单个设备信息
更新时间：2023-04-13 GMT+08:00
查看PDF
分享

查询单个设备信息

接口说明

已在物联网平台注册的设备，应用服务器若需要查看某个设备的详细信息（如厂商、型号、版本、状态和服务属性等信息），可调用此接口在物联网平台查询获取。

URI

请求方法

GET

URI

/iocm/app/dm/v1.4.0/devices/{deviceId}

传输协议

HTTPS

请求参数

参数

必选/可选

类型

位置

描述

app_key

必选

String

header

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

Authorization

必选

String

header

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

deviceId

必选

String

path

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

appId

可选

String

query

设备所属的应用ID，当查询授权应用下的设备信息时才需要填写。

select

可选

String

query

指定查询条件，可选值：imsi。

响应参数

Status Code: 200 OK

参数

类型

描述

deviceId

String(256)

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

gatewayId

String(256)

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

nodeType

Enum

节点类型，取值：ENDPOINT/GATEWAY/UNKNOW。

createTime

String(256)

创建设备的UTC时间，时间格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

若需要显示本地时区时间，您需要自己进行时间转换。

lastModifiedTime

String(256)

最后修改设备的UTC时间，时间格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

若需要显示本地时区时间，您需要自己进行时间转换。

deviceInfo

DeviceInfoQueryDTO

设备信息。

services

List<DeviceService>

设备服务列表。

alarmInfo

AlarmInfoDTO

设备告警信息。

DeviceInfoQueryDTO：

参数

类型

描述

nodeId

String(256)

设备唯一标识码。

name

String(256)

设备名称。

description

String(2048)

设备的描述信息。

manufacturerId

String(256)

厂商ID，唯一标识一个厂商。

manufacturerName

String(256)

厂商名称。

mac

String(256)

设备的MAC地址。

location

String(2048)

设备的位置信息。

deviceType

String(256)

设备类型，大驼峰命名方式，如MultiSensor、ContactSensor、CameraGateway。

model

String(256)

设备的型号。

swVersion

String(256)

设备的软件版本。

fwVersion

String(256)

设备的固件版本。

hwVersion

String(256)

设备的硬件版本。

imsi

String

NB-IoT终端的IMSI。

protocolType

String(256)

设备使用的协议类型。

radiusIp

String

Radius地址。

bridgeId

String(256)

Bridge标识，表示设备通过哪个Bridge接入物联网平台。

status

String

设备的状态，表示设备是否在线，取值范围：ONLINE、OFFLINE、INACTIVE、ABNORMAL。

  • 设备首次接入平台之前，设备的状态为INACTIVE。
  • 若设备超过25（默认值）小时未向平台上报数据或发送消息，则设备状态为ABNORMAL（默认值）；若设备超过49小时未向平台上报数据或发送消息，则设备状态为OFFLINE。

statusDetail

String(256)

设备的状态详情，跟status取值对应。

  • status为ONLINE时，取值范围为NONE（无），CONFIGURATION_PENDING（配置待下发），UE_REACHABILITY（设备可达），AVAILABILITY_AFTER_DDN_FAILURE（寻呼失败后设备重新可达）。
  • status为OFFLINE时，取值范围为NONE（无），COMMUNICATION_ERROR（通信故障），CONFIGURATION_ERROR（配置错误），BRIDGE_OFFLINE（Bridge离线），FIRMWARE_UPDATING（固件升级中），DUTY_CYCLE，NOT_ACTIVE（未激活），LOSS_OF_CONNECTIVITY（连接断开），TIME_OUT（超时）。
  • status为INACTIVE时，取值范围为NONE（无），NOT_ACTIVE（未激活）。

mute

String

表示设备是否处于冻结状态，即设备上报数据时，平台是否会管理和保存。

  • TRUE：冻结状态
  • FALSE：非冻结状态

supportedSecurity

String

表示设备是否支持安全模式。

  • TRUE：支持安全模式
  • FALSE：不支持安全模式

isSecurity

String

表示设备当前是否启用安全模式。

  • TRUE：启用
  • FALSE：未启用

signalStrength

String(256)

设备的信号强度。

sigVersion

String(256)

设备的sig版本。

serialNumber

String(256)

设备的序列号。

batteryLevel

String(256)

设备的电池电量。

设备向物联网平台上报设备状态时需要status、statusDetail成对上报。statusDetail建议仅用作显示，不建议用于逻辑判断。

DeviceService：

参数

类型

描述

serviceId

String(256)

设备的服务标识。

serviceType

String(256)

设备的服务类型。

serviceInfo

ServiceInfo

设备的服务信息。

data

ObjectNode(2097152)

属性值对。

eventTime

String(256)

事件发生的UTC时间，时间格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

若需要显示本地时区时间，您需要自己进行时间转换。

ServiceInfo：

参数

类型

描述

muteCmds

List<String>

屏蔽的设备控制命令列表

AlarmInfoDTO：

参数

类型

描述

alarmSeverity

String

告警级别。

alarmStatus

Boolean

告警状态。

alarmTime

String

告警上报UTC时间，时间格式：yyyyMMdd'T'HHmmss'Z'，如20151212T121212Z。

若需要显示本地时区时间，您需要自己进行时间转换。

请求示例

GET https://{host}:{port}/iocm/app/dm/v1.4.0/devices/{deviceId}?select=imsi
Content-Type: application/json
app_key: ******
Authorization: Bearer *****

正常响应示例

Status Code: 200 OK
Content-Type: application/json

{
  "deviceId": "xxxxx",
  "gatewayId": "xxxxx",
  "nodeType": "xxxxx",
  "deviceInfo": {
    "nodeId": "123456",
    "name": "Sensor_12",
    "manufacturerName": "wulian",
    "deviceType": "gateway",
    "model": "90",
    "mac": "C7EA1904004B1204",
    "swVersion": "th",
    "fwVersion": "seu",
    "hwVersion": "sru",
    "protocolType": "zigbee",
    "description": "smockdetector",
    "imsi": "xxxxx"
  },
  "services": [
    {
      "serviceType": "air_conditioner",
      "serviceId": "1",
      "data"{
        "battery_low": 1
      }
    },
    {
      "serviceType": "air_conditioner",
      "serviceId": "jkh",
      "data": {
        "battery_low": "jhj"
      }
    }
  ]
}

错误码

Http状态码

错误码

错误描述

说明

400

100405

The request parameter 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

Invalid access token or appId.

错误的token信息。

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

404

100403

The device is not existed.

设备不存在。

处理建议：物联网平台未找到deviceId对应的设备，请检查deviceId是否有误。

404

100418

The deviceData is not existed.

设备信息不存在。

处理建议：

  • 请求参数中携带的deviceId错误。请确认该deviceId是否属于该appId或者deviceId是否写错。
  • Header中携带的appId有误，请确认该appId下是否有该deviceId。
  • 如果URL中携带了可选参数appId，请检查该appId是否有误。

500

100203

The application is not existed.

应用不存在。

处理建议：

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

500

50252

Internal server error.

服务器运行内部错误。

处理建议：物联网平台内部错误，请联系物联网平台维护人员处理。
父主题： 数据采集

相关文档