# 角色写入共享请求与结果

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

创建与更新复用请求形状，但必填性、初始权限、请求 ID 和失败后的确认动作不同，不能整表互换。

## 请求字段

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 角色名称，1–255 个 UTF-8 字节，不含空白或控制字符；不能使用系统保留名称。 |
| `description` | string | 否 | 角色说明，最多 4096 个 UTF-8 字节，不能含 NUL；省略或 null 保存为空字符串。 |
| `schema_version` | string | 是 | 权限定义返回的 schema_version。 |
| `request_id` | string | 否 | 本次保存的业务请求 ID，最多 64 个 UTF-8 字节，不含空白或控制字符。省略时由服务端生成。 |
| `expected_lifecycle_version` | integer | 是 | 预期角色生命周期版本，必须大于 0。 |
| `expected_policy_version` | integer | 是 | 预期应用策略版本。不小于 1。 |
| `expected_data_privilege_version` | integer | 否 | 预期数据权限版本。不小于 0。 |
| `statements` | object（对象数组） 或 null | 否 | 应用策略语句。 |
| `statements[].statement_id` | string | 否 | IAM 策略语句唯一标识。 |
| `statements[].action_id` | string | 对象提供时 | 权限动作。 |
| `statements[].resource_type` | string | 对象提供时 | 资源类型。 |
| `statements[].scope_mode` | string | 对象提供时 | 资源范围。取值：`all`、`resources`。 |
| `statements[].resource_id` | string | 否 | 资源 ID。 |
| `statements[].condition_hash` | string | 否 | 条件摘要。 |
| `statements[].target_action_id` | string | 否 | 被授予动作。 |
| `statements[].grant_scope_mode` | string | 否 | 转授范围。取值：`all`、`resources`、空字符串。 |
| `statements[].grant_resource_id` | string | 否 | 转授目标资源 ID，按当前权限定义与 scope 填写。 |
| `statements[].grant_delegatable` | boolean | 否 | 是否允许应用权限再转授。 |
| `data_privilege_mutations` | object（对象数组） 或 null | 否 | 增量数据权限变更。 |
| `data_privilege_mutations[].operation` | string | 对象提供时 | 操作。取值：`grant`、`revoke`。 |
| `data_privilege_mutations[].action_id` | string | 对象提供时 | 权限动作。 |
| `data_privilege_mutations[].resource_type` | string | 对象提供时 | 资源类型。取值：`database`、`table`。 |
| `data_privilege_mutations[].resource_id` | string | 对象提供时 | 资源 ID。 |
| `data_privilege_mutations[].privilege` | string | 对象提供时 | MatrixOne权限。取值：`create_table`、`select`、`insert`、`update`、`delete`。 |
| `data_privilege_mutations[].with_grant_option` | boolean | 否 | 授予权限时是否同时允许目标角色转授该数据权限。默认 false。 |
| `data_privilege_mutations[].row_column` | object 或 null | 表 SELECT grant 时 | 目标角色的行列规则处理。保留现有规则也需提交 mode=keep。 |
| `data_privilege_mutations[].row_column.mode` | string | 提供 row_column 时 | 处理模式。取值：`keep`、`set`、`clear`。 |
| `data_privilege_mutations[].row_column.draft` | object | mode=set 时 | 行列规则草稿。 |
| `data_privilege_mutations[].row_column.draft.black_column_list` | string（字符串数组） 或 null | 否 | 禁止访问的列集合。 |
| `data_privilege_mutations[].row_column.draft.rule_list` | object（对象数组） 或 null | 否 | 行过滤规则。 |
| `data_privilege_mutations[].row_column.draft.rule_list[].column` | string | 否 | 列名。 |
| `data_privilege_mutations[].row_column.draft.rule_list[].relation` | string | 否 | 条件连接关系。取值：`and`、`or`。 |
| `data_privilege_mutations[].row_column.draft.rule_list[].expression_list` | object（对象数组） 或 null | 否 | SQL 表达式规则。 |
| `data_privilege_mutations[].row_column.draft.rule_list[].expression_list[].operator` | string | 否 | 比较操作符。取值：`=`、`!=`、`>`、`>=`、`<`、`<=`、`like`、`regexp_like`、`in`、`not in`、`expression`。 |
| `data_privilege_mutations[].row_column.draft.rule_list[].expression_list[].expression` | string（字符串数组） 或 null | 否 | 条件值列表。 |
| `data_privilege_mutations[].row_column.draft.rule_list[].expression_list[].match_type` | string | 否 | 值匹配类型。取值：空字符串、`c`、`i`、`m`、`n`、`u`。 |

`statements` 按完整替换处理，省略、`null` 或 `[]` 都表示提交空的自定义策略，不会保留原数组。系统必需的基础权限由服务端处理。`data_privilege_mutations` 按增量处理，省略、`null` 或 `[]` 均不新增数据权限变更。仅想修改说明时，也要提交需要保留的完整应用策略。

对表授予 SELECT 时必须提供 `row_column`，保留现有规则使用 `{"mode":"keep"}`。撤销时可省略或使用 `clear`；其他数据权限不接受行列规则。实际设置或清除规则还需当前权限定义支持。

## 创建与更新的差异

创建不提交三个已有角色版本；必须有业务 request_id，并至少有一项有效初始权限。更新按实际三个版本并发保护，request_id 可省略；完整替换自定义应用策略，增量处理数据权限。系统所需 baseline 仍由服务端处理。

角色创建成功为 201，更新为 200，成功对象是 role_id、role_version、policy_version、data_privilege_version、session_invalidation_status、idempotent_replay、provisioning_state/version/error_code 和请求/追踪标识。只有 ready 是本接口提交成功结果，内部 pending/failed 不能冒充成功。

## 失败结果与规范冲突

本地回滚、跨 MatrixOne 操作停止、结果未知分别由 ErrIAMRoleWriteRolledBack、ErrIAMRoleWriteFailed、ErrIAMRoleWriteResultUnknown 表达。较旧业务目录仍写编辑失败恢复旧 snapshot；04 生命周期、07 公开合同及当前 role_update owner 已区分本地回滚与跨库停止、不反向恢复权限。不能保留“所有失败都恢复旧权限”的承诺，规范漂移单列内部待确认；不修改产品规范或实现。

创建未知结果保留原业务编号和原内容确认；更新省略编号是新保存，保留草稿、刷新实际状态并由用户明确再次保存，不把创建的表单锁定协议强加所有设置。只有已确认回滚的对应错误才可能给出 cause_code；失败/未知不能通过底层错误链推断未生效。
