应用数据权限¶

提交指定角色的数据访问权限变更。请求被接受后，变更可能仍在处理；请继续查看处理结果，再确认授权是否完成。

PUT https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/iam/roles/{role_id}/data-privileges

调用前准备¶

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

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

请求参数¶

输入示例

curl -X PUT "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/iam/roles/$ROLE_ID/data-privileges" \
  -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，也是后续查看操作时使用的原请求 ID。
expected_data_privilege_version	integer	否	并发检查使用的数据权限版本；值不能小于 0。
mutations	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 时提交的行列规则。

成功响应¶

成功响应返回数据权限操作及各资源的执行状态。状态为 applying 时请求已经受理但尚未完成；使用原请求 ID 查看操作，直到状态变化。

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "request_id": "req-001",
    "trace_id": "trace-001",
    "operation_id": "operation-001",
    "audit_event_id": "audit-001",
    "state": "succeeded",
    "data_privilege_version": 2,
    "idempotent_replay": false,
    "session_invalidation_status": "new_connections_only",
    "matrixone_fact_version": "fact-v2",
    "resource_results": []
  }
}

字段说明

字段	类型	说明
code	string	成功时为 OK。
msg	string	成功时为 OK。
data.request_id	string	原请求 ID，用于查看本次操作。
data.operation_id	string	服务端生成的操作 ID。
data.audit_event_id	string	审计事件 ID。
data.state	string	操作状态：applying、succeeded、failed、drifted 或 unknown。
data.data_privilege_version	integer	操作后的数据权限版本。
data.idempotent_replay	boolean	是否为同一请求的幂等重放。
data.session_invalidation_status	string	会话权限刷新状态。
data.matrixone_fact_version	string	MatrixOne 权限事实版本。
data.resource_results	object（对象数组）	每个资源的权限执行结果。
data.trace_id	string	链路追踪 ID。

错误响应¶

响应示例

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

字段说明

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

后续操作¶

继续跟踪变更¶

使用本次变更的标识查看数据权限操作。处理尚未结束时继续查看；只有处理结束后，才能确认本次授权是否完成。

最后更新于 2026 年 9 月 3 日