行过滤接口

行过滤接口用于管理数据集的行级过滤策略，路径前缀为 /api/v1/row-filters。调用方需要相应的行过滤权限：创建需要创建权限，列表需要查看权限，编辑和启停需要修改权限，删除需要删除权限。

创建和编辑时，rowFilterConditions 至少包含一项。每项都要提供非空的过滤表达式 condition，并在 users、groups、roles 中至少指定一种适用对象。服务端会校验用户和用户组属于当前工作空间，以及角色属于当前租户；过滤表达式也会进行 SQL 校验。

条件字段	类型	是否必须	说明
rowFilterConditions[].condition	String	是	SQL 过滤条件，例如 region = 'CN'。
rowFilterConditions[].users	Array	否	适用用户。每个用户必须提供 username；userId 可选，传入时必须与该用户名对应。
rowFilterConditions[].groups	Array	否	适用用户组。每个用户组必须提供 userGroupId；name 可选。
rowFilterConditions[].roles	Array	否	适用角色。每个角色必须同时提供 roleId 和 roleName。

roleName 可使用 ADMIN、PLATFORM_ADMIN、DATA_ADMIN、DATA_ANALYST、DATA_ENGINEER。roleId 必须与当前租户及 roleName 对应，格式为 <tenantId>_<roleName>，例如 tn_2_DATA_ANALYST。请求中的用户对象无需提供 userRemoved；列表响应会返回这个由服务端计算的字段，表示策略引用的用户是否已被删除。

创建行过滤

请求方式：POST

接口地址：/api/v1/row-filters/create

请求参数：application/json 请求体。

参数名称	类型	是否必须	说明
name	String	是	策略名称，1～256 个字符。
description	String	否	描述，非空时最多 300 个字符。
datasetGuid	String	是	数据集 GUID，例如 "demo"."public"."orders"。
rowFilterConditions	Array	是	行过滤条件，字段说明见上文。

请求示例：

{
  "name": "订单区域过滤",
  "description": "限制指定角色查看的订单区域",
  "datasetGuid": "\"demo\".\"public\".\"orders\"",
  "rowFilterConditions": [
    {
      "condition": "region = 'CN'",
      "users": [{ "userId": 1001, "username": "alice" }],
      "groups": [{ "userGroupId": "group-1", "name": "销售组" }],
      "roles": [{ "roleId": "tn_2_DATA_ANALYST", "roleName": "DATA_ANALYST" }]
    }
  ]
}

响应示例：创建成功后不返回策略对象；可调用列表接口查询新策略。

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "traceId": "<trace-id>",
  "data": null
}

错误说明：参数无效、名称重复、数据集已存在行过滤策略、过滤条件 SQL 错误或缺少创建权限时，请求失败；错误码见文末。

列出行过滤

请求方式：GET

接口地址：/api/v1/row-filters/list

请求参数：查询参数。

参数名称	类型	是否必须	说明
search_key	String	否	策略搜索关键字。
status	Array	是	ENABLED 或 DISABLED；可重复传参以同时查询两种状态，不可重复同一状态。

请求示例：

GET /api/v1/row-filters/list?search_key=订单&status=ENABLED&status=DISABLED

响应示例：data 为策略数组。policyGuid 和 id 均可从列表结果取得，编辑时需要同时传入；删除和启停使用 policyGuid。角色对象只包含 roleId、roleName。

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "traceId": "<trace-id>",
  "data": [
    {
      "name": "订单区域过滤",
      "status": "ENABLED",
      "description": "限制指定角色查看的订单区域",
      "policyGuid": "123",
      "id": 123,
      "tableName": "orders",
      "tablePath": ["demo", "public", "orders"],
      "datasetGuid": "\"demo\".\"public\".\"orders\"",
      "datasetDeleted": false,
      "rowFilterConditions": [
        {
          "condition": "region = 'CN'",
          "users": [{ "userId": 1001, "username": "alice", "userRemoved": false }],
          "groups": [{ "userGroupId": "group-1", "name": "销售组" }],
          "roles": [{ "roleId": "tn_2_DATA_ANALYST", "roleName": "DATA_ANALYST" }]
        }
      ]
    }
  ]
}

