10.5.1. 多发比对 http接口
10.5.1.1. 简介
多发比对提供了 http API，用户可以通过该接口获取统一SQL的多发执行和比对结果是否一致。
10.5.1.2. 接口请求地址
10.5.1.3. 请求方式
POST
10.5.1.4. Content-Type
application/json;charset=UTF-8
10.5.1.5. 接口请求参数
参数名 |
类型 |
是否必须 |
说明 |
取值范围 |
示例 |
|---|---|---|---|---|---|
sourceDialect |
String |
是 |
源端数据库方言ORACLE/MYSQL |
ORACLE、MYSQL |
ORACLE |
targetDialects |
List<String> |
否 |
指定多发哪几个目标数据库，包括源库。多发完成后比对侧会根据该标签进行数据库类型判断是否所有都已执行完成，执行完成则开始比对，比对侧最大等待时间为10秒，如果10秒还有数据库类型未执行完成则立即开始比对。伪多发场景，且分多次调用时必须传入（needTransform=false且bulkMode=2时） |
当源为ORACLE时，目标库取值范围：LIGHTDB_ORACLE, GAUSSDB_ORACLE, DM, OCEAN_BASE_ORACLE; 当源为MYSQL时，目标库取值范围GAUSSDB500_ORACLE |
例如源为ORACLE，多发执行到LIGHTDB_ORACLE、GAUSSDB_ORACLE、DM、OCEAN_BASE_ORACLE，时填写为：[“ORACLE”, “LIGHTDB_ORACLE”, “GAUSSDB_ORACLE”, “DM”, “OCEAN_BASE_ORACLE”] |
targetDialectInfos |
List<TargetDialectInfo> |
是 |
目标数据库信息 |
详细见如下TargetDialectInfo对象结构 |
|
needTransform |
Boolean |
是 |
通过该标签区别是真多发还是伪多发，真多发时needTransform必须是true表示SQL需要通过统一SQL内部转换，并且bulkMode必须是1，目标类型信息需要一次性全部传入（接口只调用一次）。伪多发有两种场景：第一种场景业务整合好所有信息只调用接口一次，needTransform为false表示SQL不需要通过统一SQL内部转换，traceId必须传入。bulkMode为1时，目标类型信息需要一次性全部传入（接口只调用一次）；第二种场景业务分多次接口，每次的traceId相同，根据相同的traceId定义为同一批，统一比对 |
true, false |
true |
bulkMode |
Integer |
是 |
入参targetDialectInfos中是否已经包含了所有需要比对验证的多库信息，1表示本次接口调用已包含所有库信息直接开始多发执行，接口返回后可以立即查询比对结果信息；2表示入参targetDialectInfos中未包含所用目标方言信息，需分多次调用,例如源端ORACLE到 GAUSSDB_ORACLE、DM、OCEAN_BASE_ORACLE的多发，第一次调用只给了DM和OCEAN_BASE_ORACLE的信息，信息不全，第二次调用需要给ORACLE、GAUSSDB_ORACLE的信息。2的前提是needTransform必须是false，并且traceId和targetDialects必须传入（接口调用多次，每次的traceId相同，根据相同的traceId定义为同一批，统一比对），返回信息为本次目标库执行结果已经发送给比对服务，等待剩余批次调用后开始比对，具体比对结果请通过traceId去比对服务界面查询 |
1 一次性组合调用、2 分多次调用 |
1 |
traceId |
String |
否 |
用于查询比对报告的ID值（通常为uuid）。伪多发场景，且分多次调用时必须传入（needTransform=false且bulkMode=2时），用于表明本次传入的目标库需要和哪些具有相同traceId的源/目标库一起进行结果比较验证 |
84cbb67ad75b47b689445f33c3d4cef3 |
TargetDialectInfo对象结构如下：
参数名 |
类型 |
是否必须 |
说明 |
取值范围 |
示例 |
targetDialect |
String |
是 |
源库和目标数据库类型（大小写均可，建议全大写），当内容和 sourceDialect一致时的表示本结构为源方言信息 |
当源为ORACLE时，取值范围：ORACLE、LIGHTDB_ORACLE、GAUSSDB_ORACLE、DM、OCEAN_BASE_ORACLE; 当源为MYSQL时，取值范围MYSQL、GAUSSDB500_ORACLE |
ORACLE |
targetDbVersion |
String |
否 |
目标数据库版本（预留项，暂未使用） |
||
schemaName |
String |
否 |
多发执行时，会在每个目标数据库下指定的业务库或schema下执行sql，不填则按照数据源配置中的dbname执行SQL |
dbtrade |
|
sql |
String |
是 |
业务原始sql或目标方言已适配的SQL。needTransform为true表示真多发时：仅需在targetDialect表示源方言时，填写为业务原始SQL，目标方言对应sql无需填写；needTransform为false表示伪多发时：源方言和目标方言均需填写对应已适配的SQL |
update unisql_test set name = @name where id=@id |
|
sqlParameters |
List<BindVariable> |
否 |
预编译sql语句的参数信息（如果业务sql中有绑定变量，则此参数必填） |
BindVariable对象结构如下：
参数名 |
类型 |
是否必须 |
说明 |
示例 |
|---|---|---|---|---|
name |
String |
是 |
sql语句的绑定变量名(伪代码SQL中的@绑定变量的名字) |
name |
type |
Integer |
是 |
预编译sql语句的绑定变量参数值类型（java.sql.Types中的具体值）支持范围见如下：数据类型支持范围和java.sql.Types映射值章节 |
12 |
value |
Object |
是 |
预编译sql语句的绑定变量参数的内容 |
lilei |
10.5.1.6. 数据类型支持范围和java.sql.Types映射值章节
variableType支持的数据类型映射值如下：
字段类型 |
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 |
BLOB |
Types.BLOB |
2004 |
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 |
10.5.1.7. 接口返回参数
参数名 |
类型 |
是否必须 |
说明 |
取值范围 |
示例 |
|---|---|---|---|---|---|
code |
int |
是 |
状态码，0表示成功，非0表示异常 |
完整清单详见下文错误码清单 |
0 |
message |
String |
是 |
信息描述 |
多发比对成功，结果一致/比对报告结果不一致,可通过traceId，前往比对报告界面查看比对结果 |
|
data |
MultiplexOutput |
否 |
目标库多发比对后信息实体 |
MultiplexOutput对象结构如下：
参数名 |
类型 |
是否必须 |
说明 |
取值范围 |
示例 |
|---|---|---|---|---|---|
traceId |
String |
否 |
用于查询比对报告的ID |
UUID |
84cbb67ad75b47b689445f33c3d4cef3 |
10.5.1.8. 错误码
错误码 |
描述 |
|---|---|
0 |
多发比对成功，结果一致 |
10000 |
入参不能为空！ |
10001 |
目标数据库信息[targetDialectInfos]不能为空！ |
10002 |
目标数据库类型[targetDialect]不能为空！ |
10003 |
目标数据库类型[%s]暂不支持！ |
10004 |
源端数据库类型[%s]输入不正确,目前只持支oracle，mysql！ |
10005 |
输入的源sql不能为空！ |
10006 |
绑定变量名[name]不能为空！ |
10007 |
绑定变量类型[%d]不支持！ |
30000 |
多发数据库执行异常 |
40002 |
获取比对结果失败！ |
40003 |
比对服务地址未授权 |
40004 |
参数值[TraceId]不能为空 |
40005 |
比对报告结果不一致,可通过traceId，前往比对报告界面查看比对结果 |
40006 |
查询比对报告结果时出现异常 |
40007 |
比对报告结果获取超时 |
-1 |
未知异常 |
10.5.1.9. 三种使用场景以及示例
1、真多发时needTransform必须是true表示SQL需要通过统一SQL内部转换，bulkMode必须是1，目标类型信息需要一次性全部传入（接口只调用一次）。
2、伪多发needTransform必须是false表示SQL不需要通过统一SQL内部转换。traceId必须传入。bulkMode为1时，目标类型信息需要一次性全部传入（接口只调用一次）。
3、伪多发needTransform必须是false表示SQL不需要通过统一SQL内部转换。traceId必须传入。bulkMode为2时表示目标类型信息需要分批多次传入。targetDialects必须传入（接口调用多次，每次的traceId相同，根据相同的traceId定义为同一批，统一比对）。
10.5.1.9.1. 请求示例一
真多发场景，源端为ORACLE，多发目标端为LIGHTDB_ORACLE, GAUSSDB_ORACLE, DM, OCEAN_BASE_ORACLE。needTransform必须是true表示SQL需要通过统一SQL内部转换，并且bulkMode必须是1，目标类型信息需要一次性全部传入（接口只调用一次）。
{
"sourceDialect": "ORACLE", // 源端数据库类型
"needTransform": ture, // 业务DML语句是否需要多发转换到信创目标库SQL，true表示需要多发转换
"bulkMode": 1, // 入参targetDialectInfos中是否已经包含了所有需要比对验证的多库信息，1表示本次接口调用已包含所有库信息只调用接口一次，接口返回后可以立即查询比对结果信息；
"targetDialectInfos": [ // 目标数据库结构
{
"targetDialect": "ORACLE", // 与外层的sourceDialect源类型相同，故本结构表示源数据库类型信息
"schemaName": "unisql_test", // 源端业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 源端业务原始SQL语句
"sqlParameters": [ // 源端绑定变量参数内容
{
"name": "id", // 源端绑定变量名称
"type": 4, // 源端绑定变量类型
"value": 1 // 源端绑定变量值
}
,
{ // 源端第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
},
{
"targetDialect": "LIGHTDB_ORACLE", // 目标数据库类型，此处表示lightdb-oracle
"schemaName": "unisql_test1" // 业务库或schema名
}
,
{
"targetDialect": "GAUSSDB_ORACLE", // 目标数据库类型，此处表示gaussdb-oracle
"schemaName": "unisql_test2"
}
,
{
"targetDialect": "DM", // 目标数据库类型，此处表示达梦
"schemaName": "unisql_test"
}
,
{
"targetDialect": "OCEAN_BASE_ORACLE", // 目标数据库类型，此处表示ob-oracle
"schemaName": "unisql_test"
}
]
}
10.5.1.9.2. 返回示例一
{
"code": 0, // 返回状态码
"message": "成功，比对结果一致", // 返回状态信息
"data": {
"traceId": "a4784f429cb24c668024c8e954440fff" // 用于查询比对报告的ID
}
}
10.5.1.9.3. 请求示例二
伪多发场景，所有信息组合一次调用。源端为ORACLE，多发目标端为LIGHTDB_ORACLE, GAUSSDB_ORACLE, DM, OCEAN_BASE_ORACLE。 needTransform必须是true表示SQL需要通过统一SQL内部转换，并且bulkMode必须是1，目标类型信息需要一次性全部传入（接口只调用一次）。
{
"sourceDialect": "ORACLE", // 源端数据库类型
"needTransform": false, // 业务DML语句是否需要多发转换到信创目标库SQL，false表示不需要多发转换
"bulkMode": 1, // 入参targetDialectInfos中是否已经包含了所有需要比对验证的多库信息，1表示本次接口调用已包含所有库信息只调用接口一次，接口返回后可以立即查询比对结果信息；
"traceId": "84cbb67ad75b47b689445f33c3d4cef3", // 用于查询比对报告的ID
"targetDialectInfos": [ // 目标数据库结构
{
"targetDialect": "ORACLE", // 与外层的sourceDialect源类型相同，故本结构表示源数据库类型信息
"schemaName": "unisql_test", // 源端业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 源端业务原始ORACLRE SQL语句
"sqlParameters": [ // 源端绑定变量参数内容
{
"name": "id", // 源端绑定变量名称
"type": 4, // 源端绑定变量类型
"value": 1 // 源端绑定变量值
}
,
{ // 源端第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
},
{
"targetDialect": "LIGHTDB_ORACLE", // 目标数据库类型，此处表示lightdb-oracle
"schemaName": "unisql_test1", // 业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 业务已适配的lightdb-oracle SQL语句
"sqlParameters": [ // 绑定变量参数内容
{
"name": "id", // 绑定变量名称
"type": 4, // 绑定变量类型
"value": 1 // 绑定变量值
}
,
{ // 第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
}
,
{
"targetDialect": "GAUSSDB_ORACLE", // 目标数据库类型，此处表示gaussdb-oracle
"schemaName": "unisql_test2", // 业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 业务已适配的gaussdb-oracle SQL语句
"sqlParameters": [ // 绑定变量参数内容
{
"name": "id", // 绑定变量名称
"type": 4, // 绑定变量类型
"value": 1 // 绑定变量值
}
,
{ // 第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
}
,
{
"targetDialect": "DM", // 目标数据库类型，此处表示达梦
"schemaName": "unisql_test", // 业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 业务已适配的达梦 SQL语句
"sqlParameters": [ // 绑定变量参数内容
{
"name": "id", // 绑定变量名称
"type": 4, // 绑定变量类型
"value": 1 // 绑定变量值
}
,
{ // 第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
}
,
{
"targetDialect": "OCEAN_BASE_ORACLE", // 目标数据库类型，此处表示ob-oracle
"schemaName": "unisql_test", // 业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 业务已适配的ob-oracle SQL语句
"sqlParameters": [ // 绑定变量参数内容
{
"name": "id", // 绑定变量名称
"type": 4, // 绑定变量类型
"value": 1 // 绑定变量值
}
,
{ // 第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
}
]
}
10.5.1.9.4. 返回示例二
{
"code": 0, // 返回状态码
"message": "成功，比对结果一致", // 返回状态信息
"data": {
"traceId": "a4784f429cb24c668024c8e954440fff" // 用于查询比对报告的ID
}
}
10.5.1.9.5. 请求示例三
伪多发场景，非一次性调用，入参targetDialectInfos中未包含所用目标方言信息，分多次调用时。例如源端为ORACLE，多发目标端为LIGHTDB_ORACLE, GAUSSDB_ORACLE, DM, OCEAN_BASE_ORACLE。 第一次调用只给了DM和OCEAN_BASE_ORACLE的信息，信息不全，第二次调用需要给ORACLE、GAUSSDB_ORACLE、LIGHTDB_ORACLE的信息。 needTransform必须是false表示SQL不需要通过统一SQL内部转换，bulkMode必须为2时表示目标类型信息需要分批多次传入，并且traceId和targetDialects必须传入（接口调用多次，每次的traceId相同，根据相同的traceId定义为同一批，统一比对）
// 分成两次调用，第一次调用
{
"sourceDialect": "ORACLE", // 源端数据库类型
"needTransform": false, // 业务DML语句是否需要多发转换到信创目标库SQL，false表示不需要多发转换
"bulkMode": 2, // 入参targetDialectInfos中是否已经包含了所有需要比对验证的多库信息，1表示本次接口调用已包含所有库信息只调用接口一次，接口返回后可以立即查询比对结果信息；
"traceId": "84cbb67ad75b47b689445f33c3d4cef3", // 用于查询比对报告的ID
"targetDialects":["ORACLE", "LIGHTDB_ORACLE", "GAUSSDB_ORACLE", "DM", "OCEAN_BASE_ORACLE"], // 指定多发哪几个目标数据库，多发完成后比对侧会根据该标签进行数据库类型判断是否所有都已执行完成，执行完成则开始比对，比对侧最大等待时间为10秒，如果10秒还有数据库类型未执行完成则立即开始比对。伪多发场景，且分多次调用时必须传入（needTransform=false且bulkMode=2时）
"targetDialectInfos": [ // 目标数据库结构
{
"targetDialect": "DM", // 目标数据库类型，此处表示达梦
"schemaName": "unisql_test", // 业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 业务已适配的达梦 SQL语句
"sqlParameters": [ // 绑定变量参数内容
{
"name": "id", // 绑定变量名称
"type": 4, // 绑定变量类型
"value": 1 // 绑定变量值
}
,
{ // 第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
}
,
{
"targetDialect": "OCEAN_BASE_ORACLE", // 目标数据库类型，此处表示ob-oracle
"schemaName": "unisql_test", // 业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 业务已适配的ob-oracle SQL语句
"sqlParameters": [ // 绑定变量参数内容
{
"name": "id", // 绑定变量名称
"type": 4, // 绑定变量类型
"value": 1 // 绑定变量值
}
,
{ // 第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
}
]
}
// 分成两次调用，第二次调用
{
"sourceDialect": "ORACLE", // 源端数据库类型
"needTransform": false, // 业务DML语句是否需要多发转换到信创目标库SQL，false表示不需要多发转换
"bulkMode": 2, // 入参targetDialectInfos中是否已经包含了所有需要比对验证的多库信息，1表示本次接口调用已包含所有库信息只调用接口一次，接口返回后可以立即查询比对结果信息；
"traceId": "84cbb67ad75b47b689445f33c3d4cef3", // 用于查询比对报告的ID
"targetDialects":["ORACLE", "LIGHTDB_ORACLE", "GAUSSDB_ORACLE", "DM", "OCEAN_BASE_ORACLE"], // 指定多发哪几个目标数据库，多发完成后比对侧会根据该标签进行数据库类型判断是否所有都已执行完成，执行完成则开始比对，比对侧最大等待时间为10秒，如果10秒还有数据库类型未执行完成则立即开始比对。伪多发场景，且分多次调用时必须传入（needTransform=false且bulkMode=2时）
"targetDialectInfos": [ // 目标数据库结构
{
"targetDialect": "ORACLE", // 源数据库类型
"schemaName": "unisql_test", // 业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 业务原始ORACLRE SQL语句
"sqlParameters": [ // 绑定变量参数内容
{
"name": "id", // 绑定变量名称
"type": 4, // 绑定变量类型
"value": 1 // 绑定变量值
}
,
{ // 第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
},
{
"targetDialect": "LIGHTDB_ORACLE", // 目标数据库类型，此处表示LIGHTDB_ORACLE
"schemaName": "unisql_test1", // 业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 业务已适配的LIGHTDB_ORACLE SQL语句
"sqlParameters": [ // 绑定变量参数内容
{
"name": "id", // 绑定变量名称
"type": 4, // 绑定变量类型
"value": 1 // 绑定变量值
}
,
{ // 第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
}
,
{
"targetDialect": "GAUSSDB_ORACLE", // 目标数据库类型，此处表示GAUSSDB_ORACLE
"schemaName": "unisql_test2", // 业务库或schema名
"sql": "update unisql_test set name = @name where id=@id", // 业务已适配的GAUSSDB_ORACLE SQL语句
"sqlParameters": [ // 绑定变量参数内容
{
"name": "id", // 绑定变量名称
"type": 4, // 绑定变量类型
"value": 1 // 绑定变量值
}
,
{ // 第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
}
]
}
10.5.1.9.6. 返回示例三
{
"code": 0, // 返回状态码
"message": "本次目标库执行结果已经发送给比对服务，等待剩余批次调用后开始比对，具体比对结果请通过traceId去比对服务界面查询", // 返回状态信息
"data": {
"traceId": "a4784f429cb24c668024c8e954440fff" // 用于查询比对报告的ID
}
}
{
"code": 0, // 返回状态码
"message": "本次目标库执行结果已经发送给比对服务，等待剩余批次调用后开始比对，具体比对结果请通过traceId去比对服务界面查询", // 返回状态信息
"data": {
"traceId": "a4784f429cb24c668024c8e954440fff" // 用于查询比对报告的ID
}
}