Console SDK(Java)
Java 管理面 SDK(io.agentbase.console:agentbase-console-java-sdk)覆盖 Console / 管理面 API:组织与项目治理、Key 与平台注册、跨项目运维。与 Server SDK(../server-sdk/java.md)可同 classpath 并用。Node / Python / Go 面见同目录 nodejs.md / python.md / go.md。
制品与安装
ZIP 交付包(不发布到 Maven registry),托管在 agentbase-sdks release v2.10.0;下载、双层 SHA256SUMS 校验与 mvn install:install-file 完整步骤见 ../integration.md(路径二)。与 Server SDK 的 Client 同名、namespace 独立:同一 Java 文件只 import 一个,另一个用全限定类名;两边的 model / enum / service 禁止混用。
初始化与认证装载
import io.agentbase.console.Client;
import io.agentbase.console.services.Projects;
Client consoleClient = new Client()
.setEndpoint(System.getenv("APPBASE_ENDPOINT")) // 实例 API 地址,包含 /v1
.setProject("console")
.setCookie(System.getenv("APPBASE_SESSION_COOKIE")); // 完整 Cookie header 值
// 若采用已取得的短期 Console JWT,用下一行替代 setCookie,二者只选一种:
// consoleClient.setJWT(System.getenv("APPBASE_CONSOLE_JWT"));setCookie 接收完整 Cookie 请求头值,不是 Session ID。凭据从受控环境载入,不写进源码或日志。用户身份仍须具备目标组织/项目的相应权限;setKey 方法存在不代表所有管理端点支持 API Key,不能用普通项目 Key 代替 Console 用户身份。
典型治理调用
方法为位置参数风格,同步返回:
new io.agentbase.console.services.Projects(consoleClient)
.getUsageAggregates("<projectId>"); // 三级用量(最近 30 个 UTC 日;注意方法名与 JS 的 listUsageAggregates 不同)组织、成员、平台注册(createPlatform)等 Console-only 操作不能用项目 API Key。
功能面导航
治理域到服务的全量映射见 nodejs.md「功能面导航」;各域功能页:组织、项目与 Key、配额、用量、站点与域名、平台运维。
Java Console 面特有差异:
- **无
Sql服务**:SQL 走 HTTP 形态或 JS Console SDK(../databases/sql-proxy.md)。 - 配额与限频方法已提供:
Projects.getQuotaLimits/updateQuotaLimits与getLimits/updateLimits/deleteLimits分别对应/quota-limits和/limits;返回Object,没有专用响应模型。字段与继承上限见配额。 - 三级用量方法名为
getUsageAggregates——不要按 JS 命名猜测。 - checked 异常类型为
io.agentbase.console.exceptions.AgentbaseException,可通过getCode()/getType()区分 HTTP 状态和错误类型。
各语言调用示例
以下按功能域给出各语言调用示例;每个卡片可切换语言(全页同步)。
建团队、项目与签发 Key
Python 方法名为 snake_case、Go 为 facade New* 构造器 + With* 可选项。该域无 REST 直调页签,REST 直调见下文「配额与限频」卡。
- Console(Node)
- Java
- Python
- Go
import { Client, Teams, Projects, ID, Scopes } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // https://appbuild.oceanbase.com/v1
.setProject(process.env.APPBASE_CONSOLE_PROJECT_ID!); // Console 项目,常为 console
const teams = new Teams(client);
const team = await teams.create({ teamId: ID.unique(), name: 'My Team' });
const projects = new Projects(client);
const project = await projects.create({
projectId: ID.unique(),
name: 'todo-app',
teamId: team.$id,
region: 'default' // 不使用 Appwrite Cloud 的区域枚举
});
const key = await projects.createKey({
projectId: project.$id,
name: 'setup-script',
scopes: [Scopes.UsersRead, Scopes.UsersWrite] // scope 最小化
});
// key.secret 仅创建时返回一次// 在 Console 项目中创建 Team 时,服务同步建立兼容的组织与成员记录。
// 使用返回的 team.getId(),不要从其他组织的页面 URL 猜测 Team ID。
io.agentbase.console.services.Teams teams = new io.agentbase.console.services.Teams(consoleClient);
var team = teams.create(
io.agentbase.console.ID.unique(), "My Team", java.util.List.of("owner"));
Projects projects = new Projects(consoleClient);
var project = projects.create(
io.agentbase.console.ID.unique(), "billing-service", team.getId(),
io.agentbase.console.enums.Region.DEFAULT, null, // poolTag 可空
null, null, null, null, null, null, null, null, null, null,
null); // powercontextEnabled;完整参数顺序以当前 Java 制品为准
var key = projects.createKey(project.getId(), "ci-deploy",
java.util.List.of(io.agentbase.console.enums.Scopes.USERS_READ,
io.agentbase.console.enums.Scopes.USERS_WRITE),
null, null, null);
// 将 key.getSecret() 交给受控凭据存储;不要输出到终端或日志。from agentbase_console.services.projects import Projects
from agentbase_console.services.teams import Teams
teams = Teams(console_client) # console_client 初始化见上文「初始化与认证装载」
projects = Projects(console_client)
teams.create(team_id='my-team', name='My Team', roles=['owner'])
project = projects.create(project_id='unique()', name='My Project', team_id='my-team')
key = projects.create_key(
project_id=project.id,
name='server key',
scopes=['users.read', 'users.write', 'teams.read', 'teams.write'],
key_id='unique()')
print(key.secret) # 只在创建响应出现一次// consolefacade "agentbase-console-go-sdk/agentbase";consoleClient 初始化见上文
consoleTeams := consolefacade.NewTeams(consoleClient)
consoleProjects := consolefacade.NewProjects(consoleClient)
_, _ = consoleTeams.Create("my-team", "My Team", consoleTeams.WithCreateRoles([]string{"owner"}))
project, _ := consoleProjects.Create("unique()", "My Project", "my-team")
key, _ := consoleProjects.CreateKey(project.Id, "server key", []string{
"users.read", "users.write", "teams.read", "teams.write",
})
fmt.Println(key.Secret) // 只在创建响应出现一次用量查询
三级聚合(最近 30 个 UTC 日)与旧口径是两套体系,方法名不可互猜(见 用量)。
- Console(Node)
- Java
- Python
- Go
// account / organizations / projects 为 Console SDK 对应 service 实例
await account.listUsageAggregates();
await organizations.listUsageAggregates({ organizationId: '<organizationId>' });
await projects.listUsageAggregates({ projectId: '<projectId>' });// Java Console SDK 生成名是 getUsageAggregates(与 JS 的 listUsageAggregates 不同名)
new io.agentbase.console.services.Projects(consoleClient)
.getUsageAggregates("<projectId>"); // 项目级
new io.agentbase.console.services.SelfHostedOrganizations(consoleClient)
.getUsageAggregates("<organizationId>"); // 组织级(端点同 JS organizations 面)
// 账号级(/account/usage/aggregates)在 console-java 无 typed 方法,走 REST 直调
// 旧口径 /project/usage 使用另一个业务项目 Client,避免覆盖管理面 Client 上下文。
io.agentbase.console.Client projectClient = new io.agentbase.console.Client()
.setEndpoint(System.getenv("APPBASE_ENDPOINT"))
.setProject(System.getenv("APPBASE_PROJECT_ID"))
.setMode("admin")
.setCookie(System.getenv("APPBASE_SESSION_COOKIE"));
new io.agentbase.console.services.Project(projectClient)
.getUsage(java.time.Instant.now().minus(29, java.time.temporal.ChronoUnit.DAYS).toString(),
java.time.Instant.now().toString(),
io.agentbase.console.enums.ProjectUsageRange.ONE_DAY);
// 旧接口 startDate/endDate 必填;setMode("admin") 选择 Console 用户的项目管理上下文,仍校验成员权限。# Python 2.6.0 事实源(appbase release-2.6.0@c0ae98d2,app_base/services)无三级聚合
# typed 方法:无 list_usage_aggregates / get_usage_aggregates;唯一 usage 面是
# self_hosted_organizations.get_usage(organization_id, range=None)(旧口径)。
# Console wheel 源码不在事实源内,三级聚合不要按 JS 命名互猜,走 Node / Java / REST// Go 2.6.0 事实源(server-go@release-2.6.0)无三级聚合方法:全域目录无 UsageAggregates
// 面,唯一旧口径是 selfhostedorganizations.GetUsage(organizationId, WithGetUsageRange)。
// Console Go 面 2.7.0 起交付且不在事实源内,三级聚合不要按 JS 命名互猜,走 Node / Java / REST配额与限频(Java 与 REST)
Java Console SDK 的 Projects 已提供以下位置参数方法;调用者须具有目标项目所属组织的 Owner 权限,具体字段和继承规则见配额与限频。返回 Object,请按该页的响应字段解析。
Projects projects = new Projects(consoleClient);
Object quotas = projects.getQuotaLimits("<projectId>");
Object limits = projects.getLimits("<projectId>");
// 修改接口:updateQuotaLimits(projectId, databaseStorageLimit, storageLimit,
// databasesPerProject, tablesPerProject)
// updateLimits / deleteLimits 的参数顺序见配额功能页;null 表示不修改对应字段。同一管理身份也可直调 REST。以下 0 仅在继承上限同样允许不限量时有效;不要将示例直接用于不符合该条件的项目:
- REST(curl)
# 查询当前配额与限频:
curl -sS "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-b "$APPBASE_SESSION_COOKIE"
# 设置:PATCH 同路径;限频字段必须为正整数,配额还受继承上限约束
curl -sS -X PATCH "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-b "$APPBASE_SESSION_COOKIE" \
-d '{"databaseStorageLimit": 0}'
# 字段全集与字段名陷阱见上方“配额与限频”链接示例指引
- Java(Server / Console)完整调用写法:../examples/java.md
事实源
skills/ob-agentbase/references/java-console-sdk.mdskills/ob-agentbase/references/console-sdk.md- appbase v2.10.0(
0a5d23f9349028496286572fd43117aa6f8fce0a):Projects Usage/Limits、Teams Create 与管理面认证实现。 - agentbase-sdks v2.10.0(
394f2a53dacfc2494f1f3e71082d9f09b9734ff1):packages/sdks/console-java/src/main/java/io/agentbase/console/;制品摘要见仓库发布证据。