AppFolio 속도 제한
개요
AppFolio Stack API는 공유된 부동산 관리 인프라를 보호하기 위해 파트너별 속도 제한을 적용합니다. 대량 세입자 가져오기, 임대료 동기화, 작업 지시서 배치 업데이트와 같은 고부하 작업은 신속하게 할당량을 소진시킬 수 있습니다. 수백 개의 유닛에 대해 야간 포트폴리오 동기화를 실행하는 부동산 관리자는 특히 월말에 임대 갱신과 결제 처리가 동시에 급증할 때 신중하게 스로틀링해야 합니다.
사전 요구 사항
- 현재 AppFolio 파트너 계약 또는 응답 헤더에서 확인된 엔드포인트별 한도; 세입자 쓰기 작업에 일반 속도 값을 사용하지 마십시오.
- 모든 쓰기 작업에 대한 영속성 배치 커서, 멱등성 키, 그리고 월말 또는 기타 안전에 민감한 작업을 일시 중지하기 위한 운영자 정책.
- 스테이징 환경과 요청 예산 소유자가 재시도,
429동작, 알 수 없는 쓰기 처리를 프로덕션 세입자에 영향을 주지 않고 증명할 수 있어야 합니다.
지침
- 특정 엔드포인트에 대한 제한기 상한을 선택하고 동시성을 해당 포트폴리오 또는 파트너 한도 이하로 유지하십시오.
- 각 요청 전에 토큰을 획득하고
Retry-After를 준수하며, 일시적인 공급자 장애에 지터(jitter)를 추가하여 재시도 횟수를 제한하십시오. - 멱등성 키와 함께 영속성 커서에서 쓰기를 처리하고, 응답이 손실되었다고 해서 세입자 생성을 다시 재생하지 마십시오.
- 재시도 예산이 소진되거나, 유지 보수 기간에 도달하거나, 알 수 없는 쓰기 결과가 발생한 배치는 일시 중지하고 에스컬레이션하십시오.
속도 제한 참조
| 엔드포인트 | 제한 | 기간 | 범위 |
|---|---|---|---|
| 속성 목록/조회 | 120 요청 | 1분 | 파트너 키당 |
| 세입자 생성/수정 | 30 요청 | 1분 | 파트너 키당 |
| 작업 지시서 | 60 요청 | 1분 | 파트너 키당 |
| 대량 데이터 내보내기 | 5 요청 | 1시간 | 파트너 키당 |
| 웹훅 등록 | 10 요청 | 1분 | 파트너 키당 |
속도 제한기 구현
class AppFolioRateLimiter {
private tokens: number;
private lastRefill: number;
private readonly maxTokens: number;
private readonly refillRate: number; // 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 Too Many Requests | 파트너 속도 제한 초과 | Retry-After 헤더를 사용하여 백오프 |
| 403 대량 내보내기 | 시간당 내보내기 한도 도달 | 15분 간격으로 내보내기 큐잉 |
| 속성 목록 시간 초과 | 대규모 포트폴리오 (500개 이상 유닛) | per_page=50으로 페이지네이션 |
| 409 세입자 업데이트 충돌 | 동일 세입자에 대한 동시 쓰기 | 새 ETag로 재시도 |
| 503 유지 보수 중 | 예정된 야간 유지보수 기간 (오전 2-4시 PT) | 요청 건너뛰고, 기간 후 재시도 |
출력
- 큐에 쌓인 작업을 중단 없이 처리하는 자체 예약형 엔드포인트별 제한기
Retry-After증거와 편집된 오류 데이터가 포함된 제한된 재시도 결과- 완료, 나중 재시도를 위해 일시 중지, 또는 운영자 조정을 위해 격리된 영속성 배치 결정
예제
샌드박스 세입자 업데이트 배치의 경우, 문서화된 세입자 쓰기 상한보다 낮게 제한기를 설정하고, 멱등성 키를 사용하여 한 번에 하나의 레코드를 처리하며, 각 확인된 결과 후 커서를 보존하십시오. 429를 유도하여 호출자가 대기하고 추가 요청 없이 재개됨을 증명한 후, 응답 손실을 유도하여 레코드가 맹목적으로 재생되지 않고 격리됨을 증명하십시오. 속도 제한 헤더가 설정된 상한과 충돌하거나, 재시도가 소진되거나, 유지보수가 시작되면 배치를 일시 중지하고 커서를 소유자에게 전달하십시오.
리소스
다음 단계
appfolio-performance-tuning 참조.