應用獲取或者發送數據時，需要向平臺操作數據，或者從平臺訂閱數據。數據操作方面，這里主要涉及4個接口：新增數據、查詢數據、刪除數據、修改數據。詳見后面的API參考。同時，為了便于應用開發，平臺提供了SDK，簡化開發。

1 數據操作API

SDK詳情請查看API調用對接指引

1.1 API 描述

1.2 API 約定

1. 日期類型的參數傳入格式：當前時間到格林威治時間1970年01月01日00時00分00秒的毫秒數。

2. 數量查詢的一些約定：

   1. 單次查詢最多返回200條數據，未指定分頁參數情況下，查詢返回滿足條件的前200條，可根據返回參數中的hasNext判斷是否有更多數據。

   2. 若需要按照指定條件返回數據總數，則指定返回參數為COUNT，API返回參數中會帶有COUNT以及對應的值。

3. 更新刪除的約定：單次操作，最多支持200條數據。

4. 運算符定義：

1. 數據包括系統屬性，API中不允許賦值和更新系統屬性，系統屬性如下：

1.3 數據新增API

1. 請求參數

2. 返回參數

3. 請求示例

{
    "request": {
        "apiVer": "0.0.5" // api版本號
    },
    "id": 1508212818676,// request里的全局唯一id透傳
    "params": {
       "modelId":"XXX123",  //數據模型id
       "scopeId":"fdbsdj1dfjdubgxxx",  //數據模型id
       "properties":{
            "BRAND":"BMW",
            "MODE":"5",
            "CREATE_DATE":1526969423,
            "LONG_SIZE":3.3,
            "LONG_SIZE":2.2              
        }
    },
    "version": "1.0" // 請求協議版本
}

4. 返回示例

{
    "code": 200,
    "message": "success",
    "localizedMsg": null,
    "data": 12345      
}

5. 返回碼

1.4 數據刪除API

1. 請求參數

其中condition針對不同類型的屬性支持的運算符：

2. 返回參數

3. 請求示例

{
    "request": {
        "apiVer": "0.0.4" // api版本號
    },
    "id": 1508212818676,// request里的全局唯一id透傳
    "params": {  
       "modelId":"XXX123",
       "conditions":[
          {"fieldName":"BRAND","value":"BMW","operate":"eq"},
          {"fieldName":"MODE","value":"X5","operate":"eq"}
        ]                
    },
    "version": "1.0" // 請求協議版本
}

4. 返回示例

{
  "code": 200,
  "message": "success",
  "localizedMsg": null,
  "data":100   
}

5. 返回碼

1.5 數據修改API

1. 請求參數

其中condition針對不同類型的屬性支持的運算符：

2. 返回參數

3. 請求示例

{
    "request": {
        "apiVer": "0.0.4" // api版本號
    },
    "id": 1508212818676,// request里的全局唯一id透傳
    "params": {  
       "modelId":"XXX123",
       "conditions":[
          {"fieldName":"BRAND","value":"BMW","operate":"eq"},
          {"fieldName":"MODE","value":"X5","operate":"eq"}
        ],
       "updateDetails":{
          "LONG_SIZE":4,
          "WIDTH_SIZE":3
        }                     
    },
    "version": "1.0" // 請求協議版本
}

4. 返回示例

{
    "code": 200,
    "message": "success",
    "localizedMsg": null,
    "data":100   
}

5. 返回碼

1.6 數據查詢API

1. 請求參數

其中condition針對不同類型的屬性支持的運算符：

2. 返回參數

3. 請求示例-1

{
    "request": {
        "apiVer": "0.0.4" // api版本號
    },
    "id": 1508212818676,// request里的全局唯一id透傳
    "params": {        
       "modelId":"XXX123",
       "returnFields":["MODE","ENGINE"],
       "conditions":[
          {"fieldName":"BRAND","value":"BMW","operate":"eq"},
          {"fieldName":"WIDTH_SIZE","value":1,"value2":2,"operate":"bt"},
          {"fieldName":"LONG_SIZE","value":"3","operate":"mt"}
        ],
       "orderBy":{
          "asc":true,
          "orderByFields":["CREATE_DATA","MODE"]
        },
        "pageNum":1,
        "pageSize":10
       }            
    },
    "version": "1.0" // 請求協議版本
}

4. 返回示例-1

