Overview

Subscription: An application calls the platform APIs Creating a Rule Trigger Condition, Creating a Rule Action, and Modifying a Rule Trigger Condition to configure and activate rules, in order to obtain changed device service details and management details. (Service details include device lifecycle management, device data reporting, device message status, and device status. Management details include software/firmware upgrade status and result.) The URL of the application, also called the callback URL, must be specified during subscription. Click here to see what is a callback URL?

Push: After a subscription is successful, the platform pushes the corresponding change to a specified callback URL based on the type of data subscribed. (For details on the pushed content, see Transferring Data.) If an application does not subscribe to a specific type of data notification, the platform does not push the data to the application even if the data has changed. The platform pushes data, in JSON format, using HTTP or HTTPS. HTTPS requires authentication and is more secure. Therefore, HTTPS is recommended.

The figure below shows the subscription and push process.

Before pushing HTTPS messages to an application, the platform must verify the application authenticity. Therefore, the application CA certificate must be loaded to the platform. (You can use a commissioning certificate during commissioning and replace it with a commercial certificate during commercial use to avoid security risks.)

Push mechanism: After receiving a push message from the platform, the application returns a 200 OK message. If the application does not respond within 15 seconds or returns a 501, 502, 503, or 504 message, the message delivery fails. The platform caches the message for 10 minutes. Then the platform retries to push the message to each failed application in polling mode. If the retry also fails and the message cache time elapses, the platform does not attempt delivery again. If the platform fails to send a push message 10 consecutive times within the message cache time, the platform sets the callback URL to invalid and checks the validity of all failed URLs in polling mode. If a URL is confirmed to be valid, the platform resets the URL to valid. You can log in to the IoTDA console, choose Resource Spaces in the navigation pane, click View in the row of a resource space, and view the URL status on the Subscription/Push tab page.

Subscribing to Data

After connecting to IoTDA, an application calls an API to subscribe to data.

• For details on how to configure HTTP or HTTPS subscriptions on the console, see Configuring HTTP/HTTPS Subscription and Loading the CA Certificate.
• For details on how to subscribe to data through APIs, see Calling APIs, Creating a Rule Trigger Condition, Creating a Rule Action, and Modifying a Rule Trigger Condition.

Format of Pushed Data

For details on the format of data pushed by the platform to applications after data subscription is created, see Transferring Data.

Loading the CA Certificate

If HTTPS is used, you must load the push certificate by following the instructions provided in this section. Then create a subscription task on the console by following the instructions provided in Configuring HTTP/HTTPS Subscription.

• If the application cancels the subscription and then re-subscribes the data again (with the URL unchanged), the CA certificate must be loaded to the platform again.
• If a subscription type (URL) is added, you must load the CA certificate corresponding to the URL to the platform. Even if the CA certificate used by the new URL is the same as that used by the original URL, the CA certificate must be loaded again.

1. Log in to the IoTDA console.
2. In the navigation pane, click Resource Spaces. On the page displayed, click View in the row of a resource space to access its details.
3. On the Subscription/Push tab page, click Configure Certificate, set the parameters based on the data below, and click OK to load the certificate.

   Parameter	Description
   CA Certificate	A CA certificate from the application can be applied for and purchased in advance. NOTE: You can prepare a commissioning certificate during commissioning. For security reasons, you are advised to replace the commissioning certificate with a commercial certificate during commercial use.
   Domain/IP and Port	Specify the domain name or IP address and port used by the platform to push messages to the application. Set this parameter to the domain name or IP address and port in the URL of the API Creating a Rule Action, for example, api.huawei.com:9001 and 172.0.1.2:8080.
   Check Common Name	Specify whether the common name of the CA certificate is to be verified to see whether the loaded certificate matches the applied certificate. It is recommended that the common name be verified.
   Common Name	This parameter is displayed when Check Common Name is enabled. Obtain the name of the CA certificate from the certificate applicant.
   SNI Support	If multiple servers use the same IP address and port, select SNI Supported, and set Common Name to the domain name of the server that is required to receive push messages. Then the specified server sends its device certificate to the platform. This parameter is not selected by default.
   Use Device Certificate	Retain the default value Disable.

Creating an X.509 Commissioning Certificate

A commissioning certificate, or a self-signed certificate, is used for authentication when the client accesses the server through HTTPS. When the platform uses HTTPS to push data to an application, the platform authenticates the application. This section uses the Windows operating system as an example to describe how to use OpenSSL to make a commissioning certificate. The generated certificate is in PEM format and the suffix is .cer.

The table below lists common certificate storage formats.

The commissioning certificate is used only for commissioning. During commercial use, you must apply for certificates from a trusted CA. Otherwise, security risks may occur.

