校验数据权限

检查指定角色的数据访问权限变更是否可应用，不会实际修改授权。根据校验结果调整变更后，仍需另行应用。

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/iam/roles/{role_id}/data-privileges:validate

调用前准备

先选择角色。再查看数据权限，确认当前授权状态并基于最新状态准备待校验的变更。

准备具有目标工作区相应权限的个人访问令牌和目标工作区 ID。

请求参数

输入示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/iam/roles/$ROLE_ID/data-privileges:validate" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req-001",
    "expected_data_privilege_version": 1,
    "mutations": [
      {
        "operation": "grant",
        "action_id": "table.query",
        "resource_type": "table",
        "resource_id": "table-001",
        "privilege": "select",
        "with_grant_option": false
      }
    ]
  }'

参数说明

路径参数

参数	类型	是否必填	说明
workspace_id	string	是	目标工作区 ID。
role_id	string	是	要校验数据权限的角色 ID。

请求体

参数	类型	是否必填	说明
request_id	string	是	调用方生成的请求 ID。
expected_data_privilege_version	integer	否	并发检查使用的数据权限版本；值不能小于 0。
mutations	array of object	是	要校验的权限变更，至少包含一项。
mutations[].operation	string	是	变更类型，只能为 grant 或 revoke。
mutations[].action_id	string	是	权限 Schema 中的数据操作 ID。
mutations[].resource_type	string	是	资源类型，只能为 database 或 table。
mutations[].resource_id	string	是	数据库或表的资源 ID。
mutations[].privilege	string	是	MatrixOne 权限名称。
mutations[].with_grant_option	boolean	否	是否允许目标角色转授该权限。
mutations[].row_column	object	否	表级行列规则；仅在需要设置、清除或保留行列规则时提交。
mutations[].row_column.mode	string	是	行列规则处理方式：keep、set 或 clear。
mutations[].row_column.draft	object	否	mode 为 set 时提交的行列规则。

成功响应

成功时返回校验结论。请求格式正确但权限草案无效时，接口仍可能返回 HTTP 200，此时 data.valid 为 false，并在 data.errors 中指出字段路径。

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "valid": true,
    "errors": [],
    "warnings": [],
    "payload_fingerprint": "sha256:example",
    "request_id": "req-001",
    "trace_id": "trace-001"
  }
}

字段说明

字段	类型	说明
code	string	成功时为 OK。
msg	string	成功时为 OK。
data.valid	boolean	权限变更是否通过校验。
data.errors	array of object	校验错误，每项包含错误代码和字段路径。
data.warnings	array of string	不阻止提交的警告。
data.payload_fingerprint	string	规范化请求内容的指纹。
data.request_id	string	请求关联 ID。
data.trace_id	string	链路追踪 ID。

错误响应

响应示例

{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}

字段说明

字段	类型	说明
code	string	错误代码。
msg	string	错误信息。
data	null	—

最后更新于 2026 年 9 月 11 日