Subscribing to Service Data
Typical Scenario
An application can subscribe to service data of a device on the platform. When the service data changes (for example, the device is registered, the device reports data, and the device status changes), the platform can push change notifications to the application. The application can call this API to subscribe to different types of service change notifications.
API Function
This API is used by an application to subscribe to service change notifications on the platform. When the device status or data changes, the platform pushes notifications to the application.
API Description
1 | SubscriptionDTO subDeviceData(SubDeviceDataInDTO sddInDTO, String ownerFlag, String accessToken) throws NorthApiException
|
Parameter Description
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| sddInDTO | Mandatory | SubDeviceDataInDTO structure | body | For details, see SubDeviceDataInDTO structure. |
| ownerFlag | Mandatory | String(256) | query | Identifies the owner of the callback URL. If this parameter is not specified, this parameter can be set to null.
|
| 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. |
SubDeviceDataInDTO structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| notifyType | Mandatory | String | body | Indicates the notification type based on which an application can process messages.
|
| callbackUrl | Mandatory | String(1024) | body | Indicates the callback URL of a subscription, which is used to receive notifications of the corresponding type. This URL must be an HTTPS channel callback URL and contain its port. An example value is https://XXX.XXX.XXX.XXX:443/callbackurltest. NOTE: The HTTP channel can be used only for commissioning. |
| appId | Optional | String(256) | body | Identifies the application of the entity that subscribes to a device or rule. |
| channel | Optional | String(32) | Body | Indicates the transmission channel. For the MQTT client, the value is MQTT. In other cases, the value is HTTP. |
Response Parameters
SubscriptionDTO
| Parameter | Type | Description |
|---|---|---|
| subscriptionId | String | Identifies a subscription. |
| notifyType | String | Indicates the notification type. |
| callbackUrl | String | Indicates the callback URL of the subscription. |
| clientIds | List<String> | Identifies an MQTT client. The value is that returned when MQTT is subscribed to. |
Error Codes
| HTTP Status Code | Error Code | Error Description | Remarks |
|---|---|---|---|
| 400 | 100222 | The request callback URL is invalid. | The callback URL is invalid. Recommended handling: Check whether the callback URL in the request body is correct. |
| 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. |
| 409 | 100227 | A resource conflict occurs. | A resource conflict occurs. The notification type has been subscribed to. Recommended handling: Check whether the notification type has been subscribed. |
Last Article: Subscription Management
Next Article: Subscribing to Device Management Data
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.