Querying a Device Information List
Typical Scenario
If an application needs to view detailed information (such as the manufacturer, model, version, status, and service properties) of multiple devices that have been registered with the platform, the application can call this API to obtain the information.
API Function
This API is used by an application to query detailed information (such as configuration, status, and service properties) of multiple devices based on specified conditions on the platform.
API Description
1 | QueryBatchDevicesInfoOutDTO queryBatchDevicesInfo(QueryBatchDevicesInfoInDTO qbdiInDTO, String accessToken) throws NorthApiException
|
Parameter Description
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| qbdiInDTO | Mandatory | QueryBatchDevicesInfoInDTO | query | For details, see PostDeviceCommandInDTO2 structure. |
| accessToken | Mandatory | String | header | If the Periodically Refreshing a Token API is called, set this parameter to null. Otherwise, set this parameter to the accessToken obtained by the Authentication API. |
PostDeviceCommandInDTO2 structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| appId | Mandatory | String | query | If the device belongs to the current application, set this parameter to null. Otherwise, set this parameter to the ID of the authorized application. |
| gatewayId | Optional | String | query | Identifies a gateway. |
| nodeType | Optional | String | query | Indicates the node type. The value options are ENDPOINT, GATEWAY, and UNKNOW. |
| deviceType | Optional | String | query | Indicates the type of the device. |
| pageNo | Optional | Integer | query | Indicates the page number.
|
| pageSize | Optional | Integer | query | Indicates the number of records on each page. The default value is 1. |
| status | Optional | String | query | Indicates the device status.
|
| startTime | Optional | String | query | Indicates the start time. Records with the device registration time later than the specified start time are queried. The value is in the format of yyyyMMdd'T'HHmmss'Z'. An example value is 20151212T121212Z. |
| endTime | Optional | String | query | Indicates the end time. Records with the device registration time earlier than the specified end time are queried. The value is in the format of yyyyMMdd'T'HHmmss'Z'. An example value is 20151212T121212Z. |
| sort | Optional | String | query | Indicates the sorting mode of queried records.
The default value is DESC. |
| select | Optional | String | query | Indicates the record to be returned. The value can be IMSI. |
Response Parameters
QueryBatchDevicesInfoOutDTO structure
| Parameter | Type | Description |
|---|---|---|
| totalCount | long | Indicates the number of queried records. |
| pageNo | long | Indicates the page number. |
| pageSize | long | Indicates the number of records on each page. |
| devices | List< QuerySingleDeviceInfoOutDTO> | Indicates the device pagination information list. For details, see QuerySingleDeviceInfoOutDTO structure. |
QuerySingleDeviceInfoOutDTO structure
| Parameter | Type | Description |
|---|---|---|
| deviceId | String(256) | Identifies a device. |
| gatewayId | String(256) | Identifies a gateway. The gateway ID is the same as the device ID if the device is a directly connected device. If the device is an indirectly connected device, the gateway ID is the device ID of the directly connected device (the gateway) with which the indirectly connected device associates. |
| nodeType | Enum | Indicates the node type. The value options are ENDPOINT, GATEWAY, and UNKNOW. |
| createTime | String(256) | Indicates the time when the device is created. The value is in the format of yyyyMMdd'T'HHmmss'Z'. An example value is 20151212T121212Z. |
| lastModifiedTime | String(256) | Indicates the last time when the device is modified. |
| deviceInfo | DeviceInfoQueryDTO | Indicates information about the device. For details, see DeviceInfo structure. |
| services | List<DeviceService> | Indicates the device service list. For details, see DeviceService structure. |
| Parameter | Type | Description |
|---|---|---|
| nodeId | String(256) | Identifies a device. |
| name | String(256) | Indicates the device name. |
| description | String(2048) | Indicates the device description. |
| manufacturerId | String(256) | Uniquely identifies a manufacturer. |
| manufacturerName | String(256) | Indicates the manufacturer name. |
| mac | String(256) | Indicates the MAC address of the device. |
| location | String(2048) | Indicates the device location. |
| deviceType | String(256) | Indicates the device type. The upper camel case is used, for example, MultiSensor, ContactSensor, and CameraGateway. |
| model | String(256) | Indicates the device model. In Z-Wave, the format is productType + productId. The value is a hexadecimal value in the format of XXXX-XXXX. Zeros are added if required, for example, 001A-0A12. The format in other protocols is still to be determined. |
| swVersion | String(256) | Indicates the software version of the device. In Z-Wave, the format is major version.minor version, for example, 1.1. |
| fwVersion | String(256) | Indicates the firmware version of the device. |
| hwVersion | String(256) | Indicates the hardware version of the device. |
| protocolType | String(256) | Indicates the protocol used by the device. The value options are CoAP, huaweiM2M, Z-Wave, ONVIF, WPS, Hue, WiFi, J808, Gateway, ZigBee, and LWM2M. |
| bridgeId | String(256) | Identifies the bridge through which the device accesses the platform. |
| status | String | Indicates whether the device is online. The value options are ONLINE, OFFLINE, and ABNORMAL. |
| statusDetail | String(256) | Indicates the device status details. The value of this parameter varies with the value of status. For details, see status and statusDetail structure. |
| mute | String | Indicates whether the device is in the frozen state. Based on the value of this parameter, the platform determines whether to manage and store data reported by the device.
|
| supportedSecurity | String | Indicates whether the security mode is supported.
|
| isSecurity | String | Indicates whether the security mode is enabled.
|
| signalStrength | String(256) | Indicates the signal strength of the device. |
| sigVersion | String(256) | Indicates the SIG version of the device. |
| serialNumber | String(256) | Indicates the serial number of the device. |
| batteryLevel | String(256) | Indicates the battery level of the device. |
| status | statusDetail |
|---|---|
| OFFLINE | NONE CONFIGURATION_PENDING |
| ONLINE | NONE COMMUNICATION_ERROR CONFIGURATION_ERROR BRIDGE_OFFLINE FIRMWARE_UPDATING DUTY_CYCLE NOT_ACTIVE |
When the device status information is reported to the platform, status and statusDetail must be included. It is recommended that statusDetail be used only for display but not for logical judgment.
| Parameter | Type | Description |
|---|---|---|
| serviceId | String(256) | Identifies a service. |
| serviceType | String(256) | Indicates the service type. |
| serviceInfo | ServiceInfo | Indicates the masked device service information. For details, see ServiceInfo structure. |
| data | ObjectNode(2097152) | Indicates an attribute-value pair. |
| eventTime | String(256) | The value is in the format of yyyyMMdd'T'HHmmss'Z'. An example value is 20151212T121212Z. |
| Parameter | Type | Description |
|---|---|---|
| muteCmds | List<String> | Indicates the device command list. |
Error Codes
| HTTP Status Code | Error Code | Error Description | Remarks |
|---|---|---|---|
| 400 | 100216 | The application input is invalid. | The application input is invalid. Recommended handling: Check whether parameters in the API request are correct by referring to the request parameter description. |
| 400 | 100218 | The gatewayId and pageNo cannot be both null. | The gatewayId and pageNo parameters cannot be null at the same time. Recommended handling: Check whether gatewayId or pageNo is set. |
| 400 | 100405 | The request parameter is invalid. | The request message contains invalid parameters. Recommended handling: Check whether parameters in the API request are correct by referring to the request parameter description. |
| 403 | 100203 | The application does not exist. | The application does not exist. Recommended handling:
|
| 403 | 100217 | The application has not been authorized. | The application has not been authorized. Recommended handling: In scenarios where applications are not authorized, ensure that request parameter appId is null. |
| 403 | 1010009 | The application calls the API at a frequency that exceeds the flow control threshold. | The application calls the API at a frequency that exceeds the flow control threshold (100 calls per minute by default). Recommended handling: Contact IoT platform maintenance personnel to adjust the flow control threshold or control the API call frequency. |
| 403 | 1010005 | Invalid access token or application ID. | The access token is invalid. Recommended handling: Check whether accessToken carried in the API request is correct. |
| 500 | 100203 | The application does not exist. | The application does not exist. Recommended handling:
|
| 500 | 50252 | Internal server error. | An internal server error occurs. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel. |
Last Article: Querying Information About a Device
Next Article: Querying Historical Device Data
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.