1.9.1. 统一SQL http接口

1.9.1.1. 简介

统一SQL开放了一个http接口，用户可以通过该接口获取统一SQL的转换结果，多发执行和比对结果是否一致。

1.9.1.2. 接口请求地址

http://ip:port/multiplex/transformSql

1.9.1.3. 请求方式

POST

1.9.1.4. Content-Type

application/json;charset=UTF-8

1.9.1.5. 接口请求参数

参数名	类型	是否必须	说明	取值范围	示例
sourceDialect	String	是	源端数据库方言ORACLE，MYSQL	ORACLE、MYSQL	ORACLE
targetDialectInfos	List<TargetDialectInfo>	是	目标数据库信息	详细见如下TargetDialectInfo对象结构
sql	String	是	转换前sql		update unisql_test set name = @name where id=@id
sqlParameters	List<BindVariable>	否	预编译sql语句的参数信息	详细见如下BindVariable对象结构

TargetDialectInfo对象结构如下：

参数名	类型	是否必须	说明	取值范围	示例
targetDialect	String	是	目标数据库类型加兼容模式（大小写均可，建议全大写）。注：此处GAUSSDB_ORACLE表示gaussdb 505版本，GAUSSDB500_ORACLE表示gaussdb 500版本	当源为ORACLE时，目标库取值范围：LIGHTDB_ORACLE, POSTGRESQL, TDSQL_MYSQL, TDSQL_PG_ORACLE, GAUSSDB_ORACLE, DM, OCEAN_BASE_ORACLE, OCEAN_BASE_MYSQL; 当源为MYSQL时，目标库取值范围GAUSSDB500_ORACLE, GOLDENDB_MYSQL	GAUSSDB500_ORACLE
targetDbVersion	String	否	目标数据库版本（预留项，暂未使用）
schemaName	String	否	多发执行时，会在每个目标数据库下指定的业务库或schema下执行sql，不填则按照数据源配置中的dbname执行SQL。oracle系为用户名；mysql、postgresql系为URL中ip和port后面的databaseName		dbtrade
multiCompare	Boolean	否	是否执行多发比对，为true时，转换成功后内部会异步调用多发服务并直接返回traceId，后续可根据traceId查看多发比对结果是否一致	true 、false 默认不传为false

BindVariable对象结构如下：

参数名	类型	是否必须	说明	示例
name	String	是	sql语句的绑定变量名(伪代码SQL中的@绑定变量的名字)	name
type	Integer	是	预编译sql语句的绑定变量参数值类型（java.sql.Types中的具体值）支持范围见如下：数据类型支持范围和java.sql.Types映射值章节	12
value	Object	是	预编译sql语句的绑定变量参数的内容	lilei

1.9.1.6. 数据类型支持范围和java.sql.Types映射值章节

type支持的数据类型映射值如下：

字段类型	java.sql.Types	variableType值(对应java.sql.Types值)
BINARY_FLOAT、FLOAT、REAL	Types.FLOAT	6
BINARY_DOUBLE、DOUBLE、DOUBLE PRECISION	Types.DOUBLE	8
CHAR、CHARACTER	Types.CHAR	1
NCHAR	Types.NCHAR	-15
NVARCHAR、NVARCHAR2、NCHAR VARYING	Types.NVARCHAR	-9
VARCHAR、VARCHAR2、TINYTEXT	Types.VARCHAR	12
TINYINT 、INT1	Types.TINYINT	-6
SMALLINT 、INT2	Types.SMALLINT	5
INTEGER、INT、INT3、MEDIUMINT、INT4	Types.INTEGER	4
BIGINT、INT8	Types.BIGINT	-5
CLOB	Types.CLOB	2005
DECIMAL、DEC、NUMBER、NUMERIC	Types.DECIMAL	3
DATE	Types.DATE	91
TIME	Types.TIME	92
TIMESTAMP、DATETIME、TIMESTAMP(p) WITH TIME ZONE	Types.TIMESTAMP	93
ROWID	Types.ROWID	-8
BOOL、BOOLEAN	Types.BOOLEAN	16
TEXT、MEDIUMTEXT、LONGTEXT	Types.LONGVARCHAR	-1

1.9.1.7. 接口返回参数

参数名	类型	是否必须	说明	取值范围	示例
code	int	是	状态码，0表示成功，非0表示异常	完整清单详见下文错误码清单	0
message	String	是	信息描述		转换成功/转换成功且需要多发的目标端[xxx]已经发送多发服务，后续可根据traceId查看多发比对结果是否一致
data	MultiplexOutput	否	目标库转换后信息实体

MultiplexOutput对象结构如下：

