Subscribing to Service Data of the IoT Platform

Typical Scenario

An NA can subscribe to service data of a device on the IoT platform. When the service data changes (for example, the device is registered, the device reports data and the device status changes), the IoT platform can push change notifications to the NA. The NA can call this API to subscribe to different types of service change notifications.

API Function

This API is used by an NA to subscribe to service change notifications on the IoT platform. When the device status or data changes, the IoT platform pushes notifications to the NA.

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 callbackUrl. If this parameter is not specified, this parameter can be set to null. false: The callback URL owner is an authorizing application. true: The callback URL owner is an authorized application.
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.

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 callbackUrl. If this parameter is not specified, this parameter can be set to null.

false: The callback URL owner is an authorizing application.
true: The callback URL owner is an authorized application.

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 NA can process messages. bindDevice: device binding; sending such a notification after subscription deviceAdded: device addition; sending such a notification after subscription deviceInfoChanged: device information change; sending such a notification after subscription deviceDataChanged: device data change; sending such a notification after subscription deviceDatasChanged: batch device data change; sending such a notification after subscription deviceDeleted: device deletion; sending such a notification after subscription messageConfirm: message confirmation; sending such a notification after subscription commandRsp: command response; sending such a notification after subscription deviceEvent: device event; sending such a notification after subscription serviceInfoChanged: service information change; sending such a notification after subscription deviceModelAdded: device model addition; sending such a notification after subscription deviceModelDeleted: device model deletion; sending such a notification after subscription deviceDesiredPropertiesModifyStatusChanged: device shadow modification status change; sending such a notification after subscription
callbackUrl	Mandatory	String(1024)	body	Indicates the callback URL of a subscription, which is used to receive notification messages of the corresponding type. This URL must be an HTTPS channel callback URL and contain its port number. 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 callbackurl is illegal.	The callback URL is invalid. Recommended handling: Check whether the callback URL in the request body is correct.
403	100217	The application hasn't 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	app throttle exceed.	The NA 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	App_key or access_token is invalid.	The access token is invalid. Recommended handling: Check whether accessToken carried in the API request is correct.
409	100227	The resource is conflicted.	A resource conflict occurs. The notification type has been subscribed to. Recommended handling: Check whether the notification type has been subscribed.