api-billing-service-onboarding

API 課金サービスのオンボーディング

AWS Lambda ベースの課金・クォータ監視システムに、新しいサードパーティ API サービスを追加するプロセス全体を自動化します。

目的

このスキルでは、複数のサードパーティサービスのアカウント残高、クォータ、使用状況を追跡する既存の AWS 監視インフラストラクチャに、新しい API サービスを統合するための段階的なワークフローを提供します。システムは 30 分ごとにサービスを監視し、メトリクスを CloudWatch に送信し、SNS 経由で Feishu にアラートを送信し、一元管理されたダッシュボードにデータを可視化します。

使用するタイミング

ユーザーから次のような依頼があった場合に、このスキルを使用します。

• 新しい 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 メトリクス → アラーム → SNS → Feishu

主要なファイル：

• 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 キー／トークン（Secrets Manager に保存します）
4. アラートのしきい値（絶対値または割合）
5. サービスの表示名（ダッシュボードのラベルに使用）

質問する内容：

• 「残高／クォータを確認する API エンドポイントは何ですか？」
• 「API の認証方式は何ですか？（Bearer トークン、API キーヘッダー、クエリパラメーターなど）」
• 「API はどのような形式でレスポンスを返しますか？（JSON 構造）」
• 「どのしきい値でアラートを発生させますか？（例：残りが 100 未満、または 5% 未満）」
• 「サービスではどの単位を使用しますか？（USD、クレジット、メール、リクエストなど）」

ステップ 2：API アダプターを作成する

adapters/<service_name>.ts に新しい TypeScript アダプターファイルを作成します。

参照先：よく使われる 3 つのアダプターパターンについては、references/adapter-templates.md を参照してください。

• 残高フィールドを含む標準 JSON レスポンス
• クォータ情報を含むレスポンスヘッダー
• 合計額のないプリペイドクレジット

アダプターは次の処理を行う必要があります。

1. サービスの API を呼び出して、残高／クォータを取得する
2. API キーをマスクする（先頭 6 文字と末尾 6 文字を表示）
3. 次の内容を含む BillingMetric オブジェクトを返す：
   • service：小文字のサービス識別子
   • apiKeyMask：マスク済み API キー
   • 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：Secrets Manager に API キーを追加する

ヘルパースクリプトを使用して、API キーを安全に追加します。

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 か所にサービスを追加します：

   • 「全サービスの残り割合の推移」のメトリクス配列
   • 「現在の残り割合」のメトリクス配列
   • 新しいウィジェットを作成します（詳細なサービスチャートが必要な場合）
   • 「現在の残りクォータ／クレジット」のメトリクス配列

3. ダッシュボードを更新します：

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

参照先：ウィジェットの JSON 構造例については、references/dashboard-widget-template.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 を介して Feishu の webhook に通知します
• CloudWatch の名前空間は ThirdPartyAPIBilling です
• 共通ディメンション：Service=<service_name>、APIKey=<masked_key>

詳細な例や特殊なケースについては、references/service-integration-examples.md を参照してください。