AppFolio 升级与迁移 是做什么的?
概述
AppFolio 物业管理集成依赖于版本化的 REST API 端点,这些端点会随着平台的演进而变化。升级可能会重命名物业和租客对象上的字段、更改分页模型、弃用工单端点,以及改变基本身份验证流程。此技能可检测您当前的 API 版本,将弃用的响应形状映射到替代形状,并在新版本失败时自动回滚。
前提条件
- 文档中记录了当前 API 版本前缀(例如
/api/v1/) - 可以访问 AppFolio API 变更日志和发布说明
- 包含测试物业和租客数据的暂存环境
- 客户端 ID 和密钥存储在环境变量中
- 现有的集成测试套件覆盖了核心端点
操作说明
- 运行版本检测,将您当前的 API 版本与最新版本进行比较。
- 查看 AppFolio 变更日志,了解两个版本之间的破坏性变更。
- 对物业和租客响应对象应用模式迁移转换。
- 将端点 URL 从旧版本前缀更新为新版本前缀。
- 如果新版本要求,将分页从基于偏移切换为基于游标。
- 在暂存环境中运行冒烟测试套件,验证所有端点是否正常响应。
- 启用回滚策略后部署到生产环境。
- 监控错误日志中表示遗漏迁移步骤的 410/401 响应。
输出
成功迁移后,此技能会生成:
- 一个
VersionInfo对象,确认当前版本、最新版本和已弃用的版本 - 符合新模式的已转换物业和租客对象
- 针对物业、租客、工单和会计端点的冒烟测试结果
- 回滚日志条目(如果任何端点回退到了之前的版本)
版本检测
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(`版本 ${current} 已弃用。请迁移到 ${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} 被拒绝;回退到 ${fallbackVersion}`);
const fallback = await fetch(`${baseUrl}/api/${fallbackVersion}${path}`, { headers });
if (!fallback.ok) throw new Error(`回退失败:${fallback.status}`);
return fallback.json();
}
if (!res.ok) throw new Error(`请求失败:${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 更新为最新版本前缀 |
| 重命名的属性字段 | 属性同步中出现 undefined 值 | 应用 migrateProperty 转换 |
| 移除的分页偏移 | 第一页之后的结果集为空 | 切换到基于游标的分页 |
| 身份验证头部被拒 | 升级后收到 401 Unauthorized | 重新生成客户端密钥,更新环境变量 |
| Webhook 信封变更 | 事件处理程序解析错误 | 为新的信封更新负载解析器 |
资源
- AppFolio Stack APIs
- AppFolio Engineering Blog
- 有关迁移后的 CI 验证,请参阅
appfolio-ci-integration