组织
这是什么 / 何时用
组织是 Agentbase 管理面的顶层协作单元:项目归属在组织下,成员与角色在组织上管理,组织级 API Key、计划 / 账单 / 用量也挂在组织维度。API 层的组织对应 canonical Team ID(teamId);Console 页面地址里的 organization-{organizationId} 是 Organization 公开 ID,两者可能不同,自动化时不要混用。何时用:搭建团队工作区、成员进出场、组织级凭据与账单/用量治理。
前置
Console 账号(托管环境为
appbuild-sit/appbuild对应账号),Console SDK 初始化见 console-sdk/nodejs.md(Java / Python / Go 面见同目录)与agentbase-console-sdk@2.8.0安装(integration.md)。Console SDK 先
setEndpoint+setProject('console')(或环境实际 Console project ID),再以邮箱密码 Session(或 OAuth Browser Session → 短期 JWT)认证。成员操作要求相应组织角色(owner / admin 等,以 Console 成员页展示的角色为准);组织级用量聚合要求
owner、admin、analyst或billing角色。
使用骨架
创建组织:Console 或 Console SDK 创建组织(内部即创建 Team),得到 canonical
teamId;页面地址为{consoleOrigin}/console/organization-{teamId}。成员与角色:向组织 Team 邀请成员(
Teams.createMembership,支持 email / userId / phone),用Teams.listMemberships/getMembership查询,Teams.updateMembership调整角色,Teams.updateMembershipStatus处理接受/加入状态,Teams.deleteMembership移除;成员操作留痕在Teams.listLogs。组织 API Key:Console SDK 的
Organizationsservice 提供组织 Key 的创建 / 列表 / 更新 / 删除(createKey/listKeys/getKey/updateKey/deleteKey)。注意:SDK 存在这些方法不代表目标实例一定开放对应路由;只有目标环境已通过受支持渠道交付了有效 Organization API Key 时才使用 Key 路径,否则用 Owner Session 或短期 Owner JWT(组织项目治理见 project-governance.md)。计划与账单(托管环境):
Organizations.getPlan/listInvoices/getInvoice/getInvoiceDownload、账单地址、积分与估算(getAvailableCredits/addCredit/estimationUpdatePlan等)。组织用量(2.6.0):
organizations.listUsageAggregates({ organizationId })返回组织维度最近 30 个 UTC 日的标准 Meter 聚合;quantity: null表示缺失,不得当 0。能力查询:
Organizations.getScopes、Organizations.listRegions查询组织可用的 scope 与区域。
关键参数与返回
| 调用 | 关键参数 | 返回 / 说明 |
|---|---|---|
| 创建组织 | 组织名称等 | 组织对象(canonical Team ID、成员、计划等元数据) |
Teams.createMembership | teamId、roles[]、email(可选) / userId(可选) / phone(可选)、url(可选;邀请跳转)、name(可选) | Membership(含确认状态 confirm) |
Organizations.createKey | 组织 ID、名称、scopes、过期等 | Key 元数据;secret 只在创建响应出现一次 |
Organizations.listUsageAggregates | organizationId | MeterUsageList(range: '30d',四 Meter,带 complete/freshnessAt/reason) |
Organizations.getScopes / listRegions | 组织 ID | 可用 scope 列表 / 可用 region(2.6.0 为 default) |
错误与边界
403 / 权限不足:当前账号不是目标组织成员或角色不够;跨组织操作一律拒绝。
把 Console 页面的公开 organizationId 当
teamId传给 API 是高频错误:API 用 canonical Team ID。组织 API Key 路径在未交付 Key 的环境不可用;普通项目 API Key 不能替代组织级 Key。
成员邀请需要对方确认(
confirm)后才完全生效;依赖「已是成员」的授权判断要检查确认状态。组织下最后一个 owner 不应被移除;删除组织前先处理其下项目(项目生命周期与治理见 overview.md、project-governance.md)。
SDK 类别差异
Console SDK(JS,
agentbase-console-sdk@2.8.0):组织管理的主体面(组织 CRUD、成员、组织 Key、计划账单、组织用量聚合)。Console Java SDK(2.6.0):
io.agentbase.console命名空间下没有Organizationsservice;组织级操作走 JS Console SDK 或 Console UI,Java 管理工具只覆盖项目 / 密钥 / 数据面等平行能力。Server / Client SDK:不承载组织管理;Client SDK 的组织相关边界只有组织项目治理(Owner Session +
setOrganization),见 project-governance.md。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
创建组织(Teams)
组织内部即 Team:Console SDK Teams.create 创建后 team.$id 即 canonical Team ID;REST 对应 POST /v1/teams。组织管理不经 Server / Client SDK。
- Console(Node)
- REST(curl)
import { Client, Account, Teams, ID } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 必须包含 /v1
.setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID!); // 'console' 或环境实际 Console project ID
const account = new Account(client);
await account.createEmailPasswordSession({
email: process.env.APPBASE_OWNER_EMAIL!,
password: process.env.APPBASE_OWNER_PASSWORD!
});
const teams = new Teams(client);
const team = await teams.create({
teamId: ID.unique(),
name: 'Acme Inc'
});
// team.$id 即 canonical Team ID:页面地址 {consoleOrigin}/console/organization-{teamId};
// 后续自动化一律用 team.$id,不要用页面公开 organizationIdcurl -sS -X POST "$APPBASE_ENDPOINT/teams" \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"teamId":"unique()","name":"Acme Inc"}'
# 201 返回 team($id 即 canonical Team ID);roles 缺省 ["owner"]成员与角色(Teams)
Console SDK 管理组织 Team 成员(组织管理不经 Server / Client SDK);REST 对应 teams 域端点(teams.read / teams.write scope)。
- Console(Node)
- REST(curl)
import { Client, Account, Teams } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 必须包含 /v1
.setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID!); // 'console' 或环境实际 Console project ID
const account = new Account(client);
await account.createEmailPasswordSession({
email: process.env.APPBASE_OWNER_EMAIL!, // 当前账号需具备组织管理角色
password: process.env.APPBASE_OWNER_PASSWORD!
});
const teams = new Teams(client);
const membership = await teams.createMembership({
teamId: '<canonical-team-id>', // canonical Team ID,不是页面公开 organizationId
roles: ['developer'],
email: 'bob@example.com', // email / userId / phone 至少提供其一
url: 'https://<console-origin>/join', // 邀请回跳 URL(可选)
name: 'Bob'
});
// membership.confirm=false 表示待对方确认;后续 updateMembership 调角色、updateMembershipStatus
// 处理确认、deleteMembership 移除、listMemberships / getMembership 查询,留痕见 Teams.listLogscurl -sS -X POST "$APPBASE_ENDPOINT/teams/<teamId>/memberships" \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"email":"bob@example.com","roles":["developer"],"url":"https://<console-origin>/join","name":"Bob"}'
# 201 返回 membership(confirm=false 待确认);邀请限流 10 次/小时
# 查询 GET /teams/{teamId}/memberships;调角色 PATCH /teams/{teamId}/memberships/{membershipId}
# 确认加入走 PATCH /teams/{teamId}/memberships/{membershipId}/status(凭邀请 secret,一般由受邀方完成);移除 DELETE 同路径组织 API Key(Organizations)
仅 JS Console SDK 提供(Java Console SDK 无 Organizations service,REST 亦无文档化端点);SDK 存在这些方法不代表目标实例开放对应路由。
- Console(Node)
const organizations = new Organizations(client); // client 初始化与认证见上一卡
const key = await organizations.createKey({
organizationId: '<canonical-team-id>',
name: 'ci-automation',
scopes: ['projects.read', 'projects.write']
});
console.log(key.secret); // secret 只在创建响应出现一次,立即入库保存
// 轮换面:listKeys / getKey / updateKey / deleteKey;过期等其余参数以 SDK 方法签名为准计划与账单(托管环境)
托管环境的计划 / 账单 / 积分能力仅 JS Console SDK 提供(Java Console SDK 无 Organizations service,REST 无文档化端点);账单地址与发票下载也可在 Console 页面操作。
- Console(Node)
const organizations = new Organizations(client); // client 初始化与认证见上一卡
// 计划与账单方法面(参数以 agentbase-console-sdk 方法签名为准):
// organizations.getPlan({ organizationId }) // 当前计划
// organizations.listInvoices({ organizationId }) // 发票列表
// organizations.getInvoice / getInvoiceDownload // 单张发票与下载
// organizations.getAvailableCredits({ organizationId }) // 可用积分
// organizations.addCredit / estimationUpdatePlan // 充值 / 变更估算组织用量聚合(2.6.0)
organizations.listUsageAggregates 返回组织维度最近 30 个 UTC 日的标准 Meter 聚合(组织用量属管理面,仅 Console SDK 与管理 REST 承载)。
- Console(Node)
- REST(curl)
const usage = await organizations.listUsageAggregates({ organizationId: '<organizationId>' });
// 返回 MeterUsageList:range '30d',四个 Meter(storage_bytes / bandwidth_bytes / users_total / function_executions)
// quantity: null 表示缺失,不得当 0;complete=false 表示数据未闭合curl -sS "$APPBASE_ENDPOINT/organizations/<organizationId>/usage/aggregates" \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-H "X-Appwrite-JWT: $APPBASE_OWNER_JWT"
# 要求 active membership 且角色为 owner / admin / analyst / billing(Console Session 或短期 JWT)能力查询(scopes / regions)
scope 与区域查询仅 JS Console SDK 提供(Java Console SDK 无 Organizations service,REST 亦无文档化端点);入参为组织 ID。
- Console(Node)
// organizations.getScopes:入参组织 ID,返回组织可用 scope 列表
// organizations.listRegions:入参组织 ID,2.6.0 返回 default 区域
// 两者入参形态(位置参数或对象)以 agentbase-console-sdk 方法签名为准示例指引
各语言写法集中在语言树
examples/;Console SDK 初始化 + 建 Team + 建项目 + 建 API Key 的组合序列另见 overview.md。