Docs
文档目录

权限字符串文法

本文定义 Agentbase 资源级访问控制(ACL)权限字符串的完整文法,以及它在结构化表/行(TablesDB)、文档集合/文档(DocumentsDB)、存储桶/文件(Storage)、知识库(KnowledgeBases)与词库(Lexicons)等资源上的判定语义。

服务与资源边界

权限字符串是 Agentbase 平台实现多租户、多角色细粒度数据隔离的核心声明式机制:

资源与基础路径

字段名方向类型约束说明
permissions请求体 / 表单string[]单资源最多 100 条(部分容器支持更高上限)传入的资源级或容器级权限字符串数组;省略时保留默认或原权限
$permissions响应体string[]只读系统属性服务端归一化校验后持久化的权限字符串数组
rowSecurity表配置boolean默认 false为 true 时启用行级 $permissions 独立授权
documentSecurity集合配置boolean默认 false为 true 时启用文档级 $permissions 独立授权
fileSecurity存储桶配置boolean默认 false为 true 时启用文件级 $permissions 独立授权

认证与权限

服务端访问与资源级权限的关系

文法

一条合法的权限字符串由 动作("角色") 构成(角色标识必须包裹在英文双引号内):

read("any")
write("user:user_zhangwei_001")
create("label:admin")
update("team:team_tier2_support")
delete("team:team_tier2_support/owner")

动作集合(在各语言 SDK 中由 Permission 工具类生成):

动作适用层级语义说明
read容器级 & 资源级允许读取单个资源详情或在列表中检索到该资源
create仅容器级(表/集合/桶)允许在父容器下创建新行、新文档或上传新文件;对单条子资源本身无意义
update容器级 & 资源级允许修改既有资源的业务字段或元数据(含原子递增/递减操作)
delete容器级 & 资源级允许删除既有资源
write容器级 & 资源级写入聚合别名(在容器级等价于 create + update + delete,在资源级等价于 update + delete);切勿对同一角色同时混用 write 与细粒度写动作

角色集合(在各语言 SDK 中由 Role 工具类生成):

角色字符串语法匹配对象与语义说明
any任何请求方(同时涵盖已登录用户与未登录匿名访客)
guests仅限未登录的匿名访客(无 Session 的请求;注意:已登录用户不匹配 guests)
users任意已登录用户(包括普通账号登录与匿名会话登录)
users/verified任意已完成邮箱或手机号验证(emailVerification=true 或 phoneVerification=true)的已登录用户
users/unverified任意尚未完成验证的已登录用户
user:<userId>指定用户 ID(如 user:user_zhangwei_001)
user:<userId>/verified指定用户 ID 且该账号必须处于已验证状态
user:<userId>/unverified指定用户 ID 且该账号处于未验证状态
team:<teamId>指定团队(如 team:team_tier2_support)下的全部正式成员
team:<teamId>/<role>指定团队中拥有特定角色(如 team:team_tier2_support/owner)的成员
member:<membershipId>指定团队成员关系记录 ID(即使该成员角色变更,只要 membership 存在即有效)
label:<name>拥有指定用户标签(如 label:vip、label:support_agent)的全部用户;标签通过 Users API 的 PUT /v1/users/{userId}/labels 维护

在各资源上的语义

行级与表级(TablesDB)

集合与文档(DocumentsDB / 旧版 Databases)

桶与文件(Storage)

知识库与词库(KnowledgeBases & Lexicons)

端点总览

以下汇总接受 permissions 数组配置的核心 REST API 端点分组:

模块容器级权限配置端点子资源级权限配置端点细粒度安全开关字段
TablesDBPOST/PUT /v1/tablesdb/{databaseId}/tables*POST/PATCH/PUT /v1/tablesdb/{databaseId}/tables/{tableId}/rows*rowSecurity
DocumentsDBPOST/PUT /v1/documentsdb/{databaseId}/collections*POST/PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents*documentSecurity
StoragePOST/PUT /v1/storage/buckets*POST/PUT /v1/storage/buckets/{bucketId}/files*fileSecurity
Lexicons—POST/PATCH /v1/lexicons*默认启用资源级权限

端点清单

方法 + 路径权限字段位置支持的动作集合用途
POST /v1/tablesdb/{databaseId}/tablesbody permissions[]read, create, update, delete, write创建业务表并设置表级权限与 rowSecurity
POST /v1/tablesdb/{databaseId}/tables/{tableId}/rowsbody permissions[]read, update, delete, write创建行记录并设置行级归属权限
POST /v1/storage/bucketsbody permissions[]read, create, update, delete, write创建存储桶并设置桶级权限与 fileSecurity
POST /v1/storage/buckets/{bucketId}/filesformData permissions[]read, update, delete, write上传文件并设置文件级访问策略
POST /v1/lexiconsbody permissions[]read, update, delete创建项目词库并设置读写删策略

端点详解

JSON 请求体与 Multipart 表单中的序列化差异

  1. JSON 请求体(application/json):permissions 为标准 JSON 字符串数组。由于每条权限字符串内部包含双引号(如 read("any")),在 JSON 字符串中必须对内部双引号进行反斜杠转义:"read(\"any\")"。

  2. Multipart 表单(multipart/form-data):在调用 POST /v1/storage/buckets/{bucketId}/files 上传文件时,数组参数通过重复同名 permissions[] 表单项传递,此时无需 JSON 外层引号转义,直接写 -F 'permissions[]=read("user:user_zhangwei_001")' 即可。

