用量統計 API

查詢你的儲存空間使用量與配額。

取得用量統計

GET /api/usage

回應

{
  "totalBytes": 52428800,
  "quota": 524288000,
  "remaining": 471859200,
  "percentage": 10,
  "status": "OK",
  "channels": {
    "C1234567890": {
      "bytes": 31457280,
      "bytesAtSubscribe": 1048576,
      "messageCount": 1500
    },
    "C0987654321": {
      "bytes": 20971520,
      "bytesAtSubscribe": 0,
      "messageCount": 800
    }
  },
  "syncedAt": "2025-01-15T08:00:00Z"
}

欄位說明

總覽

欄位	類型	說明
totalBytes	number	已使用空間（bytes）
quota	number	配額上限（bytes）
remaining	number	剩餘空間（bytes）
percentage	number	使用百分比（0-100）
status	string	用量狀態
syncedAt	string	最後同步時間

狀態說明

status	說明	百分比
OK	正常	< 80%
WARNING	警告	80% - 89%
CRITICAL	緊急	90% - 99%
EXCEEDED	超額	>= 100%

群組明細

每個群組的用量：

欄位	類型	說明
bytes	number	該群組目前用量
bytesAtSubscribe	number	訂閱時的用量基準
messageCount	number	訊息數量

備註

實際計費用量 = bytes - bytesAtSubscribe

方案配額

方案	配額	bytes
免費方案	500 MB	524,288,000
標準方案	50 GB	53,687,091,200
進階方案	500 GB	536,870,912,000

使用範例

檢查配額

async function checkQuota() {
  const response = await fetch('https://api.gm.kamigo.tw/api/usage', {
    headers: { Authorization: 'Bearer YOUR_API_KEY' }
  });
  const usage = await response.json();

  if (usage.status === 'EXCEEDED') {
    console.log('配額已超額，請升級方案');
  } else if (usage.status === 'CRITICAL') {
    console.log(`配額即將用盡，剩餘 ${formatBytes(usage.remaining)}`);
  }

  return usage;
}

function formatBytes(bytes) {
  if (bytes < 1024) return bytes + ' B';
  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
  if (bytes < 1024 * 1024 * 1024) return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
  return (bytes / (1024 * 1024 * 1024)).toFixed(1) + ' GB';
}

計算各群組用量

async function getChannelUsage() {
  const usage = await checkQuota();

  const channelUsage = Object.entries(usage.channels)
    .map(([channelId, data]) => ({
      channelId,
      actualUsage: data.bytes - data.bytesAtSubscribe,
      messageCount: data.messageCount
    }))
    .sort((a, b) => b.actualUsage - a.actualUsage);

  return channelUsage;
}

配額超額

當配額超額時：

1. 訊息備份暫停 - 新訊息不會被備份
2. API 仍可存取 - 可讀取已備份的訊息
3. 需要升級或清理 - 升級方案或刪除舊資料

解決方式

1. 升級方案

   • 在 Dashboard 升級到更高配額的方案

2. 清理資料

   • 取消不需要的群組訂閱
   • 刪除舊的備份資料

取得目前使用者

GET /api/me

回傳包含方案資訊：

{
  "userId": "U1234567890",
  "displayName": "王小明",
  "plan": "free",
  "quota": 524288000,
  "createdAt": "2025-01-15T08:00:00Z"
}

plan	說明
free	免費方案
standard	標準方案
pro	進階方案