Console SDK(Python)
示例中的 <APPBASE_ENDPOINT_WITH_V1>、<APPBASE_CONSOLE_ORIGIN> 和 <APPBASE_CONSOLE_HOST> 均需按实际使用位置替换为目标环境信息;先确认环境再运行。
Python 管理面 SDK(pip 包 agentbase-console-python-sdk,import namespace agentbase_console)覆盖 Console / 管理面 API:组织与项目治理、Key 签发、跨项目运维,与 Server 包(../server-sdk/python.md)可在同一环境共存。Node / Java / Go 面见同目录 nodejs.md / java.md / go.md。
制品与安装
制品未发布到 PyPI:从 agentbase-sdks release ZIP 解压后 pip 安装 Console wheel,完整命令见 ../examples/python.md「获取与安装」。
初始化与认证装载
Console 登录响应体不含 session secret(只在 a_session_console cookie),先经原始 HTTP 登录取 cookie,再挂到 Console SDK client:
import re
import requests
from agentbase_console.client import Client as ConsoleClient
resp = requests.post(
'<APPBASE_ENDPOINT_WITH_V1>/account/sessions/email',
headers={'X-Appwrite-Project': 'console', 'Content-Type': 'application/json'},
json={'email': CONSOLE_EMAIL, 'password': CONSOLE_PASSWORD},
allow_redirects=False,
timeout=10,
)
if resp.status_code != 201:
raise RuntimeError(f'Console sign-in failed with HTTP {resp.status_code}')
secret = re.search(r'a_session_console=([^;]+)', resp.headers['set-cookie']).group(1)
console_client = (
ConsoleClient()
.set_endpoint('<APPBASE_ENDPOINT_WITH_V1>')
.set_project('console')
)
console_client.add_header('origin', '<APPBASE_CONSOLE_ORIGIN>')
console_client.add_header('x-forwarded-host', '<APPBASE_CONSOLE_HOST>')
console_client.add_header('Cookie', f'a_session_console={secret}')请将登录请求发往已配置的控制台 API 地址。请求须返回 HTTP 201,示例关闭自动跳转以避免把登录信息发往其他地址。将新签发的密钥直接保存在凭据管理系统中。
典型治理调用
服务面(agentbase_console.services)含 account、teams、projects、users、proxy、migrations 等;方法名与 Server 包同为 snake_case:
from agentbase_console.services.projects import Projects
from agentbase_console.services.teams import Teams
teams = Teams(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()',
)组织、成员、平台注册等 Console-only 操作不能用项目 API Key。
功能面导航
治理域到服务的全量映射见 nodejs.md「功能面导航」;各域功能页:组织、项目与 Key、配额、用量、站点与域名、平台运维。
错误与边界
Console Session cookie 与 OAuth 测试 Session 相互隔离;短期 JWT 场景
set_jwt(token),禁止写入日志。SQL 场景可给 Client 指向应用项目并配项目 API Key(../databases/sql-proxy.md)。
各语言调用示例
以下按功能域给出各语言调用示例;每个卡片可切换语言(全页同步)。
建团队、项目与签发 Key
Python 方法名为 snake_case、Go 为 facade New* 构造器 + With* 可选项。该域无 REST 直调页签,REST 直调见下文「配额与限频」卡。
- Console(Node)
- Java
- Python
- Go
运行前将目标控制台的短期管理 JWT 放入 APPBASE_ADMIN_JWT。
import { Client, Teams, Projects, ID, Scopes } from 'agentbase-console-sdk';
const token = process.env.APPBASE_ADMIN_JWT;
if (!token) throw new Error('Set APPBASE_ADMIN_JWT for the target Console');
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // <APPBASE_ENDPOINT_WITH_V1>
.setProject(process.env.APPBASE_CONSOLE_PROJECT_ID ?? 'console')
.setJWT(token);
const originalPrepareRequest = client.prepareRequest;
if (typeof originalPrepareRequest !== 'function') throw new Error('Redirect control unavailable');
client.prepareRequest = function (...args) {
const request = originalPrepareRequest.apply(this, args);
request.options.redirect = 'error';
return request;
};
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,
});
const key = await projects.createKey({
projectId: project.$id,
name: 'setup-script',
scopes: [Scopes.UsersRead, Scopes.UsersWrite] // scope 最小化
});
// key.secret 仅创建时返回一次// 组织 = Team:Teams.create(teamId, name, roles)(位置参数,POST /teams),
// team.getId() 填入下方 projects.create 第 3 个位置参数;create 位置参数全集见同目录 java.md「快速上手」
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);
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);
// 将此次创建响应中的密钥直接保存到凭据管理系统。# console_client 初始化见上文「初始化与认证装载」;完整步骤见上文「快速上手」
from agentbase_console.services.projects import Projects
from agentbase_console.services.teams import Teams
teams = Teams(console_client)
projects = Projects(console_client)
teams.create(team_id='my-team', name='My Team', roles=['owner']) # Console 的 Organization = Team
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()')// consolefacade "agentbase-console-go-sdk/agentbase";consoleClient 初始化见同目录 go.md
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",
})
_ = key // 将此次创建响应中的密钥直接保存到凭据管理系统。用量查询
三级聚合(最近 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 直调
// 旧口径:作用于 setProject 的当前项目(period 枚举 ONE_HOUR / ONE_DAY)
new io.agentbase.console.services.Project(consoleClient)
.getUsage(null, null, io.agentbase.console.enums.ProjectUsageRange.ONE_DAY);# 本文未提供 Python SDK 的三级用量聚合示例。
# 本节示例可使用 Node / Java / REST;Python 调用请核对所用 Console SDK
# 发布包的服务类、方法和参数,不要按 JS 命名推测。// server-go@release-2.6.0 无三级聚合方法
// 面,唯一旧口径是 selfhostedorganizations.GetUsage(organizationId, WithGetUsageRange)。
// Console Go 面自 2.7.0 起交付;本文未覆盖其三级聚合用法,请使用 Node / Java / REST,不按 JS 命名推测。配额与限频(REST 直调)
Python Console 面亦无 typed quota/ratelimit 证据,统一走 REST 入口:
- REST(curl)
# 查询当前配额与限频:
curl -sS "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_CONSOLE_API_KEY"
# 设置:PATCH 同路径,body 为扁平的限频 + 配额字段;Quota 0 = 不限量,RateLimit 必须正整数
curl -sS -X PATCH "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_CONSOLE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_CONSOLE_API_KEY" \
-d '{"databaseStorageLimit": 0}'
# 字段全集与字段名陷阱见 limits.mdx示例指引
Python(Server / Console)完整调用写法:../examples/python.md