{
    "code": 200,
    "localizedMsg": null,
    "data": "{\"count\":1,
            \"hasNext\":false,
            \"items\":[{\"gmt_create\":1551872701000,\"MODE\":\"33\",\"ENGINE\":\"44\",\"id\":2,\"gmt_modified\":1551872714000}],
            \"pageNum\":1,
            \"pageSize\":10}",
    "message": "success"
}

5. 請求示例-2

{
    "request": {
        "apiVer": "0.0.4" // api版本號
    },
    "id": 1508212818676,// request里的全局唯一id透傳
    "params": {        
       "modelId":"XXX123",
       "returnFields":["COUNT"],
       "conditions":[
          {"fieldName":"BRAND","value":"BMW","operate":"eq"},
          {"fieldName":"WIDTH_SIZE","value":1,"value2":2,"operate":"bt"},
          {"fieldName":"LONG_SIZE","value":"3","operate":"mt"}
        ],
        "pageNum":1,
        "pageSize":10
       }
    },
    "version": "1.0" // 請求協議版本
}

6. 返回示例-2

{
    "code": 200,
    "localizedMsg": null,
    "data": "{
            \"hasNext\":false,
            \"items\":[{
                    \"COUNT\":100
             }]
    }"
    "message": "success"
}

7. 返回碼

1.7 獲取文件上傳地址API

1. 請求參數

2. 返回參數

3. 請求示例

{
    "request": {
        "apiVer": "0.0.1"   // api版本號
    },
    "id": 1508212818671,    // request里的全局唯一id透傳
    "params": {
       "modelId":"XXX123",  //數據模型id
       "fileSize":"3.2",    //文件大小  
       "attrName":"name",   //屬性名稱
       "fileType":"jpg",    //文件類型 
       "version":"1.0",     //模型版本  
    },
    "version": "1.0"        // 請求協議版本
}

4. 返回示例

{
    "code": 200, //返回是否成功，只要不是200說明返回不成功
    "message": "success",  //如果失敗，會返回失敗的信息描述
    "localizedMsg": null,
    "data": {"url":"http://xxx.xxx.xx","fileName":"xxx.jpg"} // 返回的數據   
}

5. 返回碼

1.8 獲取文件下載地址API

1. 請求參數

2. 返回參數

3. 請求示例

{
    "request": {
        "apiVer": "0.0.1" // api版本號
    },
    "id": 1508212818671, // request里的全局唯一id透傳
    "params": {
       "modelId":"XXX123",  //數據模型id
       "scopeId":"fdbsdj1dfjdubgxxx",  //業務隔離id 
       "attrName":"name",  //屬性名稱
       "fileName":"xdsfxv.jpg",  //文件類型 
       "version":"1.0",  //模型版本  
    },
    "version": "1.0" // 請求協議版本
}

4. 返回示例

{
    "code": 200, //返回是否成功，只要不是200說明返回不成功
    "message": "success",  //如果失敗，會返回失敗的信息描述
    "localizedMsg": null,
    "data": {"url":"http://xxx.xxx.xx"} // 返回的數據下載查看的url   
}

5. 返回碼

1.9 查詢數據（不包含count）的API

1. 請求參數

其中condition針對不同類型的屬性支持的運算符：

2. 返回參數

3. 請求示例-1

{
    "request": {
        "apiVer": "2.0.0" // api版本號
    },
    "id": 1508212818676,// request里的全局唯一id透傳
    "params": {        
       "modelId":"XXX123",
       "returnFields":["MODE","ENGINE"],
       "conditions":[
          {"fieldName":"BRAND","value":"BMW","operate":"eq"},
          {"fieldName":"WIDTH_SIZE","value":1,"value2":2,"operate":"bt"},
          {"fieldName":"LONG_SIZE","value":"3","operate":"mt"}
        ],
       "orderBy":{
          "asc":true,
          "orderByFields":["CREATE_DATA","MODE"]
        },
        "pageNum":1,
        "pageSize":10
       }            
    },
    "version": "1.0" // 請求協議版本
}

4. 返回示例-1

{
    "code": 200,
   "localizedMsg": null,
    "data": "{\"hasNext\":false,
            \"items\":[{\"gmt_create\":1551872701000,\"MODE\":\"33\",\"ENGINE\":\"44\",\"id\":2,\"gmt_modified\":1551872714000}],
            \"pageNum\":1,
            \"pageSize\":10}",
    "message": "success"
}

5. 請求示例-2

