agentbase-docs

用量

这是什么 / 何时用

2.6.0 引入的三级用量聚合:Account / Organization / Project 三个层级,固定展示最近 30 个 UTC 日(当前 UTC 日 + 之前 29 天,响应 range 固定 '30d')。用于账单前预估、配额贴近度检查与项目资源消耗趋势。

四个 Meter:

Meter单位聚合
bandwidth_bytesbytessum
function_executionscountsum
storage_bytesbyteslast
users_totalcountlast

与旧口径(/project/usage、Storage.getUsage、TablesDB.listUsage 等)是两套体系:旧接口用于资源明细/兼容展示,range 与返回模型都不同,不可混用(见文末)。

前置

使用骨架

{
  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
  }]
}

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

三级用量聚合(Account / Organization / Project)

三级聚合为 Console SDK 专有入口(凭据 Console Session/JWT,项目 API Key 不可调用),不设 Node.js(Server)/Web 页签;组织级要求 owner / admin / analyst / billing 之一(见前置)。Java 走生成名 getUsageAggregates(组织级在 SelfHostedOrganizations,账号级无 typed 方法);Python / Go 事实源(appbase release-2.6.0 app_base/services、server-go@release-2.6.0)无三级聚合 typed 方法,页签省略。

// sdk.forConsole 为 Console SDK 客户端(Console Session 凭据),见 console-sdk/nodejs.md
await sdk.forConsole.account.listUsageAggregates();
await sdk.forConsole.organizations.listUsageAggregates({ organizationId: '<orgId>' });
await sdk.forConsole.projects.listUsageAggregates({ projectId: '<projectId>' });
// 返回 MeterUsageList:range 固定 '30d',aggregates[] 含 meter / quantity / complete / freshnessAt / reason

解析返回与展示规则

逐项渲染 aggregates[]:quantity=null 是「证据不足」,禁止转 0;complete=false 表示数据未闭合;bytes 与 count 分别格式化,sum 与 last 不能用同一种方式二次聚合;切换 scope 时取消旧请求并清空旧状态。Java 响应模型 MeterUsageList / MeterUsage 已按 console-java 制品源码核验;Python / Go 无响应模型逐字段事实源,页签省略。

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 的摘要/趋势

示例指引

事实源