datasetDeleted 表示策略关联的数据集是否已删除。若策略引用的用户已删除，该用户仍可能出现在列表中，此时 userId 为 null，userRemoved 为 true。

错误说明：status 值无效、重复，或缺少查看权限时，请求失败；错误码见文末。

编辑行过滤

请求方式：POST

接口地址：/api/v1/row-filters/edit

请求参数：application/json 请求体。

参数名称	类型	是否必须	说明
policyGuid	String	是	从列表响应取得的策略标识。
id	Long	是	从列表响应取得的策略数字 ID。
name	String	是	新策略名称，不能为空。
description	String	否	描述，非空时最多 300 个字符。
datasetGuid	String	是	数据集 GUID。
rowFilterConditions	Array	是	完整的行过滤条件，字段说明见上文。
status	String	否	无需传入；编辑会保留原有启停状态，修改状态请调用启停接口。

请求示例：

{
  "policyGuid": "123",
  "id": 123,
  "name": "订单区域过滤",
  "description": "更新后的过滤条件",
  "datasetGuid": "\"demo\".\"public\".\"orders\"",
  "rowFilterConditions": [
    {
      "condition": "region = 'CN' AND is_active = 1",
      "users": [{ "userId": 1001, "username": "alice" }],
      "roles": [{ "roleId": "tn_2_DATA_ANALYST", "roleName": "DATA_ANALYST" }]
    }
  ]
}

响应示例：

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "traceId": "<trace-id>",
  "data": null
}

错误说明：策略不存在、参数无效、名称重复、过滤条件 SQL 错误或缺少修改权限时，请求失败；错误码见文末。

删除行过滤

请求方式：POST

接口地址：/api/v1/row-filters/delete

请求参数：application/json 请求体。

参数名称	类型	是否必须	说明
policyGuid	String	是	要删除的策略标识。
name	String	是	策略名称，用于审计记录。

请求示例：

{
  "policyGuid": "123",
  "name": "订单区域过滤"
}

响应示例：成功删除，或策略已不存在时，均返回以下结构。

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "traceId": "<trace-id>",
  "data": null
}

错误说明：参数无效、删除失败或缺少删除权限时，请求失败；错误码见文末。

启用或停用行过滤

请求方式：POST

接口地址：/api/v1/row-filters/enable

请求参数：application/json 请求体。

参数名称	类型	是否必须	说明
policyGuid	String	是	要修改状态的策略标识。
newStatus	String	是	ENABLED 表示启用，DISABLED 表示停用。
name	String	是	策略名称，用于审计记录。

请求示例：

{
  "policyGuid": "123",
  "newStatus": "ENABLED",
  "name": "订单区域过滤"
}

响应示例：

{
  "success": true,
  "errorCode": null,
  "errorMsg": null,
  "traceId": "<trace-id>",
  "data": null
}

错误说明：状态值无效、策略不存在、更新失败或缺少修改权限时，请求失败；错误码见下表。

常见错误码

失败时响应中的 success 为 false，errorCode 和 errorMsg 给出错误信息。常见错误码如下；实际错误信息以响应为准。

错误码	说明
DWS98001	参数无效，包括适用对象缺失、用户或用户组无效、角色信息不匹配、状态无效。
DWS99001	当前调用方缺少对应的行过滤操作权限。
DWS60002	行过滤策略名称已存在。
DWS60017	数据集已有行过滤策略。
DWS60012	过滤条件 SQL 校验失败。
DWS60019	使用用户组变量的条件与所选用户不匹配。
DWS60011	查询指定策略失败或策略不存在。
DWS60005	删除策略失败。
DWS60007	编辑或更新策略失败。
DWS60010	创建策略失败。