agentbase-docs

权限字符串文法

本文定义 Agentbase 权限字符串的文法,以及它在表/行、集合/文档、桶/文件等资源上的语义。权限字符串出现在:行/文档/文件的 $permissions 与 permissions 参数、表/集合/桶的 $permissions 与 permissions 参数中。本文不定义端点——它约束的是各文档中 permissions 字段的取值。

文法

一条权限字符串 = 动作("角色"):

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

动作集合(SDK 由 Permission 类生成):

动作含义
read读取资源(列表与单个)
write写的聚合别名 = update + delete(含 create 语境的资源),不要与 update/delete/create 同时对同一角色使用
create在父资源下创建子资源(如表下建行)
update修改资源
delete删除资源

角色集合(SDK 由 Role 类生成):

角色字符串含义
any任何人(含已登录与匿名)
user:<userId>指定用户
user:<userId>/<status>指定用户且限定状态(verified / unverified)
users任意已登录用户(含匿名 Session)
users/<status>任意已登录用户且限定状态
guests仅匿名访客(无 Session 的请求;已登录用户不含在内)
team:<teamId>指定团队全部成员
team:<teamId>/<role>指定团队中拥有指定角色的成员
member:<membershipId>指定成员(按 membership 记录)
label:<name>拥有指定标签的用户(标签经 users 的 updateLabels 维护)

规则与限制:

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

在各资源上的语义

行级与表级(TablesDB)

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

桶与文件(Storage)

团队角色与成员

取值示例(curl body 写法)

以下示例展示常见组合在真实端点请求体中的写法。示例均携带服务端两头认证(见 通用约定);permissions 参数的意义是为最终用户设置资源级策略(Key 自身不受其约束)。

创建桶:任意登录用户可读,dev 团队 owner 角色可管理,admin 标签用户可建文件(权限字符串在 JSON 数组内含双引号,需按 JSON 转义写法保持原样):

curl -X POST "https://<your-endpoint>/v1/storage/buckets" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "bucketId": "app-assets",
    "name": "App Assets",
    "fileSecurity": true,
    "permissions": [
      "read(\"users\")",
      "update(\"team:dev/owner\")",
      "delete(\"team:dev/owner\")",
      "create(\"label:admin\")"
    ]
  }'

上传文件(multipart/form-data,数组字段用 permissions[] 形式;仅 vip 标签用户与文件属主可读,属主可改可删):

curl -X POST "https://<your-endpoint>/v1/storage/buckets/app-assets/files" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -F "fileId=unique()" \
  -F 'permissions[]=read("label:vip")' \
  -F 'permissions[]=read("user:66a9d8ef00f21")' \
  -F 'permissions[]=update("user:66a9d8ef00f21")' \
  -F 'permissions[]=delete("user:66a9d8ef00f21")' \
  -F "file=@./pink.png"

建表(rowSecurity=true 时行级权限才参与判定;公开可读、仅创建者可写自己的行):

curl -X POST "https://<your-endpoint>/v1/tablesdb/<DATABASE_ID>/tables" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": "comments",
    "name": "Comments",
    "rowSecurity": true,
    "permissions": [
      "read(\"any\")",
      "create(\"users\")",
      "update(\"user:66a9d8ef00f21/verified\")",
      "delete(\"user:66a9d8ef00f21/verified\")"
    ]
  }'

组合语义速查:

组合效果
read("any") 单独使用全公开(含匿名访客);匿名场景常见于素材桶
read("users")仅登录用户可读,匿名不可见(列表中表现为 404 语义)
read("guests")仅匿名访客可读,登录用户反而不含在内
read("user:u1") + read("label:vip")多角色并集:u1 与 vip 标签用户都可读
update("team:dev/owner")仅 dev 团队中拥有 owner 角色的成员可改
user:<id>/verified限定该用户邮箱/手机验证通过后的会话才生效
write("role-x") 与 update/delete 并存配置错误:write 已含 update+delete,去掉细粒度的两条

注意:create 动作只约束「在父资源下创建子资源」,对资源本身的读改删无效;标签来自用户资料(users.updateLabels),团队角色来自 membership 的 roles 数组,二者变更即时反映到权限判定。

与 Server SDK 的对应

权限字符串由各语言 SDK 的 Permission / Role 构造器生成,作为各文档中 permissions 参数的取值:

资源参数位置文档
表 / 行tables 与 rows 各创建/更新端点的 permissionsdatabases
集合 / 文档collections 与 documents 各创建/更新端点的 permissionsdatabases
桶 / 文件buckets 与 files 各创建/更新端点的 permissionsstorage

事实源