Help Center/ IoT Device Access/ FAQs/ Subscription and Push
Updated on 2024-10-31 GMT+08:00
View PDF
Share

Subscription and Push

How Do I Obtain the Callback URL When Calling the Subscription API?

The following assumes that an application tries to subscribe to device data changes. The process of subscription and push is as follows:

Figure 1 Subscription and push process
  1. The application calls an IoT platform API to subscribe to device data changes (the request carries the callback URL and notification type). The platform stores the callback URL and the notification type in the subscription list.
  2. The device reports data to the platform.
  3. The platform automatically pushes the device data to the application based on the callback URL stored during the subscription.

What Is a Callback URL?

The callback URL is the RESTful API address defined by the application for external access. When the platform pushes messages to the application, it calls the RESTful API of the application to send data to the application.

The request method of the callback URL must be POST.

How Do I Obtain a Callback URL?

The callback URL consists of the connection protocol, access address of the application, and URL of the RESTful API. An example is https://server:port/URL.

For security reasons, HTTPS is recommended for communications between the application and platform. When HTTPS is used, the platform needs to load a certificate. For details, see Creating a Commissioning Certificate.

The access address of the application depends on the network where the application is located.

  • If the application is deployed on the public network, the access address of the application is Public IP address of the application:Port (or Domain name:Port).
  • If the application is deployed on a LAN, you must configure network address translation (NAT) for the application to generate a public network access address for the application. For details, obtain the configuration procedure of the NAT tool from the Internet.

The callback URL can be the same or different for subscription of different notification types. It can be defined based on service requirements.

How Is an Application Notified of Changes in Command Status?

Configure the callbackUrl parameter when an application calls the API for creating a command. (The IP address and port number of this parameter value must be the same as those of the subscription callback URL.) When the command status changes, the IoT platform will push a message to the URL.

Can a Domain Name Be Used in a Callback URL?

Yes. You can use either an IP address or a domain name. If a domain name is bound to multiple IP addresses, perform DNS resolution to confirm that the IP address is reachable. In this case, you are advised to use the IP address in the callback URL.

Can an Application Subscribe to Platform Data When the Application Only Has an Internal IP Address?

If you are an enterprise edition user, ensure you choose the VPC of your purchased enterprise instance for your application, so the application can use the internal IP address for subscription.

Otherwise, your application cannot use an internal IP address to subscribe to the platform. Network address translation (NAT) is required when the intranet of a company or campus is used. You can use NAT to obtain a public IP address.

Why Was the Callback URL Invalid During the Subscription API Call?

A callback URL must contain a public IP address (or domain name), port, and file path.
  • Correct format: http://[IP address]:Port/[File path] or http://[IP address]:Port/
  • Incorrect format: http://[IP address]:Port or http://[IP address]/[File path]

Must the Callback URL Be an HTTPS URL?

No. The IoT platform supports pushes to HTTP and HTTPS URLs. However, you are advised to use HTTPS for encrypted transmission.

Can I Change the Callback URL?

Yes. A callback URL can be changed. To change the IP address and port number of the callback URL, call the API for deleting subscriptions in batches to delete the previous callback URL, upload a new CA certificate, and make subscriptions again.

Must the Certificate of the Callback URL Be Issued by an Authoritative Organization?

No. Custom certificates are also supported. However, it is recommended that you use a certificate issued by an authoritative organization.

What Should I Do If the Push Certificate Is Invalid?

If the certificate was provided by yourself, create a new one and upload it to the IoT platform.

If the certificate was provided by the manufacturer, contact the manufacturer for a new one.

How Can I Obtain the subscriptionId Needed in Calling the API for Deleting a Subscription?

The IoT platform returns the subscriptionId when the subscription API is called. To query the value of subscriptionId, call the API for querying subscriptions in batches.

How Can I Obtain the Address Used by the IoT Platform to Push Messages?

When configuring firewall policies on an application, you can obtain the address from the platform support personnel.

Can the IoT Platform Push Data Reported by Different Devices Under the Same Application to Two Servers?

Yes. The two servers can receive data pushed by the platform if their callback URLs are different.

Why Did an Application Not Receive Push Messages After an NB-IoT Device Subscribed to Message Confirmation and Command Response Notifications?

The message confirmation and command response notifications are not used on NB-IoT networks (CoAP and LwM2M). On NB-IoT networks, to enable an application to receive command response notifications, configure the callbackUrl parameter when calling the API for creating a command.

How Do I Obtain a Device Property Unit in the Device Property Reporting Notification?

You can obtain the device property unit using the API for querying a product based on the product model of the device. For details, see Query a Product.

What Do I Do If Message Push Fails After Subscription?

Description:

An application does not receive pushed messages after subscription, or the result of the connectivity test on Third-party application (HTTP push) is displayed as failed on the IoTDA console.

Figure 2 Forwarding target - Connectivity test results

Possible Causes:

  1. If the subscription callback URL is an HTTPS address, the server certificate may be faulty or the CA certificate corresponding to the server certificate may have not been uploaded to the platform.
  2. The service port corresponding to the subscription callback URL is not enabled.
  3. If the subscription address is a domain name and the domain name is bound to multiple IP addresses, the DNS resolution may be faulty.

Solutions:

  1. If the subscription callback URL is an HTTPS address, apply for a certificate from a CA during commercial use and upload the certificate to the platform by referring to Uploading a Certificate for Device Access to the IoT Platform. Before commissioning, ensure that the certificate creation process is correct. If Check Common Name is selected during certificate upload, ensure that the domain name of the application is the same as the common name of the certificate. You can use the certificate verification tool to view the common name of the certificate.
  2. Check whether the server port corresponding to the subscription callback URL is enabled. Run the telnet command on another computer on the external network to check whether the IP address and port are enabled. If they are not enabled, enable them or change the IP address and port of the subscription callback URL.
  3. If the subscription callback URL is a domain name and the domain name is bound to multiple IP addresses, check whether the IP addresses after DNS resolution are correct and reachable.
  4. Use the message tracing function on the IoTDA console to trigger the push. Then, view the message tracing data, check whether the platform triggers subscription and push and whether the push is successful.
  5. Capture packets on the application and check whether the message pushed by IoTDA is received.

What Happens If an Application Receives Data but an Error Is Displayed on the Platform Indicating that the Push Failed?

Description:

The application receives the data, but the message tracing details show that the push fails.

Figure 3 Message tracing -HTTP push failure details

Possible Causes:

If an application does not return the 200 OK status code to IoTDA within 15 seconds after receiving the data, and the platform considers that the push fails.

Solutions:

After receiving the data, the application needs to return the status code 200 OK.

What Is the Difference Between deviceDataChanged and deviceDatasChanged?

If an application subscribes to device data change notifications (deviceDataChanged) or batch device data change notifications (deviceDatasChanged), the IoT platform pushes notifications of device data changes to the application either way, but the format for encapsulating data is different.

For example: A water meter can have two service types: Battery and Connectivity. The data of the two services is reported each time.
  • If deviceDataChanged is subscribed to, the platform pushes the data to the application twice, Battery service data for the first time, and Connectivity service data for the second time. For example: 
    {
    "notifyType":"deviceDataChanged",
    "deviceId":"********",
    "gatewayId":"********",
    "requestId":null,
    "service":{
        "serviceId":"battery",
        "serviceType":"battery",
        "data":{
            "batteryLevel":66
        },
        "eventTime":"20170211T034003Z"
    }
}
    {
    "notifyType":"deviceDataChanged",
    "deviceId":"********",
    "gatewayId":"********",
    "requestId":null,
    "service":{
        "serviceId":"Connectivity",
        "serviceType":"Connectivity",
        "data":{
            "signalStrength":72,
            "cellId":4022250974,
            "tac":61374,
            "mnc":91,
            "mcc":235
        },
        "eventTime":"20170211T092317Z"
    }
}
  • If deviceDatasChanged is subscribed to, the platform includes information for both services in a single batch of data sent to the application. 
    {
    "notifyType":"deviceDatasChanged",
    "requestId":null,
    "deviceId":"********",
    "gatewayId":"********",
    "services":[
        {
            "serviceId":"battery",
            "serviceType":"battery",
            "data":{
                "batteryLevel":66
            },
            "eventTime":"20170211T034003Z"
        },
        {
            "serviceId":"Connectivity",
            "serviceType":"Connectivity",
            "data":{
                "signalStrength":72,
                "cellId":4022250974,
                "tac":61374,
                "mnc":91,
                "mcc":235
            },
            "eventTime":"20170211T034003Z"
        }
    ]
}

Why Does the Application Receive Multiple Push Messages After a Device Reports a Piece of Data?

The possible causes are as follows:

  • If notifyType is deviceDataChanged and the contents of the multiple push messages are different, the data reported by the device may involve multiple services (the data parameter contains multiple JSON objects). As a result, the IoT platform splits the data into multiple push messages.
  • If two messages are received, and notifyType of one message is deviceDataChanged and notifyType of the other is deviceDatasChanged, you have subscribed to both device data change notifications and batch device data change notifications. As a result, the platform pushes two messages.
  • If the same message is pushed repeatedly, the application may not return a response to the push message in a timely fashion. The platform considers the push to have failed and enables re-push.