AppFolio 升級與遷移
概述
AppFolio 物業管理整合依賴於會隨平台演進的版本化 REST API 端點。 升級可能會重新命名物件(property 和 tenant)上的欄位、 變更分頁模型、棄用工單端點,以及修改基本認證流程。 此技能會偵測您目前的 API 版本,將已棄用的回傳結構對應到替代方案, 並在新版本失敗時自動回滾。
先決條件
- 已記錄目前 API 版本前綴(例如
/api/v1/) - 可存取 AppFolio API 變更日誌與發行說明
- 具有測試用 property 和 tenant 資料的暫存環境
- 將 Client ID 和 secret 儲存在環境變數中
- 現有的涵蓋核心端點的整合測試套件
操作說明
- 執行版本偵測,將您使用的 API 版本與最新版本進行比較。
- 檢閱 AppFolio 變更日誌,找出兩個版本之間的破壞性變更。
- 對 property 和 tenant 回應物件套用結構遷移轉換。
- 將端點 URL 從舊版本前綴更新為新版本前綴。
- 如果新版本要求,將分頁從偏移量(offset)切換為游標(cursor)方式。
- 針對暫存環境執行煙霧測試套件,以驗證所有端點皆正常回應。
- 啟用回滾策略後,部署至正式環境。
- 監控錯誤日誌中代表遺漏遷移步驟的 410/401 回應。
輸出
成功遷移後,此技能會產生:
- 一個
VersionInfo物件,確認目前版本、最新版本和已棄用版本 - 符合新結構的轉換後 property 與 tenant 物件
- 針對 property、tenant、工單和會計端點的煙霧測試結果
- 若任何端點回退至前一版本時,產生的回滾日誌條目
版本偵測
interface VersionInfo { current: string; latest: string; deprecated: string[]; }
async function detectApiVersion(baseUrl: string, headers: Record<string, string>): Promise<VersionInfo> {
const res = await fetch(`${baseUrl}/api/status`, { headers });
const body = await res.json();
const current = res.headers.get("X-AppFolio-Api-Version") ?? body.api_version;
const deprecated: string[] = body.deprecated_versions ?? [];
if (deprecated.includes(current)) {
console.warn(`Version ${current} is deprecated. Migrate to ${body.latest_version}.`);
}
return { current, latest: body.latest_version, deprecated };
}
結構遷移
interface LegacyProperty { address_line1: string; unit_count: number; mgr_id: string; }
interface CurrentProperty { street_address: string; total_units: number; manager_id: string; }
function migrateProperty(old: LegacyProperty): CurrentProperty {
return { street_address: old.address_line1, total_units: old.unit_count, manager_id: old.mgr_id };
}
interface LegacyTenant { lease_end: string; balance_due: number; }
interface CurrentTenant { lease_expiry_date: string; outstanding_balance: number; }
function migrateTenant(old: LegacyTenant): CurrentTenant {
return { lease_expiry_date: old.lease_end, outstanding_balance: old.balance_due };
}
回滾策略
async function versionAwareRequest(
baseUrl: string, path: string, headers: Record<string, string>,
targetVersion: string, fallbackVersion: string
): Promise<any> {
const res = await fetch(`${baseUrl}/api/${targetVersion}${path}`, { headers });
if (res.status === 410 || res.status === 404) {
console.warn(`${targetVersion} rejected; falling back to ${fallbackVersion}`);
const fallback = await fetch(`${baseUrl}/api/${fallbackVersion}${path}`, { headers });
if (!fallback.ok) throw new Error(`Fallback failed: ${fallback.status}`);
return fallback.json();
}
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
return res.json();
}
範例
// 偵測版本並在需要時遷移
const info = await detectApiVersion("https://acme.appfolio.com", authHeaders);
if (info.deprecated.includes(info.current)) {
const oldProps = await fetchLegacyProperties();
const migrated = oldProps.map(migrateProperty);
await smokeTestEndpoints("https://acme.appfolio.com", authHeaders);
}
錯誤處理
| 遷移問題 | 症狀 | 修復方式 |
|---|---|---|
| 已棄用的版本前綴 | 每次請求都收到 410 Gone | 將基礎 URL 更新為最新版本前綴 |
| 已重新命名的 property 欄位 | property 同步中出現 undefined 值 | 套用 migrateProperty 轉換 |
| 已移除的分頁偏移量 | 第一頁之後的結果集為空 | 切換為游標式分頁 |
| 認證標頭被拒絕 | 升級後出現 401 Unauthorized | 重新產生客戶端金鑰,更新環境變數 |
| Webhook 信封變更 | 事件處理器解析錯誤 | 更新用於新信封的 payload 解析器 |
資源
- AppFolio Stack APIs
- AppFolio Engineering Blog
- 請參閱
appfolio-ci-integration以取得遷移後的 CI 驗證