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 与返回模型都不同,不可混用(见文末)。

前置

使用骨架

  1. 账号级:account.listUsageAggregates()。

  2. 组织级:organizations.listUsageAggregates({ organizationId })。

  3. 项目级:projects.listUsageAggregates({ projectId })。

  4. 解析返回 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
  }]
}
  1. 展示规则:切 scope 时取消旧请求并清空旧状态,新请求完成前不复用上一 scope 的摘要/趋势;bytes 与 count 分别格式化;sum 与 last 不能用同一种方式二次聚合。

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

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

三级用量聚合(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 的 release-2.6.0 SDK 无三级聚合 typed 方法,页签省略。

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

解析返回与展示规则

逐项渲染 aggregates[]:quantity=null 是「证据不足」,禁止转 0;complete=false 表示数据未闭合;bytes 与 count 分别格式化,sum 与 last 不能用同一种方式二次聚合;切换 scope 时取消旧请求并清空旧状态。Java 响应使用 MeterUsageList / MeterUsage;本文未提供 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 的摘要/趋势

示例指引