AppFolio アップグレード&マイグレーション
概要
AppFolio 物件管理統合は、プラットフォームの進化に伴って変化するバージョン管理された REST API エンドポイントに依存しています。アップグレードにより、プロパティやテナントオブジェクトのフィールド名変更、ページネーションモデルの変更、ワークオーダーエンドポイントの非推奨化、基本認証フローの変更などが発生する可能性があります。このスキルは、現在の API バージョンを検出し、非推奨のレスポンス形状を新しいものにマッピングし、新しいバージョンで障害が発生した場合には自動的にロールバックします。
前提条件
- 現在の API バージョンプレフィックスが文書化されていること(例:
/api/v1/) - AppFolio API チェンジログおよびリリースノートへのアクセス
- テスト用のプロパティおよびテナントデータを含むステージング環境
- 環境変数に保存されたクライアント ID とシークレット
- コアエンドポイントをカバーする既存の統合テストスイート
手順
- バージョン検出を実行し、アクティブな API バージョンと最新バージョンを比較します。
- AppFolio チェンジログを確認し、2 つのバージョン間の破壊的変更を特定します。
- プロパティおよびテナントのレスポンスオブジェクトにスキーマ移行変換を適用します。
- エンドポイント 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(`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();
}
例
// Detect version and migrate if needed
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 変換を適用 |
| ページネーションオフセットの削除 | 2ページ目以降で空の結果セット | カーソルベースのページネーションに切り替え |
| 認証ヘッダーの拒否 | アップグレード後に 401 Unauthorized | クライアントシークレットを再生成し、環境変数を更新 |
| Webhook エンベロープの変更 | イベントハンドラーのパースエラー | 新しいエンベロープ用にペイロードパーサーを更新 |
リソース
- AppFolio Stack API
- AppFolio Engineering Blog
- 移行後の CI 検証については
appfolio-ci-integrationを参照