Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

透過限流和退避策略處理 AppFolio API 的速率限制。

tons-of-skills-marketplace 是什麼?

此技能為 AppFolio Stack API 提供一個端點感知的速率限制器,能有效管理每個合作夥伴的 API 配額,避免因大量物業管理操作(如批量租戶匯入、租金同步或工單更新)而觸發 429 錯誤。它採用權杖桶演算法實現精確的限流,並內建指數退避與隨機抖動的重試邏輯,以處理暫時性故障。支援批次處理、冪等性鍵與持久化游標,確保在失敗時不會重複執行租戶建立等寫入操作。與 Claude Code、Cursor 和 Codex 等 AI 代理平台相容,此技能會自動產生端點特定的限流器、有界的重試結果,以及批次決策(完成、暫停或隔離),供操作者進行調解。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/HEAD/plugins/saas-packs/appfolio-pack/skills/appfolio-rate-limits

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

AppFolio 速率限制

概述

AppFolio 的 Stack API 對每個合作夥伴實施速率限制,以保護共享的物業管理基礎設施。大量操作如批量租戶匯入、租金同步和工單批次更新,可能會迅速耗盡配額。在每月底租約續約和付款處理高峰期間,管理數百個單位的物業經理在執行夜間資產組合同步時,必須謹慎進行限流。

先決條件

  • 從當前的 AppFolio 合作夥伴合約或回應標頭中取得每個端點的已驗證限制值;請勿對租戶寫入使用通用的速率值。
  • 每個寫入操作都需有持久化的批次游標和冪等性鍵,以及一個運營策略,用於在月底或其他安全敏感工作負載期間暫停操作。
  • 擁有一個沙盒測試裝置和請求配額管理員,能夠在不影響生產環境租戶的情況下,驗證重試、429 行為以及未知寫入處理。

指示

  1. 選擇特定端點的限流上限,並將並發數控制在最小適用資產組合或合作夥伴限制之下。
  2. 在每次請求前獲取一個權杖,遵循 Retry-After 標頭,並對暫時性供應商故障進行具有抖動的重試上限。
  3. 使用冪等性鍵從持久化的游標處理寫入操作;切勿因為回應遺失就重播租戶建立請求。
  4. 對於耗盡重試配額、遇到維護窗口或寫入結果未知的批次,應暫停並上報處理。

速率限制參考

端點限制時間窗口範圍
物業列表/取得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。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page for positioning, plan a conversion-optimized page layout, or design a launch page. Examples: "landing page for product launch", "conversion-optimized layout for SaaS

jeremylongshore/tons-of-skills-marketplace

Use when asked to design growth-optimized landing pages, activation funnel layouts, or experiment-friendly page structures. Examples: "growth-optimized landing", "activation funnel layout", "A/B testable page

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page, design page layout for conversion, or plan landing page information architecture. Examples: "landing page structure for SaaS", "conversion-optimized layout

jeremylongshore/tons-of-skills-marketplace

Generate polished demo videos from a single prompt. Use when the user asks to create a demo video, product walkthrough, feature showcase, or animated presentation. Trigger with "make a demo video", "create a product video", "demo walkthrough", or "feature showcase video".

jeremylongshore/tons-of-skills-marketplace

Track cryptocurrency portfolio with real-time valuations, allocation analysis, and P&L tracking. Use when checking portfolio value, viewing holdings breakdown, analyzing allocations, or exporting portfolio data. Trigger with phrases like "show my portfolio", "check crypto holdings", "portfolio allocation", "track my crypto", or "export portfolio".

jeremylongshore/tons-of-skills-marketplace

Runs the full release workflow for the current project. Commits any uncommitted changes, pushes to remote, creates and merges a PR if on a feature branch, determines the next semver version from conventional commits, creates an annotated git tag and GitHub release with generated notes, cleans up merged branches, and returns to a clean main. Use when the user says promote, ship, release, commit and push, tag and release, or get back to main.

jeremylongshore/tons-of-skills-marketplace

Agent skill at plugins/productivity/content-multiplier/skills/channel-formats/SKILL.md

jeremylongshore/tons-of-skills-marketplace

Operate an evidence-backed editorial queue, balance topic and format coverage, schedule approved drafts, and reconcile backlog state with the publishing system. Use when choosing or scheduling the next blog work. Trigger with "show the editorial calendar" or "pick the next topic".

jeremylongshore/tons-of-skills-marketplace

Configure CI/CD pipeline for AppFolio property management integrations. Trigger: "appfolio CI".

jeremylongshore/tons-of-skills-marketplace

Diagnose and fix common AppFolio API integration errors. Trigger: "appfolio error".

jeremylongshore/tons-of-skills-marketplace

Build property management dashboard with AppFolio API data. Trigger: "appfolio property dashboard".

jeremylongshore/tons-of-skills-marketplace

Automate tenant management and lease operations with AppFolio. Trigger: "appfolio tenant management".

jeremylongshore/tons-of-skills-marketplace

Collect AppFolio API debug evidence for support tickets. Trigger: "appfolio debug".

jeremylongshore/tons-of-skills-marketplace

Deploy AppFolio integration service to cloud infrastructure. Trigger: "deploy appfolio".

jeremylongshore/tons-of-skills-marketplace

Query AppFolio properties, units, and tenants via REST API. Trigger: "appfolio hello world".

jeremylongshore/tons-of-skills-marketplace

Configure AppFolio Stack API authentication with OAuth 2.0. Use when setting up property management API access, registering as an AppFolio Stack partner, or configuring client credentials for API calls. Trigger: "install appfolio", "setup appfolio", "appfolio auth", "appfolio API key".

jeremylongshore/tons-of-skills-marketplace

Set up local development for AppFolio property management API integration. Trigger: "appfolio local dev".

jeremylongshore/tons-of-skills-marketplace

Production readiness checklist for AppFolio integrations. Trigger: "appfolio production checklist".

jeremylongshore/tons-of-skills-marketplace

Reference architecture for AppFolio property management integration. Trigger: "appfolio architecture".

jeremylongshore/tons-of-skills-marketplace

Apply production-ready patterns for AppFolio REST API integration. Trigger: "appfolio patterns".

相關技能