交互示例图

websocket接入交互示例图

接入方式

用户在获取接入开放银行平台必要的参数后，通过SDK提供的API进行接入，以及业务逻辑的处理。

请求建立连接规则

用户需通过SDK发送建立连接请求，在SDK中已实现对应逻辑，注意事项如下：

  • 连接建立所使用的url为wss://open.cibfintech.com:443，uri为/api/websocket/connect,连接建立失败时请检查对应连接url；
  • 在建立连接时用户需自行填入客户端ID（即clientId），该参数在创建websocket配置类时需要使用；
  • 在建立连接时用户需将获取的wsId以Open-WebSocketId的键、clientId以Open-ClientId的键设置到请求头中，这两个键名不能修改；
  • 在建立连接时需要使用到WebSocketConfigure和KeyConfigure两个配置类；
  • 连接建立时会进行签名并将签名值放在请求头的Authorization中，签名规则与API签名相同、其中部分内容为固定值，method固定为大写的POST、URI固定为/api/websocket/authorization、请求参数的业务数据固定为{"clientId":"xxx","wsId":"xxx"}。

请求发送规则

在建立连接之后用户即可通过SDK提供的api进行请求的发送，注意事项如下：

  • 调用参数名与顺序与HTTP形式调用完全一样，一般优先采用HTTP形式进行API调用；
  • 用户可以添加自定义处理对返回的数据进行处理、该处理器内部已实现相关加解密、验签等逻辑，用户只需关注业务逻辑即可。

推送消息规则

用户接收到业务系统推送的消息需要进行解密验签后才能得到业务消息, 在SDK中已实现对应的逻辑，解密验签规则如下：

  • 步骤1：用户使用SM2私钥对接收到的password参数进行解密获取用于加密业务消息的SM4密钥；
  • 步骤2：使用步骤1中解密出来的SM4密钥对接收到msgContent参数使用SM4算法解密获取业务参数；
  • 步骤3：用户需要使用在开放银行平台获取的响应报文验签公钥通过Sm2WithSm3签名算法对接收到的signValue进行验签，签名内容为 Keyid + “&” + Timestamp + “&” + Nonce + “&” + 业务数据（JSON格式）拼接后的内容（例如：KY0123456789012345678900&20160516120000&025e119557284840a52ec6a404123456&{“xxx”: “xxx”, “xxx”: “xxx”}）。其中Keyid为应用ID，用户已知，Timestamp和Nonce由接收到的响应（字段名分别为timestamp和nonce）中获取，业务数据由步骤2中解密得到。

示例代码

/* *
* @param keyId
* @throws SdkException
*/
private static void execWebSocketForm(String keyId) throws SdkException {
    String wsId = "WSONLYFORTEST1234";
    String clientId = "open-sdk-ws-node-1";
    //websocket config配置见execWebSocketJson中注释
    WebSocketConfigure config = WebSocketConfigure.create(wsId, clientId);
    KeyConfigure keyConfig = Configure.getKeyConfigures().get(keyId);
    WebSocketRequest webSocketClient = null;
    try {
        webSocketClient = OpenSdk.connectWebSocket(config, keyConfig);
    } catch (Exception exception) {
        exception.printStackTrace();
    }
    //表单对应的参数
    Map bodyParamMap = new HashMap(4);
    bodyParamMap.put("param1", "test");
    bodyParamMap.put("param2", "test2");
    if (webSocketClient != null) {
        //收到业务请求/推送时逻辑处理
        webSocketClient.addHandler(new MessageHandler() {
            @Override
            public void onMessage(String body) {
                System.out.println(body);
            }
                 
             @Override
            public void onError(String message, Exception throwable) {
                System.out.println("调用业务消息异常");
            }
        });
         webSocketClient.send("/api/test/websocket", ReqMethodEnum.POST, null, bodyParamMap, null, null);
    }
}

更多示例请参考SDK中的Example.java