# 配置行列数据权限

为工作区内的普通角色预校验并保存数据表查询权限与行列过滤规则，再按持久化操作回执确认数据库权限变更结果。

(sdk-ai-studio-data-privilege-flow)=
## 任务流程

```text
工作区 IAM 句柄 + 行列规则变更 JSON
               │
               ▼
1. 读取角色当前数据权限版本并预校验变更（仅校验，不执行数据库 DCL）
               │
               ▼
2. 提交同一变更请求 ──▶ 按请求标识查询操作回执与逐表执行状态
               │
               ▼
3. 重新读取角色数据权限视图确认最新版本号
```

(sdk-ai-studio-data-privilege-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. 按 [管理角色与对象权限](管理角色和权限.md#sdk-ai-studio-iam-s1) 获取允许修改策略的目标普通角色 ID。
3. 获取目标数据表 ID 与实际列名：可通过 IAM 句柄的权限资源查询方法列出可授权的数据表（传入资源类型 `table` 与动作 `table.query`），或结合 [管理目录、数据库和表](../资源中心/管理目录、数据库和表.md) 确认表 ID 与列结构。授权请求中必须填写数值型表 ID。
4. 准备变更 JSON 文件与唯一请求标识 `DATA_PRIVILEGE_REQUEST_ID`，并在确认操作终态前保留同一请求标识。

(sdk-ai-studio-data-privilege-validate)=
## 1. 读取版本并预校验变更

先读取目标角色当前的数据权限版本号，将其与本地变更数组组装为变更请求并执行预校验。预校验返回字段级错误、告警与标准化预览，确认 `valid` 为真后再进入保存步骤。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import json
import os
from pathlib import Path

from google.protobuf.json_format import MessageToDict, ParseDict
import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
iam = client.workspace(os.environ["WORKSPACE_ID"]).iam()
role_id = os.environ["TARGET_ROLE_ID"]
request_id = os.environ["DATA_PRIVILEGE_REQUEST_ID"]

view = iam.data_privileges(role_id)
mutations = json.loads(Path(os.environ["MUTATIONS_FILE"]).read_text(encoding="utf-8"))
request = ParseDict(
    {
        "request_id": request_id,
        "expected_data_privilege_version": view.data_privilege_version,
        "mutations": mutations,
    },
    sdk.IAMDataPrivilegeMutationRequest(),
)
print("Request:", request_id, "Expected version:", view.data_privilege_version)

validation = iam.validate_data_privileges(role_id, request)
print(MessageToDict(validation, preserving_proto_field_name=True))
if not validation.valid:
    raise SystemExit("Resolve validation errors before applying this request")
```

::::

::::{tab-item} Go
:sync: go

```go
package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
	"google.golang.org/protobuf/encoding/protojson"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	defer client.Close()
	workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	iam := workspace.IAM()
	roleID := os.Getenv("TARGET_ROLE_ID")
	requestID := os.Getenv("DATA_PRIVILEGE_REQUEST_ID")

	view, err := iam.DataPrivileges(ctx, roleID)
	if err != nil {
		panic(err)
	}
	raw, err := os.ReadFile(os.Getenv("MUTATIONS_FILE"))
	if err != nil {
		panic(err)
	}
	request := &sdk.IAMDataPrivilegeMutationRequest{}
	if err := protojson.Unmarshal(append(append([]byte(`{"mutations":`), raw...), '}'), request); err != nil {
		panic(err)
	}
	request.RequestId = requestID
	request.ExpectedDataPrivilegeVersion = view.GetDataPrivilegeVersion()
	fmt.Println("Request:", requestID, "Expected version:", view.GetDataPrivilegeVersion())

	validation, err := iam.ValidateDataPrivileges(ctx, roleID, request)
	if err != nil {
		panic(err)
	}
	encoded, err := protojson.MarshalOptions{UseProtoNames: true}.Marshal(validation)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(encoded))
	if !validation.GetValid() {
		panic("Resolve validation errors before applying this request")
	}
}
```

::::

:::::

`MUTATIONS_FILE` 文件内容为操作数组。以下示例授予表 `1001` 的查询权限，隐藏 `salary` 列，并通过行级规则排除 `region` 列取值为 `blocked` 或 `unknown` 的记录：

```json
[
  {
    "operation": "grant",
    "action_id": "table.query",
    "resource_type": "table",
    "resource_id": "1001",
    "privilege": "select",
    "row_column": {
      "mode": "set",
      "draft": {
        "black_column_list": [
          "salary"
        ],
        "rule_list": [
          {
            "column": "region",
            "relation": "and",
            "expression_list": [
              {
                "operator": "not in",
                "expression": [
                  "blocked",
                  "unknown"
                ]
              }
            ]
          }
        ]
      }
    }
  }
]
```

设置表查询权限时需显式指定 `row_column.mode`：写入新规则使用 `set`，沿用既有规则使用 `keep`，移除既有规则使用 `clear`；省略行列规则块不会自动清除已生效的行级或列级限制。

(sdk-ai-studio-data-privilege-apply)=
## 2. 保存变更并确认操作回执

核对预校验输出无误后，提交同一请求对象，再按 `DATA_PRIVILEGE_REQUEST_ID` 查询持久化操作回执，检查整体状态 `state`、逐资源执行结果以及连接失效状态，最后重新读取角色数据权限版本号。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
operation = iam.apply_data_privileges(role_id, request)
print(MessageToDict(operation, preserving_proto_field_name=True))

confirmed = iam.data_privilege_operation(role_id, request_id)
print(MessageToDict(confirmed, preserving_proto_field_name=True))
if confirmed.state != "succeeded":
    raise RuntimeError("Inspect operation receipt and per-resource errors before proceeding")

current = iam.data_privileges(role_id)
print("Current data privilege version:", current.data_privilege_version)
```

::::

::::{tab-item} Go
:sync: go

```go
operation, err := iam.ApplyDataPrivileges(ctx, roleID, request)
if err != nil {
	panic(err)
}
encoded, err = protojson.MarshalOptions{UseProtoNames: true}.Marshal(operation)
if err != nil {
	panic(err)
}
fmt.Println(string(encoded))

confirmed, err := iam.DataPrivilegeOperation(ctx, roleID, requestID)
if err != nil {
	panic(err)
}
encoded, err = protojson.MarshalOptions{UseProtoNames: true}.Marshal(confirmed)
if err != nil {
	panic(err)
}
fmt.Println(string(encoded))
if confirmed.GetState() != "succeeded" {
	panic("Inspect operation receipt and per-resource errors before proceeding")
}

current, err := iam.DataPrivileges(ctx, roleID)
if err != nil {
	panic(err)
}
fmt.Println("Current data privilege version:", current.GetDataPrivilegeVersion())
```

::::

:::::

:::{warning}
请求超时或返回部分失败时，底层数据库可能已执行部分授权语句。请先用原 `DATA_PRIVILEGE_REQUEST_ID` 查询操作回执并保留逐资源报错详情，切勿更换请求标识直接重提。需要基于数据库当前实际权限修复权限投影视图时，调用 IAM 句柄的数据权限修复方法并传入原操作请求标识与当前期望版本号；修复动作只回读受影响资源的当前数据库状态，不会重新执行原授权或撤销变更。
:::

连接失效策略可能仅约束新建立的数据库会话，操作回执变为 `succeeded` 后仍需结合回执中的会话刷新字段判断存量连接是否已刷新。

(sdk-ai-studio-data-privilege-next)=
## 下一步

- [管理角色与对象权限](管理角色和权限.md)
- [管理目录、数据库和表](../资源中心/管理目录、数据库和表.md)