{
    "request": {
        "apiVer": "2.0.0" // api版本號
    },
    "id": 1508212818676,// request里的全局唯一id透傳
    "params": {        
       "modelId":"XXX123",
       "returnFields":["COUNT"],
       "conditions":[
          {"fieldName":"BRAND","value":"BMW","operate":"eq"},
          {"fieldName":"WIDTH_SIZE","value":1,"value2":2,"operate":"bt"},
          {"fieldName":"LONG_SIZE","value":"3","operate":"mt"}
        ],
        "pageNum":1,
        "pageSize":10
       }            
    },
    "version": "1.0" // 請求協議版本
}

6. 返回示例-2

{
    "code": 200,
    "localizedMsg": null,
    "data": "{
            \"hasNext\":false,
            \"items\":[{
                    \"COUNT\":100
            }"
    "message": "success"
}

7. 返回碼

2.0 查詢總數的API

1. 請求參數

其中condition針對不同類型的屬性支持的運算符：

2. 返回參數

3. 請求示例-1

{
    "request": {
        "apiVer": "0.0.3" // api版本號
    },
    "id": 1508212818676,// request里的全局唯一id透傳
    "params": {        
       "modelId":"XXX123",
       "conditions":[
          {"fieldName":"BRAND","value":"BMW","operate":"eq"},
          {"fieldName":"WIDTH_SIZE","value":1,"value2":2,"operate":"bt"},
          {"fieldName":"LONG_SIZE","value":"3","operate":"mt"}
        ]    
    },
    "version": "1.0" // 請求協議版本
}

4. 返回示例-1

{
    "code": 200,
    "localizedMsg": null,
    "data": "{\"count\":23,
            \"pageNum\":1,
            \"pageSize\":10}",
    "message": "success"
}

9. 返回碼

2. 應用開發 - 數據訂閱

應用可以通過AMQP方式，訂閱數據的變更消息（新增、刪除、修改）。應用自身不需要發布數據的變更消息到通道中，這些消息的產生是由應用通過上面的數據操作API，對數據進行操作之后，由平臺產生。平臺產生時間之后，會將消息通過訂閱關系發送到訂閱方。在這個消息通信中，每一個應用實例，由AppKey標識身份。對于單租戶型的應用，每一個AppKey代表了一次應用分發的實例；但是，對于SaaS應用，他的一個AppKey代表了該應用對應的所有租戶的身份，因此，在SaaS應用按照AppKey得到消息之后，需要自行根據訂閱到的數據內容中的AppID字段，將數據對應到不用的用戶中。

2.1 SDK介紹

2.1.1 Java SDK

1. 依賴引用

對于企業實例和公共實例，都可以使用AMQP方式訂閱，需要添加以下依賴

<!-- amqp 1.0 qpid client -->
<dependency>
  <groupId>org.apache.qpid</groupId>
  <artifactId>qpid-jms-client</artifactId>
  <version>0.40.0</version>
</dependency>
<!-- util for base64-->
<dependency>
  <groupId>commons-codec</groupId>
  <artifactId>commons-codec</artifactId>
  <version>1.10</version>
</dependency>

2. 身份認證

對于使用AMQP方式訂閱，示例代碼如下所示：

 
 public static void main(String[] args) throws Exception {
        String clientId = UUID.randomUUID().toString();  //填寫唯一的id，比如uuid
        String random = UUID.randomUUID().toString().replaceAll("-", "").substring(0, 6);

        //按照阿里云IoT規范，組裝UserName
        String userName = clientId + "|authMode=appkey"
            + ",signMethod=SHA256"
            + ",random=" + random
            + ",appKey=" + "{appkey:純數字}"
            //+ ",iotInstanceId=" + iotInstanceId, //如果是企業實例ID，那么需要補充這個參數。如果是公共實例ID，那么隱藏這個參數
            + ",groupId=" + "{appkey:純數字}"
            + "|";

        //按照阿里云IoT規范，計算簽名，組裝password
        String signContent = "random=" + random;
        String password = doSign(signContent, "{app-secret}", "HmacSHA256");

        //如果是公共實例，那么使用如下鏈接地址。如果是企業實例，需要在實例管理中查看amqp鏈接地址。
        String connectionUrl =
            "failover:(amqps://{aliyun-uid}.iot-amqp.cn-shanghai.aliyuncs.com:5671?amqp.idleTimeout=80000)"
                + "?failover.maxReconnectAttempts=10&failover.reconnectDelay=30";

        Hashtable<String, String> hashtable = new Hashtable<String, String>();
        hashtable.put("connectionfactory.SBCF", connectionUrl);
        hashtable.put("queue.QUEUE", "default");
        hashtable.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.qpid.jms.jndi.JmsInitialContextFactory");
        Context context = new InitialContext(hashtable);
        ConnectionFactory cf = (ConnectionFactory)context.lookup("SBCF");
        Destination queue = (Destination)context.lookup("QUEUE");
        Connection connection = cf.createConnection(userName, password);
        MyJmsConnectionListener myJmsConnectionListener = new MyJmsConnectionListener();
        ((JmsConnection)connection).addConnectionListener(myJmsConnectionListener);
        // Create Session
        // Session.CLIENT_ACKNOWLEDGE: 收到消息后，需要手動調用message.acknowledge()
        // Session.AUTO_ACKNOWLEDGE: SDK自動ack（推薦）
        Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
        connection.start();
        // Create Receiver Link
        MessageConsumer consumer = session.createConsumer(queue);
    }

    /**
     * 按照指定簽名算法計算password簽名
     */
    private static String doSign(String toSignString, String secret, String signMethod) throws Exception {
        SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(), signMethod);
        Mac mac = Mac.getInstance(signMethod);
        mac.init(signingKey);
        byte[] rawHmac = mac.doFinal(toSignString.getBytes());
        return Hex.encodeHexString(rawHmac);
    }
}