参数名	类型	是否必须	说明	示例
sourceDialect	String	是	源端数据库类型	oracle/mysql
targetDialectInfos	List<TargetDialectInfo>	是	目标数据库信息
traceId	String	否	用于查询比对报告的ID	84cbb67ad75b47b689445f33c3d4cef3

TargetDialectInfo对象结构如下：

参数名	类型	是否必须	说明	取值范围	示例
targetDialect	String	是	目标数据库类型加兼容模式（大小写均可，建议全大写）。注：此处GAUSSDB_ORACLE表示gaussdb 505版本，GAUSSDB500_ORACLE表示gaussdb 500版本	当源为ORACLE时，目标库取值范围：LIGHTDB_ORACLE, POSTGRESQL, TDSQL_MYSQL, TDSQL_PG_ORACLE, GAUSSDB_ORACLE, DM, OCEAN_BASE_ORACLE, OCEAN_BASE_MYSQL; 当源为MYSQL时，目标库取值范围GAUSSDB500_ORACLE, GOLDENDB_MYSQL	GAUSSDB500_ORACLE
targetDbVersion	String	否	目标数据库版本（预留项，暂未使用）
schemaName	String	否	多发执行时，会在每个目标数据库下指定的业务库或schema下执行sql，不填则按照数据源配置中的dbname执行SQL。oracle系为用户名；mysql、postgresql系为URL中ip和port后面的databaseName		dbtrade
multiCompare	Boolean	是	是否执行多发比对，为true时，转换成功后内部会异步调用多发服务并直接返回traceId，后续可根据traceId查看多发比对结果是否一致	true
sql	String	是	转换后sql		update unisql_test set name = @name where id=@id

1.9.1.8. 错误码

错误码	描述
0	转换成功/转换成功且需要多发的目标端[xxx]已经发送多发服务，后续可根据traceId查看多发比对结果是否一致
10000	入参不能为空！
10001	目标数据库信息[targetDialectInfos]不能为空！
10002	目标数据库类型[targetDialect]不能为空！
10003	目标数据库类型[%s]暂不支持！
10004	源端数据库类型[%s]输入不正确,目前只持支oracle，mysql！
10005	输入的源sql不能为空！
20000	源库[%s]到目标库[%s]转换失败
-1	未知异常

1.9.1.9. 两种使用场景以及示例

1、仅通过统一SQL进行SQL转换

2、通过统一SQL进行SQL转换同时转换成功后内部会异步调用多发服务并直接返回traceId，后续可根据traceId查看多发比对结果是否一致

1.9.1.9.1. 请求示例一

仅通过统一SQL进行SQL转换

{
"sourceDialect": "ORACLE",                      // 源端数据库类型，本例源库为oracle
"targetDialectInfos": [                         // 目标数据库类型信息
    {
    "targetDialect": "LIGHTDB_ORACLE"           // 目标数据库类型1，表示lightdb-oracle
    }
    ,
    {
    "targetDialect": "GAUSSDB_ORACLE"           // 目标数据库类型2，表示gaussdb-oracle
    }
    ,
    {
    "targetDialect": "GAUSSDB500_ORACLE"        // 目标数据库类型3，表示gaussdb500-oracle
    }
    ,
    {
    "targetDialect": "DM"                       // 目标数据库类型4，表示dm
    }
    ,
    {
    "targetDialect": "OCEAN_BASE_ORACLE"        // 目标数据库类型5，表示ob-oracle
    }
],
"sql": "select id,name from unisql_test where id=@id and name=@name order by id"      // 业务原始SQL语句，本例中表示需要转换到各目标库的oracle语句
}

1.9.1.9.2. 返回示例一

{
"code": 0,                                                                                          // 返回状态码，0表示转换成功
"data": {
    "sourceDialect": "ORACLE",                                                                      // 源端数据库类型，本例中源库为oracle
    "targetDialectInfos": [                                                                         // 目标数据库SQL转换信息
    {
        "targetDialect": "LIGHTDB_ORACLE",                                                          // 目标数据库类型1，表示lightdb-oracle
        "sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id"            // 由oracle源sql转换而来的lightdb-oracle的方言语句
    },
    {
        "targetDialect": "GAUSSDB_ORACLE",                                                          // 目标数据库类型2，表示gaussdb-oracle
        "sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id"            // 由oracle源sql转换而来的gaussdb-oracle的方言语句
    },
    {
        "targetDialect": "GAUSSDB500_ORACLE",                                                       // 目标数据库类型3，表示gaussdb500-oracle
        "sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id"            // 由oracle源sql转换而来的gaussdb500-oracle的方言语句
    },
    {
        "targetDialect": "DM",                                                                      // 目标数据库类型4，表示dm
        "sql": "select id,name from unisql_test where id=@id and name=@name order by id"            // 由oracle源sql转换而来的dm的方言语句
    },
    {
        "targetDialect": "OCEAN_BASE_ORACLE",                                                       // 目标数据库类型5，表示ob-oracle
        "sql": "select id,name from unisql_test where id=@id and name=@name order by id"            // 由oracle源sql转换而来的ob-oracle的方言语句
    }
    ]
},
"message": "转换成功"                                                                                // 返回状态具体信息描述
}