请求与响应

取值示例(curl body 写法)

以下示例基于展示项目 enterprise-ai-hub-210 演示常见权限组合在真实端点中的完整写法。

场景 1:创建客服业务表 customer_tickets(允许登录用户提单,二线团队与工单创建人可读写)

curl -X POST "https://appbuild-sit.oceanbase.com/v1/tablesdb/enterprise_biz_db/tables" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "customer_tickets",
    "name": "企业智能客服工单表",
    "rowSecurity": true,
    "permissions": [
      "create(\"users/verified\")",
      "read(\"team:team_tier2_support\")",
      "update(\"team:team_tier2_support/specialist\")",
      "delete(\"team:team_tier2_support/owner\")"
    ]
  }'

响应示例(201 Created):

{
  "$id": "customer_tickets",
  "$createdAt": "2026-10-22T02:00:00.000+00:00",
  "$updatedAt": "2026-10-22T02:00:00.000+00:00",
  "$permissions": [
    "create(\"users/verified\")",
    "read(\"team:team_tier2_support\")",
    "update(\"team:team_tier2_support/specialist\")",
    "delete(\"team:team_tier2_support/owner\")"
  ],
  "databaseId": "enterprise_biz_db",
  "name": "企业智能客服工单表",
  "enabled": true,
  "rowSecurity": true,
  "columns": [],
  "indexes": []
}

场景 2:创建工单行记录并授予客户 user_zhangwei_001 行级查看与补充权限

curl -X POST "https://appbuild-sit.oceanbase.com/v1/tablesdb/enterprise_biz_db/tables/customer_tickets/rows" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "rowId": "TK-20261022-001",
    "data": {
      "title": "OceanBase 向量索引 HNSW 构建参数咨询",
      "priority": "high",
      "status": "open",
      "customerId": "user_zhangwei_001"
    },
    "permissions": [
      "read(\"user:user_zhangwei_001\")",
      "update(\"user:user_zhangwei_001/verified\")",
      "read(\"label:support_agent\")"
    ]
  }'

场景 3:向 agent_multimedia_bucket 上传工单截图并设置 multipart/form-data 文件级权限

curl -X POST "https://appbuild-sit.oceanbase.com/v1/storage/buckets/agent_multimedia_bucket/files" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -F "fileId=unique()" \
  -F 'permissions[]=read("user:user_zhangwei_001")' \
  -F 'permissions[]=read("team:team_tier2_support")' \
  -F 'permissions[]=delete("team:team_tier2_support/owner")' \
  -F "file=@./ticket-attachment.png"

组合语义速查表

权限组合表达式实际生效边界
read("any")全公开可读(含匿名访客与已登录用户);常用于公开帮助文档或静态素材桶
read("users")仅限已登录会话可读;未登录请求返回 404
read("guests")仅限未登录匿名访客可读;用户一旦登录反而不再匹配该规则
read("user:u1") + read("label:vip")多角色并集:用户 u1 或任何带有 vip 标签的用户均可读取
update("team:dev/owner")仅 dev 团队中 membership roles 包含 owner 的成员可修改
user:<id>/verified仅当该用户完成邮箱或手机验证后才放行

错误与边界

HTTP 状态码错误类型 (type)触发原因修复与排障建议
400 Bad Requestgeneral_argument_invalid权限字符串缺少内部双引号(如誤写为 read(any))、使用了未知动作或角色 ID 超过 36 字符使用 SDK 的 Permission.read(Role.any()) 构造器,或严格写成 "read(\"any\")"
400 Bad Requestgeneral_argument_invalid在词库(/v1/lexicons)上传递了不支持的 create(...) 权限动作词库仅支持 read、update、delete 三种权限动作
401 Unauthorizedgeneral_access_forbidden客户端尝试授予自身未持有的角色(如非团队成员授予 team:other)由服务端 API Key 代为设置跨团队权限,或仅授予当前用户自身角色
404 Not Foundrow_not_found / storage_file_not_found开启了 rowSecurity=true 或 fileSecurity=true,但新创建的资源 $permissions 为空且使用客户端身份读取检查表/桶的细粒度安全开关,确认创建资源时已传入目标用户的 read(...) 权限

与 Server SDK 的对应

各语言 Server SDK(agentbase-node-sdk@2.10.0、agentbase-python-sdk==2.10.0 等)内置了强类型的 Permission 与 Role 构造器,避免手工拼接转义引号出错:

权限字符串字面量Node.js / TypeScript 写法Python 写法关联 API 文档
"read(\"any\")"Permission.read(Role.any())Permission.read(Role.any())databases/overview.md
"create(\"users/verified\")"Permission.create(Role.users('verified'))Permission.create(Role.users('verified'))databases/overview.md
"update(\"user:user_zhangwei_001\")"Permission.update(Role.user('user_zhangwei_001'))Permission.update(Role.user('user_zhangwei_001'))auth/users.md
"delete(\"team:dev/owner\")"Permission.delete(Role.team('dev', 'owner'))Permission.delete(Role.team('dev', 'owner'))auth/teams.md
"read(\"label:vip\")"Permission.read(Role.label('vip'))Permission.read(Role.label('vip'))storage.md