AppFolio 速率限制
概述
AppFolio 的 Stack API 對每個合作夥伴實施速率限制,以保護共享的物業管理基礎設施。大量操作如批量租戶匯入、租金同步和工單批次更新,可能會迅速耗盡配額。在每月底租約續約和付款處理高峰期間,管理數百個單位的物業經理在執行夜間資產組合同步時,必須謹慎進行限流。
先決條件
- 從當前的 AppFolio 合作夥伴合約或回應標頭中取得每個端點的已驗證限制值;請勿對租戶寫入使用通用的速率值。
- 每個寫入操作都需有持久化的批次游標和冪等性鍵,以及一個運營策略,用於在月底或其他安全敏感工作負載期間暫停操作。
- 擁有一個沙盒測試裝置和請求配額管理員,能夠在不影響生產環境租戶的情況下,驗證重試、
429行為以及未知寫入處理。
指示
- 選擇特定端點的限流上限,並將並發數控制在最小適用資產組合或合作夥伴限制之下。
- 在每次請求前獲取一個權杖,遵循
Retry-After標頭,並對暫時性供應商故障進行具有抖動的重試上限。 - 使用冪等性鍵從持久化的游標處理寫入操作;切勿因為回應遺失就重播租戶建立請求。
- 對於耗盡重試配額、遇到維護窗口或寫入結果未知的批次,應暫停並上報處理。
速率限制參考
| 端點 | 限制 | 時間窗口 | 範圍 |
|---|---|---|---|
| 物業列表/取得 | 120 次請求 | 1 分鐘 | 每個合作夥伴金鑰 |
| 租戶建立/更新 | 30 次請求 | 1 分鐘 | 每個合作夥伴金鑰 |
| 工單 | 60 次請求 | 1 分鐘 | 每個合作夥伴金鑰 |
| 批量資料匯出 | 5 次請求 | 1 小時 | 每個合作夥伴金鑰 |
| Webhooks 註冊 | 10 次請求 | 1 分鐘 | 每個合作夥伴金鑰 |
限流器實作
class AppFolioRateLimiter {
private tokens: number;
private lastRefill: number;
private readonly maxTokens: number;
private readonly refillRate: number; // tokens per ms
constructor(maxPerMinute: number) {
this.maxTokens = maxPerMinute;
this.tokens = maxPerMinute;
this.lastRefill = Date.now();
this.refillRate = maxPerMinute / 60_000;
}
async acquire(): Promise<void> {
for (;;) {
this.refill();
if (this.tokens >= 1) {
this.tokens -= 1;
return;
}
// 等待直到下一個權杖可用;無需後續請求來喚醒此調用者。
const waitMs = Math.max(1, Math.ceil((1 - this.tokens) / this.refillRate));
await new Promise(resolve => setTimeout(resolve, waitMs));
}
}
private refill() {
const now = Date.now();
this.tokens = Math.min(this.maxTokens, this.tokens + (now - this.lastRefill) * this.refillRate);
this.lastRefill = now;
}
}
const limiter = new AppFolioRateLimiter(25); // 根據端點合約配置
重試策略
async function appfolioRetry<T>(fn: () => Promise<Response>, maxRetries = 4): Promise<T> {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
await limiter.acquire();
const res = await fn();
if (res.ok) return res.json();
if (res.status === 429) {
const retryAfter = parseInt(res.headers.get("Retry-After") || "10", 10);
const delay = retryAfter * 1000 + Math.random() * 2000;
await new Promise(r => setTimeout(r, delay));
continue;
}
if (res.status >= 500 && attempt < maxRetries) {
await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
continue;
}
throw new Error(`AppFolio API ${res.status}: ${await res.text()}`);
}
throw new Error("超過最大重試次數");
}
批次處理
async function batchSyncTenants(tenants: any[], batchSize = 25) {
const results: any[] = [];
for (let i = 0; i < tenants.length; i += batchSize) {
const batch = tenants.slice(i, i + batchSize);
const batchResults = await Promise.all(
batch.map(t => appfolioRetry(() =>
fetch(`${BASE}/api/v1/tenants`, {
method: "POST", headers, body: JSON.stringify(t),
})
))
);
results.push(...batchResults);
if (i + batchSize < tenants.length) await new Promise(r => setTimeout(r, 2000));
}
return results;
}
錯誤處理
| 問題 | 原因 | 修正 |
|---|---|---|
| 429 請求過多 | 超出合作夥伴速率限制 | 使用 Retry-After 標頭進行退避 |
| 批量匯出 403 | 達到每小時匯出上限 | 將匯出排隊,間隔 15 分鐘 |
| 物業列表逾時 | 資產組合過大(500 個以上單位) | 使用 per_page=50 分頁 |
| 租戶更新 409 衝突 | 同時寫入同一租戶 | 使用新 ETag 重試 |
| 維護期間 503 | 排定的夜間維護窗口(太平洋時間凌晨 2-4 點) | 跳過請求,窗口結束後重試 |
輸出
- 一個自排程、端點特定的限流器,不會擱置佇列中的工作
- 具有
Retry-After證據和經過編輯的失敗資料的有界重試結果 - 一個持久化的批次決策:完成、暫停以供稍後重試,或隔離以供操作者調解
範例
對於沙盒環境的租戶更新批次,請將限制器設定低於記錄的租戶寫入上限,使用冪等性鍵逐筆處理記錄,並在每次確認結果後保留游標。觸發一個 429 錯誤以證明調用者會等待並在無需額外請求的情況下恢復,然後觸發一個回應遺失的情況,以證明該記錄會被隔離而不是盲目重播。如果速率標頭與配置的上限衝突、重試耗盡或維護開始,請暫停批次並將游標交給操作者。
資源
後續步驟
請參閱 appfolio-performance-tuning。