注：connectionUrlTemplate 的寫法如下所示：

上海：
公共實例：amqps://${uid}.iot-amqp.cn-shanghai.aliyuncs.com:5671
購買的實例：在LP控制臺“實例管理”--“查看終端節點”里找到AMQP接入點

3. 設置消息接受接口

使用AMQP方式，建立連接之前，需要提供消息接收接口，用于處理回調的消息，需要通過 ((JmsConnection) connection).addConnectionListener(myJmsConnectionListener)來設置，其中 myJmsConnectionListener是一個自定義實現JmsConnectionListener接口的類，如下所示：

    class MyJmsConnectionListener  impJmsConnectionListener() {
    /**
     * 連接成功建立
     * @param remoteURI
     */
    @Override
    public void onConnectionEstablished(URI remoteURI) {
        logger.info("onConnectionEstablished, remoteUri:{}", remoteURI);
    }

    /**
     * 最終連接失敗，嘗試過最大重試次數之后
     * @param error
     */
    @Override
    public void onConnectionFailure(Throwable error) {
        logger.error("onConnectionFailure, {}", error.getMessage());
    }

    /**
     * 連接中斷
     * @param remoteURI
     */
    @Override
    public void onConnectionInterrupted(URI remoteURI) {
        logger.info("onConnectionInterrupted, remoteUri:{}", remoteURI);
    }

    /**
     * 連接中斷后又自動重連上
     * @param remoteURI
     */
    @Override
    public void onConnectionRestored(URI remoteURI) {
        logger.info("onConnectionRestored, remoteUri:{}", remoteURI);
    }

    @Override
    public void onInboundMessage(JmsInboundMessageDispatch envelope) {
        logger.info("onInboundMessage, {}", envelope);
        JmsMessage message = envelope.getMessage();
        try {
            byte[] body = message.getBody(byte[].class);
            String content = new String(body);
            String topic = message.getStringProperty("topic");
            String messageId = message.getStringProperty("messageId");
            logger.info("receive message"
                + ", topic = " + topic
                + ", messageId = " + messageId
                + ", content = " + content);
            //如果創建Session選擇的是Session.CLIENT_ACKNOWLEDGE，這里需要手動ack
            //Thread.sleep(2000);
            message.acknowledge();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onSessionClosed(Session session, Throwable cause) {
        logger.error("onSessionClosed, " + session, cause);
    }

    @Override
    public void onConsumerClosed(MessageConsumer consumer, Throwable cause) {
        logger.error("onConsumerClosed, " + consumer, cause);
    }

    @Override
    public void onProducerClosed(MessageProducer producer, Throwable cause) {
        logger.error("onProducerClosed, " + producer, cause);
    }
}

其中的content內容是一個JSON對象字符串，字段信息如下：

   // 模型ID
    String modelId;

    // 變更數據的ID
    List<Long> dataIds;

    // 操作類型：insert/update/delete
    String operateType;

    // 訂閱的appId, 以appKey授權時為空
    String appId;

    String scopeId;

    // 模型的邏輯隔離id
    String logicalModelIsoId;

    // 模型實例id
    String modelInstanceId;

    //  數據實例id
    String dataInstanceId;