用量
这是什么 / 何时用
2.6.0 引入的三级用量聚合:Account / Organization / Project 三个层级,固定展示最近 30 个 UTC 日(当前 UTC 日 + 之前 29 天,响应 range 固定 '30d')。用于账单前预估、配额贴近度检查与项目资源消耗趋势。
四个 Meter:
| Meter | 单位 | 聚合 |
|---|---|---|
bandwidth_bytes | bytes | sum |
function_executions | count | sum |
storage_bytes | bytes | last |
users_total | count | last |
与旧口径(/project/usage、Storage.getUsage、TablesDB.listUsage 等)是两套体系:旧接口用于资源明细/兼容展示,range 与返回模型都不同,不可混用(见文末)。
前置
- Account 级:Console Session/JWT,按当前有效项目成员关系汇总。
- Organization 级:active membership,角色
owner/admin/analyst/billing。 - Project 级:Console 项目上下文,服务端在请求前后复核读权限与删除状态。
- 方法名固定为 **
listUsageAggregates**(JS Console SDK 三个服务同名方法);不要猜getUsageAggregates()(那是 Server/Web SDK 账号/项目侧的另一组入口,见 SDK 差异)。
使用骨架
- 账号级:
account.listUsageAggregates()。 - 组织级:
organizations.listUsageAggregates({ organizationId })。 - 项目级:
projects.listUsageAggregates({ projectId })。 - 解析返回
MeterUsageList:
{
range: '30d', periodStart, periodEnd, complete, freshnessAt,
aggregates: [{
subjectType: 'project' | 'organization' | 'account',
subjectId, meter, meterVersion,
quantity, // number | null
unit: 'bytes' | 'count',
aggregation: 'sum' | 'last',
periodStart, periodEnd, complete, freshnessAt, reason
}]
}- 展示规则:切 scope 时取消旧请求并清空旧状态,新请求完成前不复用上一 scope 的摘要/趋势;
bytes与count分别格式化;sum与last不能用同一种方式二次聚合。
关键参数与返回
- **
quantity = null表示证据不足,绝不可转 0**(禁止?? 0);它与0、"不完整"是三种状态。 complete=false表示数据未闭合;freshnessAt是数据新鲜度水位(可能为 null)。reason枚举:child_missing(子项目缺失)、child_incomplete(子项目不完整)、source_watermark_unavailable(来源水位无法证明)。- 配额上限不等于用量:上限见 limits.md,展示时分别读取。
错误与边界
- 权限不足 / 非成员:401/403;组织级要求四种角色之一。
- 数据缺失是正常状态而非错误:按
quantity=null/complete=false/reason渲染,不要当失败重试。 - 用量来自后端 stats 聚合,非实时扫描;临近当前时刻的桶可能尚未闭合。
- 2.7.0 起组织用量汇总(
GET /organizations/{organizationId}/usage及聚合口径)只统计deletionStatus为空的活动项目,待删除/删除中项目不进入汇总与项目明细(appbase release-2.7.0 PR 520)。
SDK 类别差异
- Console SDK(console-sdk/nodejs.md):
account/organizations/projects三个服务的listUsageAggregates()——2.6.0 新增的规范入口。 - Server SDK / 客户端 SDK(server-sdk/nodejs.md / client-sdk/web.md):
account.getUsageAggregates()与projects.getUsageAggregates()(账号/项目两级的同类聚合,方法名不同)。 - Java Console SDK 的生成名是 **
getUsageAggregates**(new Projects(client).getUsageAggregates(projectId))——与 JS 的listUsageAggregates不同名,不要互相套用。 - 旧口径(兼容,Console SDK):
new Project(client).getUsage({ startDate, endDate, period })(period1h/1d,返回databasesStorageTotal/filesStorageTotal/ breakdown);storage.getUsage({ range })/storage.getBucketUsage({ bucketId, range });tablesDB.listUsage({ range })/tablesDB.getUsage({ databaseId, range })(range24h/30d/90d)。这些接口面向当前业务项目,不能直接复用setProject('console')的聚合用量 Client;Java 独立 Client 示例见 Console Java SDK。Databases 的同名方法已废弃,优先 TablesDB。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
三级用量聚合(Account / Organization / Project)
三级聚合为 Console SDK 专有入口(凭据 Console Session/JWT,项目 API Key 不可调用),不设 Node.js(Server)/Web 页签;组织级要求 owner / admin / analyst / billing 之一(见前置)。JS Console SDK 的 sdk.forConsole 包装对象未暴露 Organizations;组织级需从包导入 Organizations 并用 Console Client 实例化。Java 走生成名 getUsageAggregates(组织级在 SelfHostedOrganizations,账号级无 typed 方法);Python / Go 事实源(appbase release-2.6.0 app_base/services、server-go@release-2.6.0)无三级聚合 typed 方法,页签省略。
- Console(Node)
- Java
- REST(curl)
import { Client, Account, Organizations, Projects } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!)
.setProject(process.env.APPBASE_CONSOLE_PROJECT_ID!)
.setCookie(process.env.APPBASE_SESSION_COOKIE!); // Console Session,不使用项目 API Key
const account = new Account(client);
const organizations = new Organizations(client);
const projects = new Projects(client);
await account.listUsageAggregates();
await organizations.listUsageAggregates({ organizationId: '<orgId>' });
await projects.listUsageAggregates({ projectId: '<projectId>' });
// 返回 MeterUsageList:range 固定 '30d',aggregates[] 含 meter / quantity / complete / freshnessAt / reason// Java Console SDK 生成名是 getUsageAggregates,与 JS 的 listUsageAggregates 不同名,不要互相套用
// 项目级:
new io.agentbase.console.services.Projects(consoleClient)
.getUsageAggregates("<projectId>"); // GET /projects/{projectId}/usage/aggregates
// 组织级(Java 服务类名 SelfHostedOrganizations,端点同 JS organizations 面):
new io.agentbase.console.services.SelfHostedOrganizations(consoleClient)
.getUsageAggregates("<organizationId>"); // GET /organizations/{organizationId}/usage/aggregates
// 账号级(/account/usage/aggregates)在 console-java 无 typed 方法,走下方 REST 页签# 三级聚合统一走 Console Session/JWT(Cookie,-b),不是项目 API Key
# 账号级:
curl -sS "$APPBASE_ENDPOINT/account/usage/aggregates" \
-b "$APPBASE_CONSOLE_COOKIE"
# 组织级(需 owner / admin / analyst / billing 之一):
curl -sS "$APPBASE_ENDPOINT/organizations/<organizationId>/usage/aggregates" \
-b "$APPBASE_CONSOLE_COOKIE"
# 项目级:
curl -sS "$APPBASE_ENDPOINT/projects/<projectId>/usage/aggregates" \
-b "$APPBASE_CONSOLE_COOKIE"
# 返回 MeterUsageList;quantity=null 是「证据不足」,禁止转 0解析返回与展示规则
逐项渲染 aggregates[]:quantity=null 是「证据不足」,禁止转 0;complete=false 表示数据未闭合;bytes 与 count 分别格式化,sum 与 last 不能用同一种方式二次聚合;切换 scope 时取消旧请求并清空旧状态。Java 响应模型 MeterUsageList / MeterUsage 已按 console-java 制品源码核验;Python / Go 无响应模型逐字段事实源,页签省略。
- Console(Node)
- Java
- REST(curl)
const list = await sdk.forConsole.projects.listUsageAggregates({ projectId: '<projectId>' });
for (const agg of list.aggregates) {
if (agg.quantity === null) {
// 证据不足 ≠ 0:按缺失渲染,结合 agg.complete / agg.reason(child_missing | child_incomplete | source_watermark_unavailable)
continue;
}
// bytes 与 count 分别格式化;aggregation 为 'sum' 与 'last' 时不能用同一种方式二次聚合
console.log(agg.meter, agg.quantity, agg.unit, agg.complete, agg.freshnessAt);
}
// 切换 Account / Organization / Project 时取消旧请求并清空旧状态,新请求完成前不复用上一 scope 的摘要/趋势// MeterUsageList / MeterUsage 为 console-java 制品响应模型(io.agentbase.console.models)
io.agentbase.console.models.MeterUsageList list =
new io.agentbase.console.services.Projects(consoleClient).getUsageAggregates("<projectId>");
for (io.agentbase.console.models.MeterUsage agg : list.getAggregates()) {
if (agg.getQuantity() == null) {
// 证据不足 ≠ 0:quantity 为 Long,null 按缺失渲染,结合 getComplete() / getReason()
//(child_missing | child_incomplete | source_watermark_unavailable)
continue;
}
// bytes 与 count 分别格式化;aggregation 为 sum 与 last 时不能用同一种方式二次聚合
System.out.println(agg.getMeter() + " " + agg.getQuantity() + " " + agg.getUnit()
+ " complete=" + agg.getComplete() + " freshnessAt=" + agg.getFreshnessAt());
}
// 切换 Account / Organization / Project 时取消旧请求并清空旧状态,新请求完成前不复用上一 scope 的摘要/趋势curl -sS "$APPBASE_ENDPOINT/projects/<projectId>/usage/aggregates" \
-b "$APPBASE_CONSOLE_COOKIE"
# aggregates[] 每项含 meter / meterVersion / quantity(number|null) / unit / aggregation / periodStart / periodEnd / complete / freshnessAt / reason
# quantity=null 按缺失渲染(禁止转 0);complete=false 表示数据未闭合示例指引
- JavaScript(Console 三级用量 + Node 项目用量):examples/javascript.md
- Java:examples/java.md
事实源
- Java 方法与响应模型按 agentbase-sdks v2.10.0(
394f2a53dacfc2494f1f3e71082d9f09b9734ff1)console-java制品核对:Projects/SelfHostedOrganizations.getUsageAggregates、MeterUsageList/MeterUsage;Account未提供该聚合方法。 skills/ob-agentbase/references/usage-metering.mdskills/ob-agentbase/references/console-sdk.md(旧 usage 口径节)skills/ob-agentbase/references/release-2.6.0.md(三级用量为 2.6.0 能力)- appbase v2.7.0(tag v2.7.0);release-2.7.0 分支 PR 520(组织用量过滤删除态项目;v2.7.0 spec
GET /organizations/{organizationId}/usage描述实读确认) - agentbase-sdks v2.7.0 specs(
packages/sdks/console-web/src/services/{account,organizations,projects}.ts的listUsageAggregates;packages/sdks/server-nodejs/src/services/projects.ts的getUsageAggregates)