# 批量设置同步策略 - BatchSetPolicy #### 功能介绍 - 批量设置同步策略，包括冲突策略、过滤DROP Database、对象同步范围。 - 设置kafka同步策略 #### 调试 您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?product=DRS&api=BatchSetPolicy)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### 接口约束 - 任务创建成功之后，任务状态为CONFIGURATION，并且与源库和目标库测试连接通过、修改任务接口调用成功后才能调用。 - 支持设置Kafka同步策略的有：PostgreSQL-Kafka同步，Oracle-Kafka同步，GaussDB-Kafka同步，TaurusDB-Kafka，MySQL-Kafka。 - TaurusDB-Kafka，MySQL-Kafka支持任务状态为INCRE_TRANSFER_STARTED时修改Kafka策略配置，修改配置后需等任务状态为INCRE_TRANSFER_STARTED时再进行编辑同步对象操作。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-drs/drs_api_0035.html)。 #### URI POST /v3/{project_id}/jobs/batch-sync-policy 表1路径参数 | **参数** | **是否必选** | **参数类型** | **描述** | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释：** 租户在某一Region下的Project ID。 获取方法请参见[获取项目ID](https://support.huaweicloud.com/api-drs/drs_api_0106.html)。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Content-Type | 是 | String | **参数解释**： 发送的实体的MIME类型。推荐用户默认使用application/json，如果API是对象、镜像上传等接口，媒体类型可按照流类型的不同进行确定。 **约束限制：** 不涉及。 **取值范围：** application/json **默认取值：** application/json | | X-Auth-Token | 是 | String | **参数解释**： 从IAM服务获取的用户Token。 用户Token也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。 请求响应成功后在响应消息头中包含的"X-Subject-Token"的值即为Token值。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | X-Language | 否 | String | **参数解释**： 请求语言类型。 **约束限制：** 不涉及。 **取值范围：** - **en-us**：英语 - **zh-cn**：中文 **默认取** **值：** **en-us** | 表3请求Body参数 | **参数** | **是否必选** | **参数类型** | **描述** | |:---|:---|:---|:---| | jobs | 是 | Array of objects | **参数解释**： 批量设置同步策略请求列表，包含需要设置策略的同步任务信息。 详情请参见[表4]。 | 表4jobs字段数据结构说明 | **参数** | **是否必选** | **参数类型** | **描述** | |:---|:---|:---|:---| | job_id | 是 | String | **参数解释**： 同步任务ID，用于唯一标识一个数据复制任务，在批量设置同步策略时指定需要设置策略的任务。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | conflict_policy | 否 | String | **参数解释**： 数据迁移过程中的冲突策略，指定当目标库已存在相同数据时的处理方式。 **约束限制**： 不涉及。 **取值范围**： - **ignore：**冲突忽略，跳过冲突数据继续迁移。 - **overwrite：**冲突覆盖，用源库数据覆盖目标库已有数据。 - **stop**：冲突失败，遇到冲突时停止任务。 **默认取值**： 不涉及。 | | filter_ddl_policy | 否 | String | **参数解释**： 过滤DDL策略，指定增量同步过程中需要过滤的DDL操作类型。 **约束限制**： 不涉及。 **取值范围**： **drop_database**：过滤DROP DATABASE操作。 **默认取值**： 不涉及。 | | ddl_trans | 否 | Boolean | **参数解释**： 同步增量是否同步DDL，指定增量同步阶段是否将源库的DDL操作同步到目标库。 **约束限制**： 不涉及。 **取值范围**： - **true**：同步增量时同步DDL。 - **false**：同步增量时不同步DDL。 **默认取值**： 不涉及。 | | index_trans | 否 | Boolean | **参数解释**： 同步增量是否同步索引，指定增量同步阶段是否将源库的索引变更同步到目标库。 **约束限制**： 不涉及。 **取值范围**： - **true**：同步增量时同步索引。 - **false**：同步增量时不同步索引。 **默认取值**： 不涉及。 | | topic_policy | 否 | String | **参数解释**： 同步Topic策略，指定Kafka目标库的Topic生成方式 **约束限制**： - 目标库为Kafka时必填。 - 不同引擎类型支持的取值范围不同，详见取值范围说明。 **取值范围**： GaussDB分布式版到Kafka同步取值： - 0：集中投递到一个Topic。 - 1：按库名-schema-表名自动生成Topic名字。 - 2：按库名自动生成Topic名字。 - 3：按库名-schema自动生成Topic名字。 - 4：按库名-dn序号自动生成Topic名字。 GaussDB集中式版到Kafka同步、PostgreSQL到Kafka同步取值： - 0：集中投递到一个Topic。 - 1：按库名-schema-表名自动生成Topic名字。 - 2：按库名自动生成Topic名字。 - 3：按库名-schema自动生成Topic名字。 Oracle到Kafka同步取值： - 0：集中投递到一个Topic。 - 1：按schema-表名自动生成Topic。 - 3：按schema自动生成Topic。 MySQL到Kafka同步取值： - 0：集中投递到一个Topic。 - 1：自动生成Topic。 TaurusDB到Kafka同步取值： - 0：集中投递到一个Topic。 - 1：自动生成Topic。 **默认取值**： 不涉及。 | | topic | 否 | String | **参数解释**： Kafka Topic名称，指定同步数据投递的目标Topic。 **约束限制**： - topic_policy为0时必填。 - 确保topic已存在。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | partition_policy | 否 | String | **参数解释**： 同步到kafka partition策略，指定数据投递到Kafka分区的方式。 **约束限制**： - 目标库为Kafka时必填。 - partition_policy的可选取值受topic_policy约束： - 当topic_policy取0时可取0、1、2、3、4、5； - 当topic_policy取1时可取0、1、2、5； - 当topic_policy取2时partition_policy只支持0、1、2、3，gaussdbv5ha是0、1、2、3，gaussdbv5是0、1、3； - 当topic_policy取3时可取0、1；当topic_policy取4时可取0、1、3。 - 不同链路topic_policy不同，partition_policy取值总结如下： - gaussv5-kafka：根据topic_policy，partition_policy可取0、1、2、3、4、5 - gaussv5ha-kafka：根据topic_policy，partition_policy可取0、1、2、3、5 - taurus-kafka：根据topic_policy，partition_policy可取0、2 - mysql-kafka：根据topic_policy，partition_policy可取0、1、2 - oracle-kafka：根据topic_policy，partition_policy可取0、1、2、3 **取值范围**： - 0：按库名.schema.表名的hash值投递到不同Partition。 - 1：全部投递到Partition 0。 - 2：按主键的hash值投递到不同Partition。 - 3：按库名.schema的hash值投递到不同Partition。 - 4： 按库名.dn序号的hash值投递到不同Partition（仅GaussDB分布式版到Kafka支持选择）。 - 5：按非主键列的hash值投递到不同Partition。 **默认取值**： 不涉及。 | | kafka_data_format | 否 | String | **参数解释**： 投送到kafka的数据格式，指定同步到Kafka的数据序列化方式。 **约束限制**： - MySQL到Kafka增量同步支持avro、json和json_c。 - TaurusDB到Kafka同步支持json和json_c。 - 其他引擎支持json和avro。 **取值范围**： - json：为JSON消息格式，方便解释格式，但需要占用更多的空间。 - avro：可以显示Avro二进制编码，高效获取数据。 - json_c：一种能够兼容多个批量，流式计算框架的数据格式。 **默认取值**： json。 | | topic_name_format | 否 | String | **参数解释**： Topic名字格式，指定自动生成Topic名称时使用的命名模板。 **约束限制**： topic_policy为1,2,3,时需要填写。 PostgreSQL到Kafka同步、GaussDB集中式版到Kafka同步取值： - 当topic_policy取1时，Topic名字格式支持database、schema两个变量，其他字符当做常量。分别用$database$代替数据库名，$schema$代替模式名，**不填默认为$database$-$schema$**。 - 当topic_policy取2时，Topic名字格式支持database一个变量，其他字符都当做常量，不填默认为$database$ - 当topic_policy取3时，Topic名字格式支持database、schema和tablename三个变量，其他字符当做常量。分别用$database$代替数据库名，$schema$代替模式名，$tablename$代替表名，**不填默认为$database$-$schema$-$tablename$**。 Oracle到Kafka同步取值： - 当topic_policy取1时，Topic名字格式支持schema和tablename两个变量，其他字符都当做常量。分别用$schema$代替模式名，$tablename$代替表名。**不填默认为$schema$-$tablename$。** - 当topic_policy取3时，Topic名字格式支持schema变量，其他字符都当做常量。用$schema$代替模式名。**不填默认为$schema$**。 MySQL到Kafka、TaurusDB到Kafka同步取值： - 当topic_policy取1时，Topic名字格式支持database和tablename两个变量，其他字符都当做常量。分别用$database$代替数据库名，$tablename$代替表名。**不填默认为$database$-$tablename$。** **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | partitions_num | 否 | String | **参数解释**： Partition个数，指定Kafka Topic的分区数量。 **约束限制**： - topic_policy为1、2、3时需要填写。 **取值范围**： 1-2147483647 **默认取值**： 1 | | replication_factor | 否 | String | **参数解释**： 副本个数，指定Kafka Topic的副本数量。 **约束限制**： - topic_policy为1、2、3时需要填写。 **取值范围**： 1-32767 **默认取值**： 1 | | is_fill_materialized_view | 否 | Boolean | **参数解释**： PostgreSQL全量阶段是否填充物化视图，指定全量同步时是否将源库物化视图的数据填充到目标库。 **约束限制**： 不涉及。 **取值范围**： - true：填充物化视图 - false：不填充物化视图 **默认取值**： false | | export_snapshot | 否 | Boolean | **参数解释**： PostgreSQL全量阶段是否使用快照模式导出，指定全量同步时是否采用快照方式导出源库数据。 **约束限制**： 不涉及。 **取值范围**： - true：使用快照模式导出 - false：不使用快照模式导出 **默认取值**： false | | slot_name | 否 | String | **参数解释**： 复制槽名称，指定PostgreSQL逻辑复制的复制槽标识。 **约束限制**： - gaussdbv5ha-to-kafka主备任务必填。 - PostgreSQL为源的单增量同步任务选填。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | file_and_position | 否 | String | **参数解释**： 源库日志位点，指定增量同步的起始位点。 **约束限制**： - MySQL为源通过show master status命令获取源库位点，根据提示分别填写File:Position。例如：mysql-bin.000277:805。文件名只能为1-60个字符且不能包含\< \> \& : " ' / \\\\ 特殊字符，文件编号只能为3-20个数字，binlog事件位置只能为1-20个数字，且总长度不能超过100个字符。格式为：文件名.文件编号:事件位点。 - MongoDB为源的任务，任务的源库日志从位点开始获取（含当前启动位点），位点需设置在oplog范围以内。非集群通过db.getReplicationInfo()直接获得oplog范围，集群通过db.watch(\[\], {startAtOperationTime: Timestamp(xx, xx)})命令，将启动位点填在xx处，校验位点是否在oplog范围以内。格式为：timestamp:incre。timestamp和incre均为范围在1\~2,147,483,647之间的整数。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | gtid_set | 否 | String | **参数解释**： MySQL GTID集合，指定增量同步的GTID起始位点。 **约束限制**： - MySQL为源的任务需要填写。通过show master status命令获取源库位点，根据提示填写Executed_Gtid_Set。 - 如果源库为MySQL 5.5版本，则不支持使用同步任务。 - 不能包含\< \> \& " ' / \\\\ 特殊字符和中文，且不能超过2048个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | | ddl_topic | 否 | String | **参数解释**： 存储DDL的topic，指定DDL操作数据投递的目标Topic。 **约束限制**： - Kafka为目标且ddl_trans为true时必填。 - 取值必须为目标库已存在的topic名称，确保topic已存在。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | #### 响应参数 **状态码：200** 表5响应Body参数 | **参数** | **参数类型** | **描述** | |:---|:---|:---| | count | Integer | **参数解释**： 返回的任务信息总数，表示本次查询成功返回的任务数量，与results数组的长度一致。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 | | results | Array of objects | **参数解释**： 批量设置同步策略返回列表。 详情请参见[表6]。 | 表6results字段数据结构说明 | **参数** | **参数类型** | **描述** | |:---|:---|:---| | id | String | **参数解释**： 设置同步策略的任务ID，用于标识策略设置结果对应的任务。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 | | status | String | **参数解释**： 策略设置结果状态，表示同步策略是否设置成功。 **约束限制**： 不涉及。 **取值范围**： - **success**：成功。 - **failed**：失败。 | | error_code | String | **参数解释**： 错误码，当任务报错时返回的错误代码。 **约束限制**： 不涉及。 **取值范围**： 格式为DRS.XXXXXX。 | | error_msg | String | **参数解释**： 错误详细信息，当任务执行失败时返回的具体错误描述。 **约束限制**： 不涉及。 **取值范围**： 不涉及。 | #### 请求示例 - 批量设置同步任务策略，其中增量冲突策略为忽略，同步增量DDL并过滤drop_database操作 ``` https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-sync-policy { "jobs": [{ "conflict_policy": "ignore", "ddl_trans": true, "filter_ddl_policy": "drop_database", "index_trans": true, "job_id": "19557d51-1ee6-4507-97a6-8f69164jb201" }] } ``` - 批量设置MySQL单增量同步任务策略示例： ``` https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-sync-policy { "jobs": [ { "conflict_policy": "ignore", "ddl_trans": true, "filter_ddl_policy": "drop_database", "index_trans": true, "job_id": "19557d51-1ee6-4507-97a6-8f69164jb201"， "file_and_position": "mysql-bin.000019:197", "gtid_set":"e4979f26-4bc3-11ee-b279-fa163ef21d64:1-23" } ] } ``` #### 响应示例 **状态码：200** OK ``` { "results" : [ { "id" : "19557d51-1ee6-4507-97a6-8f69164jb201", "status" : "success" } ], "count" : 1 } ``` #### 状态码 | **状态码** | **描述** | |:---|:---| | 200 | OK | | 400 | Bad Request | 其他状态请参见[状态码](https://support.huaweicloud.com/api-drs/drs_api_0108.html)。 #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-drs/drs_05_0004.html)。