← 全部范例范例 02
读取积分响应头:从响应中审计每一笔扣费
你将构建: 一层轻薄的客户端包装,记录每次调用的花费与剩余额度,让你自己的日志成为计费审计轨迹。
| 分类 | API 基础 |
|---|---|
| 使用的操作 | POST /v1/data/contacts/verify-email |
| 积分 | 1 (最坏情况) |
| 测试密钥可用 | 是 —— 可在 qk_test_ 上运行,零积分 |
| 预计耗时 | ~5 分钟 |
| 前置条件 | 一把密钥,以及任何能读取响应头的 HTTP 客户端。 |
每次数据调用都带三个响应头
X-Credits-Charged 是本次调用的花费。X-Credits-Balance 是调用之后的剩余额度。X-Price-Book 标明扣费所依据的价目表,因此报价与扣费始终能追溯到同一套规则。
headers.sh
curl -i -X POST https://api.qannasapi.com/v1/data/contacts/verify-email \
-H "Authorization: Bearer $QANNAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "jane@acme.example"}'
# < HTTP/1.1 200 OK
# < X-Credits-Charged: 1 # what this call cost
# < X-Credits-Balance: 94 # what is left afterwards
# < X-Price-Book: public # which rules were applied记录扣费,而不是预估
把 HTTP 客户端包装一次,将这三个响应头与 request_id 一并记录。这样无需轮询用量端点就能按调用归集成本,而 request_id 正是扣费看起来有问题时客服会索取的东西。
metered_client.ts
export async function call(action: string, body: unknown) {
const res = await fetch(`${API}/v1/data/${action}`, {
method: "POST",
headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
body: JSON.stringify(body),
});
const json = await res.json();
// Your logs become the billing audit trail.
logger.info("qannas.call", {
action,
request_id: json.request_id,
charged: Number(res.headers.get("X-Credits-Charged")),
balance: Number(res.headers.get("X-Credits-Balance")),
});
return json;
}盯余额,别盯时钟
由于余额随每次调用返回,你可以基于手上已有的响应做限流或告警。既没有单独的配额端点需要轮询,花费与知晓之间也没有延迟。
throttle.ts
// The balance arrives on the call you already made —
// there is no quota endpoint to poll and no lag.
const balance = Number(res.headers.get("X-Credits-Balance"));
if (balance < LOW_WATER_MARK) {
pauseNonUrgentJobs();
alertOps(`credits low: ${balance}`);
}小结
| 模式 | 做法 |
|---|---|
| 本次调用花了多少 | X-Credits-Charged |
| 还剩多少 | X-Credits-Balance |
| 套用了哪套规则 | X-Price-Book |
| 追溯一笔扣费 | 响应体中的 request_id |
| 限流 | 基于刚完成那次调用返回的 X-Credits-Balance 告警 |
上线检查清单
- 每次调用都记录 X-Credits-Charged、X-Credits-Balance 与 request_id。
- 基于余额响应头告警,而不是轮询用量端点。
- 保留 request_id —— 具体某笔扣费靠它追溯。
- 无结果时应预期 X-Credits-Charged: 0,不要当成失败。
下一步
先运行预估。它不花任何费用,用的正是计量器将要套用的那套算术。