api-billing-service-onboarding

API 计费服务接入

自动完成将新的第三方 API 服务接入基于 AWS Lambda 的计费和配额监控系统的整个流程。

目的

此技能提供了分步工作流，用于将新的 API 服务集成到现有的 AWS 监控基础设施中，以跟踪多个第三方服务的账户余额、配额和使用情况。系统每 30 分钟监控一次服务，将指标推送到 CloudWatch，通过 SNS 向飞书发送告警，并在集中式仪表板上展示数据。

适用场景

用户提出以下需求时，请使用此技能：

• 为新的 API 服务添加余额、配额或额度监控
• 为第三方服务的低余额或低配额设置告警
• 将新服务集成到计费仪表板
• 监控外部 API 的剩余用量或支出

常见触发语句：

• “将 [Service] 添加到监控中”
• “监控 [Service] API 余额”
• “为 [Service] 设置配额告警”
• “在仪表板中跟踪 [Service] 额度”

项目背景

监控系统位于 /path/to/monitoring-system/，由以下部分组成：

• 运行时：Node.js 18.x（TypeScript）
• 云平台：AWS Lambda + CloudWatch + Secrets Manager + EventBridge + SNS
• 命令：通过 just 管理（参见 justfile）
• 架构：EventBridge（30 分钟）→ Lambda → CloudWatch Metrics → Alarms → SNS → 飞书

关键文件：

