Help Center > > API Reference> Northbound API Reference> Subscription Management> Subscribing to Service Data of the IoT Platform

Subscribing to Service Data of the IoT Platform

Updated at: Aug 28, 2019 GMT+08:00

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 or the device status changes), the IoT platform can push change notifications to the NA.

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 Prototype

Method

POST

URL

https://server:port/iocm/app/sub/v1.2.0/subscriptions?ownerFlag={ownerFlag}

Transport Protocol

HTTPS

Request Parameters

Parameter

Mandatory or Optional

Type

Location

Description

app_key

Mandatory

String

header

Identifies an application that can be accessed on the IoT platform. The value of this parameter is allocated by the IoT platform when the application is created on the platform.

Authorization

Mandatory

String

header

Indicates the authentication information for accessing the IoT platform. The value is Bearer {accessToken}, in which {accessToken} indicates the access token returned by the Authentication API.

ownerFlag

Optional

String(256)

query

Indicates the owner flag of the callback URL.

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

appId

Optional

String(256)

body

Identifies an application that can be accessed on the IoT platform. The value of this parameter is allocated by the IoT platform when the application is created on the platform. Set this parameter to the value of appId of the authorized application.

notifyType

Mandatory

String

body

Indicates the notification type based on which an NA can receive notifications pushed by the IoT platform.

  • deviceAdded: device addition; sending such a notification after subscription
  • bindDevice: device binding; 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
  • deviceCapabilitiesChanged: device service capability change; sending such a notification after subscription
  • deviceCapabilitiesAdded: device service capability added; sending such a notification after subscription
  • deviceCapabilitiesDeleted: device service capability deleted; sending such a notification after subscription
  • deviceDeleted: device deletion; sending such a notification after subscription
  • messageConfirm: message confirmation; sending such a notification after subscription (This function applies only to devices that use the MQTT protocol for access.)
  • commandRsp: command response; sending such a notification after subscription. (This function applies only to devices that use the MQTT protocol for access.)
  • ruleEvent: rule event; 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.

HTTPS or HTTP callback URL can be used. HTTPS is recommended. The callback URL can be a combination of an IP address or a domain name and a port number. An example value is https://XXX.XXX.XXX.XXX:443/callbackurltest.

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

Status Code: 201 Created

Parameter

Type

Description

subscriptionId

String

Uniquely identifies a subscription. The value of this parameter is allocated by the IoT platform during subscription creation.

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.

Request Example

Method: POST
request: https://server:port/iocm/app/sub/v1.2.0/subscriptions
Header:
app_key: ******
Authorization: Bearer *****
Content-Type: application/json
Body:
{
  "appId": "*******",
  "notifyType": "deviceInfoChanged",
  "callbackUrl": "https://***********"
}

Response Example

Response:
Status Code: 201 Created
Content-Type: application/json
Body:
{
  "subscriptionId": "*******",
  "notifyType": "*******",
  "callbackUrl": "https://***********"
}

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.

Did you find this page helpful?

Submit successfully!

Thank you for your feedback. Your feedback helps make our documentation better.

Failed to submit the feedback. Please try again later.

Which of the following issues have you encountered?







Please complete at least one feedback item.

Content most length 200 character

Content is empty.

OK Cancel