数据模型对接指引

应用获取或者发送数据时，需要向平台操作数据，或者从平台订阅数据。数据操作方面，这里主要涉及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;