• adapters/*.ts - API 服务适配器
• adapters/index.ts - 适配器注册表
• src/handler.ts - Lambda 入口点
• src/types.ts - BillingMetric 接口
• src/metrics.ts - CloudWatch 指标发布
• CLAUDE.md - 项目文档

工作流

第 1 步：收集服务信息

开始实现前，向用户收集以下信息：

1. 服务名称（例如，“resend”、“sendgrid”）
2. API 文档 URL（尤其是余额／配额端点）
3. API Key／Token（将存储在 Secrets Manager 中）
4. 告警阈值（绝对值或百分比）
5. 服务显示名称（用于仪表板标签）

需要询问的问题：

• “查询余额／配额的 API 端点是什么？”
• “API 如何进行身份验证？（Bearer token、API key 请求头、查询参数？）”
• “API 返回什么格式的响应？（JSON 结构）”
• “什么阈值应触发告警？（例如，剩余量 < 100，或 < 5%）”
• “服务使用什么单位？（USD、额度、邮件、请求？）”

第 2 步：创建 API 适配器

在 adapters/<service_name>.ts 创建一个新的 TypeScript 适配器文件。

参考：references/adapter-templates.md，其中包含三种常见适配器模式：

• 包含余额字段的标准 JSON 响应
• 响应头中包含配额信息
• 不含总量的预付费额度

适配器必须：

1. 调用服务的 API 获取余额／配额
2. 对 API key 进行脱敏（显示前 6 位和后 6 位字符）
3. 返回一个 BillingMetric 对象，包含：
   • service：小写的服务标识符
   • apiKeyMask：脱敏后的 API key
   • total：配额／余额总量
   • remaining：剩余配额／余额
   • remainingRatio：剩余量／总量（0-1）
   • currency（可选）：“USD”、“CNY”等
   • unit（可选）：“额度”、“邮件”、“请求”

使用 Read 工具查看现有适配器以供参考：

• adapters/resend.ts - 响应头配额模式
• adapters/serper.ts - 预付费额度模式
• adapters/scrapedo.ts - 标准 JSON 响应模式

第 3 步：注册适配器

编辑 adapters/index.ts：

1. 导入新的适配器函数
2. 在 adapters 对象中添加条目

示例：

import { fetchServiceName } from "./service_name";

export const adapters = {
  // ... existing adapters
  service_name: fetchServiceName,
};

第 4 步：更新 Lambda 处理程序

编辑 src/handler.ts，添加服务调用逻辑。

位置：在 console.log("✅ Billing check completed") 之前插入

模式：

// <Service Display Name>
if (apiKeys.<service_name>) {
  try {
    console.log("🔍 Fetching <Service> quota...");
    const metric = await adapters.<service_name>(apiKeys.<service_name>);
    await pushMetrics(metric);
    results.push({
      service: "<service_name>",
      status: "success",
      remaining: metric.remaining,
      total: metric.total,
      ratio: metric.remainingRatio
    });
  } catch (error: any) {
    console.error("❌ <Service> error:", error.message);
    results.push({ service: "<service_name>", status: "error", error: error.message });
  }
}

第 5 步：将 API Key 添加到 Secrets Manager

使用辅助脚本安全地添加 API key：

scripts/add-secret-key.sh <service_name> <api_key>

手动替代方案：

# Get current secrets
aws secretsmanager get-secret-value \
  --secret-id api-billing-monitor/keys \
  --query SecretString --output text > /tmp/secrets.json

# Edit /tmp/secrets.json to add: "<service_name>": "<api_key>"

# Update secrets
aws secretsmanager update-secret \
  --secret-id api-billing-monitor/keys \
  --secret-string file:///tmp/secrets.json

步骤 6：构建和部署

# Quick deployment (recommended)
just deploy-quick

# Or full deployment with verbose output
just deploy

验证部署：

# Trigger Lambda manually
just invoke

# Check logs for the new service
just logs | grep <service_name>

步骤 7：创建 CloudWatch 告警

选择合适的告警策略：

策略 A：绝对值阈值（适用于固定额度）：

aws cloudwatch put-metric-alarm \
  --alarm-name "<Service>-Low-Balance" \
  --namespace "ThirdPartyAPIBilling" \
  --metric-name "Remaining" \
  --dimensions Name=Service,Value=<service_name> \
  --statistic Average \
  --period 1800 \
  --evaluation-periods 1 \
  --threshold <absolute_value> \
  --comparison-operator LessThanThreshold \
  --alarm-actions "arn:aws:sns:us-east-1:830101142436:CloudWatchAlarmsToFeishu" \
  --alarm-description "<Service> remaining balance below <threshold>"

策略 B：百分比阈值（适用于可变额度）：

aws cloudwatch put-metric-alarm \
  --alarm-name "<Service>-Low-Ratio" \
  --namespace "ThirdPartyAPIBilling" \
  --metric-name "RemainingRatio" \
  --dimensions Name=Service,Value=<service_name> \
  --statistic Average \
  --period 1800 \
  --evaluation-periods 1 \
  --threshold 0.05 \
  --comparison-operator LessThanThreshold \
  --alarm-actions "arn:aws:sns:us-east-1:830101142436:CloudWatchAlarmsToFeishu" \
  --alarm-description "<Service> remaining ratio below 5%"

验证告警是否创建：

just alarms | grep <Service>

步骤 8：更新 CloudWatch 控制面板

使用辅助脚本自动将服务添加到控制面板：

scripts/add-to-dashboard.sh <service_name> "<Service Display Name>" "<masked_api_key>"

手动替代方案：

1. 获取当前控制面板配置：

   aws cloudwatch get-dashboard \
     --dashboard-name "API-Billing-Monitor" \
     --query "DashboardBody" \
     --output text > /tmp/dashboard.json
   

2. 编辑 /tmp/dashboard.json，在 4 个位置添加服务：

   • “所有服务剩余比例趋势”的指标数组
   • “当前剩余比例”的指标数组
   • 新建一个小组件（可选，用于显示详细的服务图表）
   • “当前剩余额度/Credits”的指标数组

3. 更新控制面板：

   aws cloudwatch put-dashboard \
     --dashboard-name "API-Billing-Monitor" \
     --dashboard-body file:///tmp/dashboard.json
   

参考：references/dashboard-widget-template.json，查看小组件 JSON 结构示例。

步骤 9：更新项目文档

编辑 CLAUDE.md，将新服务添加到“已接入服务”表格中：

| <service_name> | <unit> | <threshold> | <description> |

步骤 10：验证

运行完整的验证清单：

# 1. Trigger monitoring
just invoke

# 2. Check logs for successful execution
just logs | grep "<service_name>"
# Expected: "✅ Metrics pushed for <service_name>"

# 3. Verify metrics in CloudWatch
aws cloudwatch list-metrics \
  --namespace ThirdPartyAPIBilling \
  --dimensions Name=Service,Value=<service_name>

# 4. Check alarm status
just alarms | grep "<Service>"

# 5. View current status
just status

# 6. Visit dashboard
echo "https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#dashboards/dashboard/API-Billing-Monitor"

成功标准：

• ✅ Lambda 日志显示指标推送成功
• ✅ CloudWatch 中存在该服务的指标
• ✅ 告警处于 OK 或 ALARM 状态（而非 INSUFFICIENT_DATA）
• ✅ 控制面板的所有图表均显示该服务
• ✅ just status 输出中显示该服务

故障排除

Lambda 执行失败：

• 检查日志：just logs
• 验证 Secrets Manager 中的 API 密钥：just secrets-full
• 使用 curl/Postman 手动测试 API 端点

CloudWatch 中未显示指标：

• 确认 Lambda 执行成功：just invoke
• 检查适配器代码是否存在错误
• 在日志中验证指标推送逻辑

控制面板未显示数据：

• 等待 30 分钟，完成首次执行周期
• 确认指标存在：aws cloudwatch list-metrics --namespace ThirdPartyAPIBilling
• 验证控制面板 JSON 语法

告警未触发：

• 检查告警配置：aws cloudwatch describe-alarms --alarm-names "<Service>-Low-Balance"
• 验证指标数据点是否存在
• 测试告警：just test-alarm <Service>-Low-Balance

备注

• 系统通过 EventBridge 每 30 分钟运行一次
• 所有 API 密钥都安全地存储在 AWS Secrets Manager 中
• 告警通过 SNS 发送到飞书 webhook
• CloudWatch 命名空间为 ThirdPartyAPIBilling
• 常用维度：Service=<service_name>、APIKey=<masked_key>

详细示例和边缘情况请参阅 references/service-integration-examples.md。