OpenAPI SDK Usage Guide

OpenAPI SDK is mainly used for SaaS system integration, enabling product device management and remote control of devices through SaaS applications.

Operation Steps

Prerequisites

1. Before using OpenAPI services, you need to create a SaaS application under the SaaS Development -> SaaS Management menu.

2. Enable and authorize the API service packages you need to use on the SaaS Details -> Services page. You can only call the API interfaces under that service package after authorization.

3. Authorize product data that the SaaS application can access on the SaaS Details -> Products page. You can only query data under authorized products through the API after authorization.

4. Obtain AccessKey and AccessSecret, which will be used to exchange for an access Token later.

Development Environment Preparation

The example uses the following development environment:

• Operating System: Windows10
• JDK Version: JDK8
• Integrated Development Environment: IntelliJ IDEA Community Edition

SDK Function List

quecloud-sdk-dev-mgr:

Method Name	Function Description
getProductItems	Get product categories
getProductDetail	Get product details
getProductList	Get product list
getDeviceList	Get device list
getDeviceDetail	Get device details
deviceResource	Get device resources
getDeviceDataHistory	Get device historical uplink/downlink data
getDeviceEventData	Get device event log data
getDeviceLocationLatest	Get device location information data
getTslJson	Get thing model data
generateSn	Get SN
createSnBindDevice	Create SN and device binding relationship
findDkList	Query corresponding device list by PK and SN list
findSnList	Query corresponding SN list by device list
delSnBindDevice	Delete SN and device binding relationship
createQuece	Create queue
deleteQuece	Delete queue
getQueceDetail	Get queue details
createSubscribe	Create regular subscription
createEnterpriseUserSubscribe	Create enterprise user subscription
createSaasUserSubscribe	Create SaaS user subscription
createEndUserSubscribe	Create end-user subscription
getSubscribeDetail	Get subscription details
startSubscribe	Start subscription
stopSubscribe	Stop subscription
deleteSubscribe	Delete subscription

quecloud-sdk-dev-msg:

Method Name	Function Description
sendDeviceData	Send downlink data to device
batchSendDeviceData	Send downlink data to devices in batch
deviceDmReadData	Read device thing model property data
deviceDmWriteData	Send downlink thing model data to device
deviceRawSendData	Send downlink transparent transmission data
deviceDmsendServiceData	Send downlink thing model service data to device

SDK Example

1. Reference jar package from central repository

a) Product and device management
<dependency>
  <groupId>com.quectel.aiot</groupId>
  <artifactId>quecloud-sdk-standard-mgr</artifactId>
  <version>2.1.0.RELEASE</version>
</dependency>

b) Device data uplink/downlink management
<dependency>
    <groupId>com.quectel.aiot</groupId>
    <artifactId>quecloud-sdk-dev-msg</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

2. Initialize SDK

a) Create an InitClientProfile object to store accessKey, accessSecret, endpoint (for Europe data center, enter iot-api.acceleronix.io) and other information

b) Create a Client object. For product and device management, initialize a MgrClient object; for device uplink/downlink, initialize a MsgClient object

3. Call steps:

SaaS SDK encapsulates two classes for each API: the request parameter class (*Request) and the request response class (*Response).

a) Complete SDK initialization. Get MgrClient Client/MsgClient Client object

b) Create a parameter object for the corresponding API request method

c) Use set methods on the parameter object to set the request parameter values required by the API.

  i) Use the obtained Client object to directly call methods in the object to get a response object. Each response object includes success (success indicator), msg (return information), errorMsg (error information, returns specific error information when success is false), body (body is an object that carries the specific information value returned by each API)

  ii) Use the catch() method to handle exception errors.

For API list and corresponding Request and Response object descriptions, please see API List

d) Using the downlink data API as an example, write the code as follows:

public static void main(String[] args) {
        try{
            // accessKey and accessSecret are created by developers in the developer center
            InitClientProfile initClientProfile = new InitClientProfile(
                    "${accessKey}",
                    "${accessSecret}",
                    "${endpoint}");
            // Get the MsgClient object. Singleton pattern is recommended. This object contains SDK for device data downlink.
            MsgClient msgClient = new MsgClient(initClientProfile);
 
            // PASSTHROUGH:transparent transmission PROPERTY:property SERVICE:service
            String type="PASSTHROUGH|PROPERTY|SERVICE";
            // GET:report UP DOWN:downlink
            String operate="GET|DOWN";
 
            // Send thing model property data to a single device
            /**
             * Send downlink data to device. data is the specific content of the downlink data. When operate=GET, the data format is "["key1","key2",…]" (key is the thing model identifier). When operate=DOWN, the data format is "[{key1:value1},{key2:value2}]" (key is the thing model identifier).
             * Examples:
             * Property bool/int/float/double/enum/date/text
             * "[{\"key\":\"value\"}]"
             * Property array
             * "[{\"key\":[{\"id\":\"value1\"},{\"id\":\"value2\"}]}]" (id is 0)
             * Property struct
             * "[{\"key\":[{\"key1\":\"value1\"},{\"key2\":\"value2\"}]}]"
             * Property array containing struct
             * "[{\"key\":[{\"id\":[{\"key1\":\"value1\"}]},{\"id\":[{\"key2\":\"value2\"}]}]}]" (id is 0)
             * Service call bool/int/float/double/enum/date/text
             * "[{\"key\":[{\"key1\":\"value1\"},{\"key2\":\"value2\"},{\"key3\":\"value3\"}]}]"
             * Service call array
             * "[{\"key\":[{\"key1\":[{\"id\":\"value1\"},{\"id\":\"value1\"}]}]}]" (id is 0)
             * Service call struct
             * "[{\"key\":[{\"key1\":[{\"key2\":\"value2\"},{\"key3\":\"value3\"}]}]}]"
             * Service call array, and array contains struct
             * "[{\"key\":[{\"key1\":[{\"id\":[{\"key2\":\"value2\"}]},{\"id\":[{\"key3\":\"value3\"}]}]}]}]" (id is fixed at 0)
             */
 
            type = "PROPERTY";
            operate = "DOWN";
            DeviceSendDataRequest deviceSendTslDataRequest = new DeviceSendDataRequest("${productKey}","${deviceKey}","${data}",type,operate);
            DeviceSendDataResponse tslResult = msgClient.sendDeviceData(deviceSendTslDataRequest);
            log.info("Single device downlink model data return result:{}", JSONObject.toJSONString(tslResult));
        }catch(Exception e){
            log.info("Error sending thing model property data to single device",e);
        }
    }

For detailed Demo code, see GitHub repository: Product and device management (quecloud-sdk-dev-mgr)

https://github.com/thridparty-cloud2/quecloud-sdk-dev-mgr-demonstration.git

Device data uplink/downlink (quecloud-sdk-dev-msg)

https://github.com/thridparty-cloud2/quecloud-sdk-dev-msg-demonstration.git