1. Visit https://slproweb.com/products/Win32OpenSSL.html to download and install OpenSSL.
2. Open the CLI as user admin.
3. Run cd c:\openssl\bin (replace c:\openssl\bin with the actual OpenSSL installation directory) to access the OpenSSL view.
4. Generate the private key file ca_private.key of the CA root certificate.

   openssl genrsa -passout pass:123456 -aes256  -out ca_private.key 2048

   • aes256: encryption algorithm
   • passout pass: private key password
   • 2048: key length

5. Use the private key file of the CA root certificate to generate the file ca.csr.

   openssl req -passin pass:123456 -new -key ca_private.key -out ca.csr -subj "/C=CN/ST=GD/L=SZ/O=Huawei/OU=IoT/CN=CA"

   Modify the following information based on actual conditions:

   • C: country, for example, CN
   • ST: region, for example, GD
   • L: city, for example, SZ
   • O: organization, for example, Huawei
   • OU: organization unit, for example, IoT
   • CN: common name (the organization name of the CA), for example, CA

6. Create the CA root certificate ca.cer.

   openssl x509 -req -passin pass:123456 -in ca.csr -out ca.cer -signkey ca_private.key -CAcreateserial -days 3650

   Modify the following information based on actual conditions:

   • passin pass: The value must be the same as the private key password set in 4.
   • days: validity period of the certificate.

7. Generate the private key file for the application.

   openssl genrsa -passout pass:123456 -aes256 -out server_private.key 2048

8. Generate the .csr file for the application.

   openssl req -passin pass:123456 -new -key server_private.key -out server.csr -subj "/C=CN/ST=GD/L=SZ/O=Huawei/OU=IoT/CN=appserver.iot.com"

   Modify the following information based on actual conditions:

   • C: country, for example, CN
   • ST: region, for example, GD
   • L: city, for example, SZ
   • O: organization, for example, Huawei
   • OU: organization unit, for example, IoT
   • CN: common name. Enter the domain name or IP address of the application.

9. Use the CA private key file ca_private.key to sign the file server.csr and generate the server certificate file server.cer.

   openssl x509 -req -passin pass:123456 -in server.csr -out server.cer -sha256 -CA ca.cer -CAkey ca_private.key -CAserial ca.srl -CAcreateserial -days 3650

10. (Optional) If you need a .crt or .pem certificate, proceed this step. The following uses the conversion from server.cer to server.crt as an example. To convert the ca.cer certificate, replace server in the command with ca.

    openssl x509 -inform PEM -in server.cer -out server.crt

11. In the bin folder of the OpenSSL installation directory, obtain the CA certificate (ca.cer/ca.crt/ca.pem), application server certificate (server.cer/server.crt/server.pem), and private key file (server_private.key). The CA certificate is loaded to the platform, and the application server certificate and private key file are loaded to the application.

Configuring HTTP/HTTPS Subscription

This section describes how to configure HTTP or HTTPS subscription on the console.

1. Log in to the IoTDA console.
2. In the navigation pane, choose Rules > Data Forwarding, and click Create Rule in the upper right corner.
3. Set the parameters based on the table below and click Create Rule.

   Parameter	Description
   Rule Name	Specify the name of a rule to create.
   Description	Describe the rule.
   Data Source	Device: Device information, such as device addition, deletion, and update, will be forwarded. When Data Source is set to Device, quick configuration is not supported. Device property: A property value reported by a device in a resource space will be forwarded. Click Quick Configuration on the right and select the product, property, and service data to forward. Device message: A message reported by a device in a resource space will be forwarded. Click Quick Configuration on the right and select data of a specified topic to forward. Select the product to which the topic belongs and enter the topic name. You can use a custom topic on the product details page or a preset topic. Device message status: The status of device messages exchanged between the device and platform will be forwarded. For details on the device message status, see Message Status. When Data Source is set to Device message status, quick configuration is not supported. Device status: The status change of a directly connected device in a resource space will be forwarded. Click Quick Configuration on the right to forward information about devices whose status is Online, Offline, or Abnormal to other services. For details on the status of devices directly connected to the IoT platform, see Device Status. Batch task: The batch task status will be forwarded. When Data Source is set to Batch Task, quick configuration is not supported.
   Trigger	After the data source is selected, the platform automatically matches the trigger event.
   Resource Space	You can select a single resource space or all resource spaces. If All resource spaces is selected, quick configuration is not supported.

4. Under Set Forwarding Target, click Add. On the displayed page, set the parameters based on the table below and click OK.

   Parameter	Description
   Forwarding Target	Select Third-party application (HTTP push).
   Push URL	Specify the domain name or IP address and port used by the platform to push messages to the application. for example, api.huawei.com:9001 and 172.0.1.2:8080. NOTE: Ensure that the URL is the same as the domain name/IP address entered in Loading the CA Certificate.

5. After the rule is defined, click Start Rule to start forwarding data to the HTTP or HTTPS message queue.

FAQs

• Why Is the Callback URL Invalid During the Subscription API Call?

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

APIs

Creating a Rule Action

Creating a Rule Trigger Condition

Modifying a Rule Trigger Condition

Forwarding Data