1.9.1.9.3. 请求示例二

通过统一SQL进行SQL转换同时转换成功后内部会异步调用多发服务并直接返回traceId，后续可根据traceId查看多发比对结果是否一致。如下例子为ORACLE到LIGHTDB_ORACLE、GAUSSDB_ORACLE、GAUSSDB500_ORACLE、DM、OCEAN_BASE_ORACLE 5个库的统一SQL转换。同时 ORACLE到LIGHTDB_ORACLE、GAUSSDB_ORACLE、DM、OCEAN_BASE_ORACLE 4个库的异步多发验证。

{
    "sourceDialect": "ORACLE",                      // 源端数据库类型，本例源库为oracle
    "targetDialectInfos": [                         // 目标数据库类型信息
        {
        "targetDialect": "LIGHTDB_ORACLE",          // 目标数据库类型1，表示lightdb-oracle
        "multiCompare": true                        // 是否进行多发验证
        }
        ,
        {
        "targetDialect": "GAUSSDB_ORACLE",          // 目标数据库类型2，表示gaussdb-oracle
        "multiCompare": true                        // 是否进行多发验证
        }
        ,
        {
        "targetDialect": "GAUSSDB500_ORACLE",       // 目标数据库类型3，表示gaussdb500-oracle
        "multiCompare": false                        // 是否进行多发验证

        }
        ,
        {
        "targetDialect": "DM",                      // 目标数据库类型4，表示dm
        "multiCompare": true                        // 是否进行多发验证

        }
        ,
        {
        "targetDialect": "OCEAN_BASE_ORACLE",       // 目标数据库类型5，表示ob-oracle
        "multiCompare": true                        // 是否进行多发验证
        }
    ],
    "sql": "select id,name from unisql_test where id=@id and name=@name order by id", // 业务原始SQL语句，本例中表示需要转换到各目标库的oracle语句
    "sqlParameters": [                                                                          // 绑定变量参数内容
        {
        "name": "id",                                                                           // 绑定变量名称
        "type": 4,                                                                              // 绑定变量类型
        "value": 1                                                                              // 绑定变量值
        }
        ,
        {                                                                                       // 第二个绑定变量参数内容
        "name": "name",
        "type": 12,
        "value": "测试"
        }
    ]
}

1.9.1.9.4. 返回示例二

{
    "code": 0,                                                                                          // 返回码，0成功
    "data": {
        "sourceDialect": "ORACLE",                                                                      // 源端数据库类型，本例中源库为oracle
        "targetDialectInfos": [                                                                         // 目标数据库SQL转换信息
            {
                "targetDialect": "LIGHTDB_ORACLE",                                                      // 目标数据库类型1，表示lightdb-oracle
                "sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id",       // 由oracle源sql转换而来的lightdb-oracle的方言语句
                "multiCompare": true                                                                    // 进行多发验证
            },
            {
                "targetDialect": "GAUSSDB_ORACLE",                                                      // 目标数据库类型2，表示gaussdb-oracle
                "sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id",       // 由oracle源sql转换而来的gaussdb-oracle的方言语句
                "multiCompare": true                                                                    // 进行多发验证
            },
            {
                "targetDialect": "GAUSSDB500_ORACLE",                                                   // 目标数据库类型3，表示gaussdb500-oracle
                "sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id",       // 由oracle源sql转换而来的gaussdb500-oracle的方言语句
                "multiCompare": false                                                                   // 不进行多发验证
            },
            {
                "targetDialect": "DM",                                                                  // 目标数据库类型4，表示dm
                "sql": "select id,name from unisql_test where id=@id and name=@name order by id",       // 由oracle源sql转换而来的dm的方言语句
                "multiCompare": true                                                                    // 进行多发验证
            },
            {
                "targetDialect": "OCEAN_BASE_ORACLE",                                                   // 目标数据库类型5，表示ob-oracle
                "sql": "select id,name from unisql_test where id=@id and name=@name order by id",       // 由oracle源sql转换而来的ob-oracle的方言语句
                "multiCompare": true                                                                    // 进行多发验证
            }
        ],
        "traceId": "fdea3b18-118d-453f-b5a6-2cf4745ea654"                                               // 用于查询比对报告的ID
    },
    "message": "转换成功且需要多发的目标端[GAUSSDB_ORACLE,DM,OCEAN_BASE_ORACLE,ORACLE]已经发送多发服务，后续可根据traceId查看多发比对结果是否一致"  // 返回状态信息
}