Querying Service Capabilities of a Device
Typical Scenario
If an application needs to know which service properties can be reported by a device and which commands can be delivered to the device, the application can call this API to query the device service capabilities defined in the product model of the device on the platform.
API Function
This API is used by an application to query device service capabilities, such as service properties and device commands.
API Description
1 | QueryDeviceCapabilitiesOutDTO queryDeviceCapabilities(QueryDeviceCapabilitiesInDTO qdcInDTO, String accessToken) throws NorthApiException
|
Parameter Description
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| qdcInDTO | Mandatory | QueryDeviceCapabilitiesInDTO structure | query | For details, see QueryDeviceCapabilitiesInDTO 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. |
QueryDeviceCapabilitiesInDTO structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| gatewayId | Optional | String | query | Identifies a gateway. |
| 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. |
| deviceId | Optional | String | query | Identifies a device. |
Response Parameters
QueryDeviceCapabilitiesOutDTO structure
| Parameter | Type | Description |
|---|---|---|
| deviceCapabilities | List<DeviceCapabilityDTO> | Indicates the query result list. For details, see DeviceCapabilityDTO structure. |
| Parameter | Type | Description |
|---|---|---|
| deviceId | String(256) | Identifies a device. |
| serviceCapabilities | List<ServiceCapabilityDTO> | Indicates the service capability list. For details, see ServiceCapabilityDTO structure. |
ServiceCapabilityDTO structure
| Parameter | Type | Description |
|---|---|---|
| serviceId | String(256) | Identifies a service. |
| serviceType | String(256) | Indicates the service type. |
| option | String(256) | Indicates a service option. |
| description | String(10240) | Indicates the service description. |
| commands | List<ServiceCommand> | Indicates the supported commands. For details, see ServiceCommand structure. |
| properties | List<ServiceProperty> | Indicates the property list. For details, see ServiceProperty structure. |
| Parameter | Type | Description |
|---|---|---|
| commandName | String(256) | Indicates the command name. |
| paras | List<ServiceCommandPara> | Indicates the property list. For details, see ServiceCommandPara structure. |
| responses | List<ServiceCommandResponse> | Indicates the response list. For details, see ServiceCommandResponse structure. |
| Parameter | Type | Description |
|---|---|---|
| paraName | String(256) | Indicates the parameter name. |
| dataType | String(256) | Indicates the data type. |
| required | Boolean | Indicates whether the parameter is mandatory. |
| min | String | Indicates the minimum value of the property. |
| max | String | Indicates the maximum value of the property. |
| step | Double | Indicates the step. |
| maxLength | Integer | Indicates the maximum length. |
| unit | String | Indicates the unit (symbol). |
| enumList | List<String> | Indicates the enumeration type list. |
ServiceCommandResponse structure
| Parameter | Type | Description |
|---|---|---|
| responseName | String(256) | Indicates the response name. |
| paras | List<ServiceCommandPara> | Indicates the property list. For details, see ServiceCommandPara structure. |
| Parameter | Type | Description |
|---|---|---|
| propertyName | String(256) | Indicates the property name. |
| dataType | String(256) | Indicates the data type. |
| required | Boolean | Indicates whether the parameter is mandatory. |
| min | String | Indicates the minimum value of the property. |
| max | String | Indicates the maximum value of the property. |
| step | Double | Indicates the step. |
| maxLength | Integer | Indicates the maximum length. |
| method | String(256) | Indicates the access method. The values are as follows:
|
| unit | String | Indicates the unit (symbol). |
| enumList | List<String> | Indicates the enumeration type list. |
Error Codes
| HTTP Status Code | Error Code | Error Description | Remarks |
|---|---|---|---|
| 400 | 100022 | An input parameter is invalid. | An input parameter is invalid. Recommended handling: Check whether parameters carried in the API call request are valid. |
| 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 Historical Device Shadow Data
Next Article: Subscription Management
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.