文档首页/ 数据复制服务 DRS/ API参考/ API v5（公测中）/ 数据加工/ 保存数据过滤规则 - SaveDataFilterRules
更新时间：2026-07-29 GMT+08:00
查看PDF
分享

保存数据过滤规则 - SaveDataFilterRules

功能介绍

保存数据过滤规则

接口约束

1.一般过滤条件中涉及到子查询，需要提前配置高级配置过滤条件。

2.Mysql-Mysql、Mysql-Taurus链路支持高级配置过滤条件功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限和授权项。
  • 如果使用身份策略授权，当前API调用无需身份策略权限。

URI

PUT /v5/{project_id}/jobs/{job_id}/filter-rules

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数解释：

租户在某一Region下的Project ID。

获取方法请参见获取项目ID。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及

job_id

是

String

参数解释：

任务ID，用于指定要保存过滤规则的目标任务。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及

请求参数

表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：中文
  • es-us：西班牙语
  • pt-br：葡萄牙语

默认取值：

en-us
表3 请求Body参数

参数

是否必选

参数类型

描述

general_filtering_list

否

Array of objects

参数解释：

数据过滤条件列表。包含需要校验的数据过滤规则信息。

详情请参见表4。

约束限制：

当data_filter_type为common（简单条件过滤）时，此参数为必填项。列表中的每个元素代表一组过滤条件，包含过滤对象列表和源库过滤条件SQL。包含以下关键字段：filter_object_list（过滤对象列表）/source_filter_condition（源库过滤条件SQL）。适用条件：data_filter_type=common时必填。

取值范围：

不涉及。

默认取值：

不涉及

advanced_setting_list

否

Array of objects

参数解释：

数据过滤高级设置列表。用于配置关联表场景下的高级过滤规则，包含数据库名、表名、列名、索引等详细过滤配置。

详情请参见表6。

约束限制：

当前仅MySQL到 MySQL链路支持此功能。适用条件：data_filter_type=config时必填。

取值范围：

不涉及。

默认取值：

不涉及

source

否

String

参数解释：

校验请求的来源场景。用于区分数据过滤规则校验是来自数据同步任务执行场景，还是来自数据对比任务执行场景。

约束限制：

不涉及。

取值范围：

  • job 数据同步任务执行时的过滤规则校验。
  • compare 数据对比任务执行时的过滤规则校验。

默认取值：

job

data_filter_type

否

String

参数解释：

数据过滤类型。用于指定数据过滤规则的模式，common表示简单条件过滤（单表过滤条件），config表示关联表过滤（多表关联条件过滤）。

约束限制：

当简单条件过滤是子查询时，需要先校验关联条件，关联条件校验成功之后，需要保存关联条件。

取值范围：

  • common 简单条件过滤。
  • config 关联表过滤。

默认取值：

common
表4 GeneralTransformationReq

参数

是否必选

参数类型

描述

filter_object_list

否

Array of objects

参数解释：

数据过滤对象列表。包含需要校验的具体数据库对象（库/Schema/表）信息。

详情请参见表5。

约束限制：

在简单条件过滤场景下为必填项，列表中的每个元素代表一个待过滤的数据库对象。

取值范围：

不涉及。

默认取值：

不涉及。

source_filter_condition

否

String

参数解释：

源端数据库的过滤条件SQL语句。用于定义源库数据过滤规则，支持SQL子查询等高级过滤表达式。当数据过滤涉及子查询场景时，需要通过此字段配置查询条件。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表5 DataFilterObjectInfo

参数

是否必选

参数类型

描述

id

是

String

参数解释：

数据过滤对象的唯一标识。用于标识待过滤的数据库对象，填写格式为层级路径形式。

约束限制：

填写格式为以下三种之一：库名---表名、schema名---表名、库名---schema名---表名。

取值范围：

不涉及。

默认取值：

不涉及。

parent_id

是

String

参数解释：

数据过滤对象的父级对象标识。用于标识当前过滤对象所属的上级数据库对象（库或Schema）。

约束限制：

填写格式为以下三种之一：库名、schema名、库名---schema名。

取值范围：

不涉及。

默认取值：

不涉及。

object_name

是

String

参数解释：

数据过滤对象的名称。即当前需要进行过滤操作的具体数据库表名。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

object_type

否

String

参数解释：

