团队
这是什么 / 何时用
项目内的团队与成员管理:把用户组织成 Team,用 Role.team(teamId[, role]) 在行 / 文件权限里做批量授权。何时用:协作空间(看板、共享文档)、按团队粒度的数据共享、成员角色分层(如 owner / member)。
注意区分:项目内 Team(本页)与管理面的组织(Console 场景的 Organization = Team,见 organization.md)。两者 API 同形但边界不同——组织管项目与成员计费,项目内团队只服务该项目的授权。
前置
- Server API Key:
teams.read/teams.write;客户端创建 / 管理自己的团队用用户 Session。 - 邀请成员需要消息可达(email 邀请依赖实例 SMTP)或直接用
userId。
使用骨架
- 建团队:
teams.create({ teamId, name, roles? })——创建者自动成为成员并持有roles中的角色(含owner);ID.unique()或自定义 ID。 - 查询 / 维护:
teams.list()(当前用户的团队)、teams.get(teamId)、teams.update(teamId, name?)(含 prefs 维护:getTeamPrefs/updateTeamPrefs)、teams.delete(teamId)(需 owner)。 - 邀请成员:
teams.createMembership({ teamId, roles, email? , userId?, phone?, url?, name? })——email / userId / phone 至少其一;url是接受邀请的跳转地址;新成员需确认(confirm)后完全生效。 - 成员管理:
listMemberships(teamId, queries?)、getMembership、updateMembership({ teamId, membershipId, roles })调整角色、updateMembershipStatus(处理邀请接受 / 加入状态)、deleteMembership移除。 - 授权使用:在行 / 文件
permissions中用Permission.read(Role.team(teamId))(可带成员角色Role.team(teamId, 'owner'));Client SDK 只能授予自己已加入的团队(见 permissions.md)。
关键参数与返回
| 调用 | 关键参数 | 返回 |
|---|---|---|
create | teamId、name、roles?(创建者角色) | Models.Team($id、name、total) |
createMembership | teamId、roles[]、email?/userId?/phone?、url?、name? | Models.Membership(confirm 状态、roles) |
updateMembership | teamId、membershipId、roles[] | Membership |
updateMembershipStatus | teamId、membershipId、userId、secret | Membership(邮件邀请链接携带凭据) |
listMemberships | teamId、queries? | MembershipList |
错误与边界
- 邀请需要对方确认:
confirm: false的成员关系尚未生效;依赖「已是成员」的授权要检查确认状态。 - 删除团队需要
owner角色;移除最后一个 owner 前先转移角色。 - Client SDK 不能把行授权给未加入的团队(401,
hasRole约束);跨团队授权由服务端完成。 - 邮箱邀请的接受链接域名必须在项目 Platform 内可达(浏览器跳转场景)。
- 团队成员数量与团队数量受项目 quota 约束;大量成员的团队膨胀会影响授权维护成本,细粒度场景配合 Function 代理(permissions.md)。
SDK 类别差异
- Client SDK(Web):
teams.create/list/get/update/delete+ 成员管理(用户 Session,管理自己所在的团队)。 - Server SDK:同一套方法面(管理员视角,可管理项目内全部团队);Java 为同步 typed model,Python 为 snake_case。
- Console SDK:
Teamsservice 在 Console 上下文里操作的是组织 Team(成员 / 邀请),不是项目内团队;不要混用两个上下文的teamId。 - 差异入口:client-sdk/web.md、
server-sdk/nodejs.md。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
建团队
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
import { Client, Teams, ID } from 'agentbase-node-sdk';
const teams = new Teams(client); // client 初始化见 server-sdk/nodejs.md
const team = await teams.create({ teamId: ID.unique(), name: 'backend', roles: ['owner'] });
// roles 为创建者角色,缺省 ["owner"];teamId 自定义或 ID.unique()import { Client, Teams, ID } from 'agentbase-web-sdk'; // 前提:用户已登录
const teams = new Teams(client);
// 用户 Session 只能管理自己所在的团队;把行 / 文件授权给未加入的团队会 401(hasRole 约束)
const team = await teams.create({ teamId: ID.unique(), name: 'my-team' });import io.agentbase.ID;
import io.agentbase.models.Team;
import io.agentbase.services.Teams;
Teams teams = new Teams(client); // client 初始化见 server-sdk/java.md
Team<Map<String, Object>> team = teams.create(ID.unique(), "backend", List.of("owner"));from agentbase.services.teams import Teams
teams = Teams(client) # client 初始化见 server-sdk/python.md
team = teams.create(team_id='backend-team', name='backend', roles=['owner'])teams := agentbase.NewTeams(client) // facade 构造器;client 已装载 API Key
team, err := teams.Create("backend-team", "backend", teams.WithCreateRoles([]string{"owner"}))curl -sS -X POST "$APPBASE_ENDPOINT/teams" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"teamId":"backend-team","name":"backend","roles":["owner"]}'
# roles 为创建者角色,缺省 ["owner"];teamId 最长 36 字符查询 / 维护
Server SDK 在管理员视角列出项目内全部团队;Web(用户 Session)只看到自己所在的团队。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
await teams.list(); // 项目内全部团队,支持 queries / search
const team = await teams.get('backend-team');
await teams.updateName('backend-team', 'backend-core'); // 团队 ID 不可变,仅改名
await teams.getPrefs('backend-team'); // 团队偏好(自由键值 JSON)
await teams.updatePrefs('backend-team', { theme: 'dark' }); // 整体覆盖写,全量替换既有偏好
await teams.delete('backend-team'); // 需 owner;级联删除成员关系,引用该团队的权限字符串立即失效const mine = await teams.list(); // 当前用户的团队
const team = await teams.get('my-team');
await teams.update('my-team', 'New Name');
await teams.delete('my-team');teams.list(null, null, null); // 项目内全部团队,支持 queries / search / total
var team = teams.get("backend-team");
teams.updateName("backend-team", "backend-core"); // 团队 ID 不可变,仅改名
teams.getPrefs("backend-team"); // 团队偏好(自由键值 JSON)
teams.updatePrefs("backend-team", Map.of("theme", "dark")); // 整体覆盖写,全量替换既有偏好
teams.delete("backend-team"); // 需 owner;级联删除成员关系,引用该团队的权限字符串立即失效teams.list() # 项目内全部团队,支持 queries / search
team = teams.get(team_id='backend-team')
teams.update_name(team_id='backend-team', name='backend-core') # 团队 ID 不可变,仅改名
teams.get_prefs(team_id='backend-team') # 团队偏好(自由键值 JSON)
teams.update_prefs(team_id='backend-team', prefs={'theme': 'dark'}) # 整体覆盖写(区别于合并语义)
teams.delete(team_id='backend-team') # 需 owner;级联删除成员关系,引用该团队的权限字符串立即失效_, err = teams.List() // 项目内全部团队,支持 queries / search
team, err := teams.Get("backend-team")
_, err = teams.UpdateName("backend-team", "backend-core") // 团队 ID 不可变,仅改名
_, err = teams.GetPrefs("backend-team") // 团队偏好(自由键值 JSON)
_, err = teams.UpdatePrefs("backend-team", map[string]interface{}{"theme": "dark"}) // 整体覆盖写
_, err = teams.Delete("backend-team") // 需 owner;级联删除成员关系,引用该团队的权限字符串立即失效
_ = teamcurl -sS "$APPBASE_ENDPOINT/teams" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 单个团队:GET /teams/{teamId};改名:PUT /teams/{teamId}(body:name,ID 不可变)
# 团队偏好:GET /teams/{teamId}/prefs;PUT /teams/{teamId}/prefs(body:prefs,整体覆盖)
# 删除(级联删除成员关系,需 owner):DELETE /teams/{teamId}邀请成员
email 邀请依赖实例消息通道可达,也可直接用 userId / phone。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const membership = await teams.createMembership({
teamId: team.$id,
roles: ['member'], // 自由字符串,team:<teamId>/<role> 按此判定
email: 'newbie@example.com', // email / userId / phone 至少其一
url: 'https://<project-domain>/accept-invite', // 邀请回跳地址;须在项目平台列表内,带 API Key 可省略
name: 'New Member'
});
// 响应中的 secret 供受邀人确认加入(邀请邮件同样下发),服务端应转发而不是代为确认const membership = await teams.createMembership({ teamId: team.$id, roles: ['member'], email: 'newmember@example.com' });import io.agentbase.models.Membership;
Membership membership = teams.createMembership(
team.getId(),
List.of("member"), // roles
"newbie@example.com", // email(与 userId / phone 至少其一)
null, // userId
null, // phone
"https://app.example.com/accept", // url:接受邀请的跳转地址
null // name
);membership = teams.create_membership(
team_id='backend-team',
roles=['member'], # 自由字符串,team:<teamId>/<role> 按此判定
email='newbie@example.com', # email / userId / phone 至少其一
url='https://<project-domain>/accept-invite', # 邀请回跳地址;须在项目平台列表内,带 API Key 可省略
name='New Member')
# 响应中的 secret 供受邀人确认加入(邀请邮件同样下发),服务端应转发而不是代为确认membership, err := teams.CreateMembership("backend-team", []string{"member"}, // roles 位置参数;team:<teamId>/<role> 按此判定
teams.WithCreateMembershipEmail("newbie@example.com"), // email / userId / phone 至少其一
teams.WithCreateMembershipUrl("https://<project-domain>/accept-invite"), // 须在项目平台列表内
teams.WithCreateMembershipName("New Member"))
_ = membership // 响应中的 secret 供受邀人确认加入,服务端应转发而不是代为确认curl -sS -X POST "$APPBASE_ENDPOINT/teams/backend-team/memberships" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"email":"newbie@example.com","roles":["member"],"url":"https://example.com/accept-invite","name":"New Member"}'
# email / userId / phone 至少其一;url 仅允许项目平台列表内的主机名(防开放重定向)
# 限流 10 次/小时;邀请 secret 只出现在本端点响应与邀请邮件中成员管理
confirm: false 的成员关系尚未生效;依赖「已是成员」的授权前先检查确认状态。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const members = await teams.listMemberships(team.$id); // 可传 queries 过滤分页
const one = await teams.getMembership(team.$id, membership.$id);
await teams.updateMembership({ teamId: team.$id, membershipId: membership.$id, roles: ['admin'] });
// roles 为完整的新角色数组(全量替换语义)
// 受邀人侧确认(邮件链接携带 userId + secret),确认后 confirm=true、joined 填充:
await teams.updateMembershipStatus({ teamId: team.$id, membershipId: membership.$id, userId: '<userId>', secret: '<secret>' });
await teams.deleteMembership(team.$id, membership.$id); // 该成员的 team:<teamId> 系权限立即失效const members = await teams.listMemberships('my-team');
await teams.updateMembership({ teamId: 'my-team', membershipId: '<membershipId>', roles: ['admin', 'member'] });
await teams.deleteMembership('my-team', '<membershipId>');
// 邀请确认由被邀请人侧完成teams.listMemberships(team.getId(), null, null, null);
var one = teams.getMembership(team.getId(), membership.getId());
teams.updateMembership(team.getId(), membership.getId(), List.of("admin")); // roles 为完整的新角色数组(全量替换)
// 受邀人凭邀请邮件携带的 userId + secret 确认(public 端点),确认后 confirm=true、joined 填充:
teams.updateMembershipStatus(team.getId(), membership.getId(), "<userId>", "<secret>");
teams.deleteMembership(team.getId(), membership.getId());members = teams.list_memberships(team_id='backend-team') # 可传 queries 过滤分页
one = teams.get_membership(team_id='backend-team', membership_id='<membership_id>')
teams.update_membership(team_id='backend-team', membership_id='<membership_id>',
roles=['admin']) # roles 为完整的新角色数组(全量替换)
# 受邀人侧确认(邮件链接携带 userId + secret),确认后 confirm=True、joined 填充:
teams.update_membership_status(team_id='backend-team', membership_id='<membership_id>',
user_id='<user_id>', secret='<secret>')
teams.delete_membership(team_id='backend-team', membership_id='<membership_id>') # team:<teamId> 系权限立即失效members, err := teams.ListMemberships("backend-team") // 可传 queries 过滤分页
one, err := teams.GetMembership("backend-team", "membership-id")
_, err = teams.UpdateMembership("backend-team", "membership-id", []string{"admin"}) // roles 位置参数,完整的新角色数组(全量替换)
// 受邀人凭邀请邮件携带的 userId + secret 确认,确认后 confirm=true:
_, err = teams.UpdateMembershipStatus("backend-team", "membership-id", "user-123", "<secret>")
_, err = teams.DeleteMembership("backend-team", "membership-id") // team:<teamId> 系权限立即失效
_, _ = members, onecurl -sS "$APPBASE_ENDPOINT/teams/backend-team/memberships" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 单条:GET /teams/{teamId}/memberships/{membershipId}
# 调整角色(全量替换):PATCH /teams/{teamId}/memberships/{membershipId}(body:roles)
# 移除成员:DELETE /teams/{teamId}/memberships/{membershipId}
# 受邀人凭 secret 确认加入:PATCH /teams/{teamId}/memberships/{membershipId}/status(body:userId + secret)授权使用
在行 / 文件 / 表的 permissions 中用 Role.team() 授权;Client SDK 只能授予自己已加入的团队。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
import { Permission, Role } from 'agentbase-node-sdk';
// 行 / 文件 / 表等资源的 permissions 参数:
const permissions = [
Permission.read(Role.team('backend-team')), // 全体成员
Permission.update(Role.team('backend-team', 'owner')), // 仅 owner 角色
];import { Permission, Role } from 'agentbase-web-sdk';
const permissions = [
Permission.read(Role.team('my-team')),
Permission.delete(Role.team('my-team', 'owner')),
];
// Client SDK 只能授予自己已加入的团队;授权给未加入的团队返回 401(hasRole 约束)// 行 / 文件 / 表等资源的 permissions 参数(Permission / Role 与 Query / ID 同在 io.agentbase 包):
List<String> permissions = List.of(
Permission.read(Role.team("backend-team")), // 全体成员
Permission.update(Role.team("backend-team", "owner"))); // 仅 owner 角色# 行 / 文件 / 表等资源的 permissions 参数(Permission / Role 构造器来自 agentbase 包):
permissions = [
Permission.read(Role.team('backend-team')), # 全体成员
Permission.update(Role.team('backend-team', 'owner')), # 仅 owner 角色
]
# 也可直接传语法字符串 list,如 'read("team:backend-team")'import (
"appbase-go-sdk/permission"
"appbase-go-sdk/role"
)
// 行 / 文件 / 表等资源的 permissions 参数:SDK 构造器生成权限字符串
// (permission.Read/Update/Delete(role) + role.Team(id, role),返回 string):
permissions := []string{
permission.Read(role.Team("backend-team", "")), // 全体成员
permission.Update(role.Team("backend-team", "owner")), // 仅 owner 角色
}
_ = permissionscurl -sS -X POST "$APPBASE_ENDPOINT/tablesdb/<DATABASE_ID>/tables" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"tableId":"comments","name":"Comments","rowSecurity":true,"permissions":["read(\"users\")","update(\"team:backend-team/owner\")"]}'
# 权限字符串出现在表 / 行 / 桶 / 文件等创建端点的 permissions 数组中;team:<teamId>/<role> 即团队成员角色示例指引
- 各语言写法集中在语言树
examples/;Java 的createMembership(email / userId / roles / url 参数位)与 Python 的teams.create(team_id/roles=['owner'])见skills/ob-agentbase/references/server-sdks/java.md、skills/ob-agentbase/references/server-sdks/python.md。
事实源
skills/ob-agentbase/references/server-sdks/java.md(Teams 小节)skills/ob-agentbase/references/client-sdks/web.md(团队 API)skills/ob-agentbase/references/database-permissions.md(Role.team授权)- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
teamsservice 面)