数据过滤对象的类型。标识当前过滤对象的数据库对象类型，如表、视图、存储过程等。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表6 DataFilteringAdvancedSetting

参数

是否必选

参数类型

描述

db_name

是

String

参数解释：

库名。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

table_name

是

String

参数解释：

表名。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

col_names

是

String

参数解释：

列名。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

prim_key_or_indexes

是

String

参数解释：

主键或唯一索引。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

indexes

是

String

参数解释：

优化查询所需的索引。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

values

是

String

参数解释：

过滤条件。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

响应参数

状态码：200

OK

状态码：400

表7 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码，当任务报错时返回的错误代码。

约束限制：

  • 最小长度：12
  • 最大长度：12

取值范围：

格式为DRS.XXXXXX。

error_msg

String

参数解释：

错误详细信息，当任务执行失败时返回的具体错误描述。

约束限制：

  • 最小长度：1
  • 最大长度：512

取值范围：

不涉及。

请求示例

  • 源库是库表或者schema表，两层对象结构的批量数据过滤规则请求体 
    https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs/c7debc9c-8e09-4a5d-8dd6-cc44f78jb20r/filter-rules 
 
{ 
  "general_filtering_list" : [ { 
    "filter_object_list" : [ { 
      "id" : "test_drs-*-*-mysql1", 
      "parent_id" : "test_drs", 
      "object_name" : "mysql1", 
      "object_alias_name" : "test-*-*-test1", 
      "object_type" : "table" 
    }, { 
      "id" : "test_drs-*-*-mysql2", 
      "parent_id" : "test_drs", 
      "object_name" : "mysql1", 
      "object_alias_name" : "test-*-*-test2", 
      "object_type" : "table" 
    } ], 
    "source_filter_condition" : "id > 1" 
  } ], 
  "source" : "job", 
  "data_filter_type" : "common" 
}
  • 源库是库schema表，三层对象结构的批量数据过滤规则请求体 
    https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs/c7debc9c-8e09-4a5d-8dd6-cc44f78jb20r/filter-rules 
 
{ 
  "general_filtering_list" : [ { 
    "filter_object_list" : [ { 
      "id" : "test_db-*-*-testschema-*-*-test_table01", 
      "parent_id" : "test_db-*-*-testschema", 
      "object_name" : "test_table", 
      "object_alias_name" : "test_db-*-*-testschema-*-*-test01", 
      "object_type" : "table" 
    }, { 
      "id" : "test_db-*-*-testschema-*-*-test_table02", 
      "parent_id" : "test_db-*-*-testschema", 
      "object_name" : "test_table", 
      "object_alias_name" : "test_db-*-*-testschema-*-*-test02", 
      "object_type" : "table" 
    } ], 
    "source_filter_condition" : "id > 1" 
  } ], 
  "source" : "job", 
  "data_filter_type" : "common" 
}
  • 高级配置过滤条件，一般过滤条件中涉及到子查询，需要提前配置高级配置过滤条件 
    https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs/c7debc9c-8e09-4a5d-8dd6-cc44f78jb20r/filter-rules 
 
{ 
  "advanced_setting_list" : [ { 
    "db_name" : "test_drs", 
    "table_name" : "mysql5", 
    "col_names" : "id", 
    "prim_key_or_indexes" : "id", 
    "indexes" : "id", 
    "values" : "id > 1" 
  } ], 
  "source" : "job", 
  "data_filter_type" : "config" 
}
  • 一般过滤条件中涉及到子查询的场景 
    https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs/c7debc9c-8e09-4a5d-8dd6-cc44f78jb20r/filter-rules 
 
{ 
  "general_filtering_list" : [ { 
    "filter_object_list" : [ { 
      "id" : "test_drs-*-*-mysql3", 
      "parent_id" : "test_drs", 
      "object_name" : "mysql3", 
      "object_alias_name" : "test-*-*-mysql3", 
      "object_type" : "table" 
    } ], 
    "source_filter_condition" : "id in (select id from test_drs.mysql5 where id > 1)" 
  } ], 
  "source" : "job", 
  "data_filter_type" : "common" 
}

响应示例

状态码：200

OK

""

状态码：400

Bad Request

{ 
  "error_code" : "DRS.10020001", 
  "error_msg" : "The parameter general_filtering_list is empty" 
}

状态码

状态码

描述

200

OK

400

Bad Request

其他状态请参见状态码。

错误码

请参见错误码。

父主题： 数据加工