AppFolio デバッグバンドル
概要
このデバッグバンドルは、AppFolio 物件管理 API 統合に関する診断証拠を収集し、サポートエスカレーションや根本原因分析に使用します。プロパティ、テナント、作業依頼エンドポイントに対する API 接続状況、クライアント認証情報の認証ステータス、統合パイプラインからの最近のエラーログ、SDK バージョン情報をキャプチャします。結果の tarball により、サポートエンジニアはライブ環境にアクセスすることなく、接続障害、認証拒否、データ同期の問題を診断するために必要なすべての情報を得られます。
前提条件
curl、jq、tarがインストールされていることAPPFOLIO_CLIENT_IDとAPPFOLIO_CLIENT_SECRETが設定されていること(基本認証ペア)APPFOLIO_BASE_URLがスタック API ベース URL に設定されていること(例:https://yourcompany.appfolio.com/api/v1)
手順
- インシデントの承認を取得し、影響を受ける時間枠、ポートフォリオ、安全な読み取りプローブを定義します。利用可能だからといって、テナント、リース、支払い、または生のログ本文を収集しないでください。
- 設定状態、プロバイダーのステータス/レイテンシ、レート制限ヘッダー、パッケージバージョンのみを含むバンドルを作成します。認証情報を argv に含めないでください。
- 共有前にすべてのファイルを確認し、アーカイブを暗号化するか承認されたサポートチャネルを使用し、インシデントポリシーに従ってローカルコピーを削除します。
- 機密レコードが必要な場合は、この汎用デバッグバンドルを拡張するのではなく、個別に承認された最小限のエクスポートを取得して停止します。
デバッグ収集スクリプト
#!/bin/bash
set -euo pipefail
BUNDLE="debug-appfolio-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"
NETRC_FILE="$(mktemp)"
trap 'rm -f "$NETRC_FILE"' EXIT
chmod 600 "$NETRC_FILE"
APPFOLIO_HOST="${APPFOLIO_BASE_URL#https://}"
APPFOLIO_HOST="${APPFOLIO_HOST%%/*}"
printf 'machine %s login %s password %s\n' "$APPFOLIO_HOST" \
"$APPFOLIO_CLIENT_ID" "$APPFOLIO_CLIENT_SECRET" > "$NETRC_FILE"
probe() {
endpoint="$1"
curl -s -o /dev/null -w 'HTTP %{http_code} in %{time_total}s\n' \
--netrc-file "$NETRC_FILE" "${APPFOLIO_BASE_URL}/${endpoint}?per_page=1" \
|| printf 'UNREACHABLE\n'
}
# 環境確認
echo "=== 環境 ===" > "$BUNDLE/environment.txt"
echo "ベースURL: ${APPFOLIO_BASE_URL:-設定されていません}" >> "$BUNDLE/environment.txt"
echo "クライアントID: ${APPFOLIO_CLIENT_ID:+設定済み (秘匿化)}" >> "$BUNDLE/environment.txt"
echo "クライアントシークレット: ${APPFOLIO_CLIENT_SECRET:+設定済み (秘匿化)}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo '未インストール')" >> "$BUNDLE/environment.txt"
echo "タイムスタンプ: $(date -u)" >> "$BUNDLE/environment.txt"
# API 接続メタデータのみ — このバンドルに API ボディを書き込まないでください。
echo "=== API ヘルス ===" > "$BUNDLE/api-health.txt"
probe properties >> "$BUNDLE/api-health.txt"
# 作業依頼エンドポイントのプローブ
echo "=== 作業依頼 ===" > "$BUNDLE/work-orders.txt"
probe work_orders >> "$BUNDLE/work-orders.txt"
# テナントエンドポイントのプローブ
echo "=== テナント ===" > "$BUNDLE/tenants.txt"
probe tenants >> "$BUNDLE/tenants.txt"
# ログの目録のみ; 生ログにはテナントおよび財務データが含まれる可能性があります。
echo "=== ログ目録 ===" > "$BUNDLE/app-logs.txt"
find /var/log/appfolio-sync -maxdepth 1 -type f -printf '%f %s バイト\n' 2>/dev/null \
|| echo "同期ログが見つかりません" >> "$BUNDLE/app-logs.txt"
# レート制限ヘッダー
echo "=== レート制限 ===" > "$BUNDLE/rate-limits.txt"
curl -sI --netrc-file "$NETRC_FILE" \
"${APPFOLIO_BASE_URL}/properties?per_page=1" 2>/dev/null | grep -i "x-rate\|retry-after\|x-ratelimit" >> "$BUNDLE/rate-limits.txt" || echo "レート制限ヘッダーがありません" >> "$BUNDLE/rate-limits.txt"
# パッケージバージョン
echo "=== 依存関係 ===" > "$BUNDLE/deps.txt"
npm ls 2>/dev/null | grep -i appfolio >> "$BUNDLE/deps.txt" || echo "AppFolio npm パッケージが見つかりません" >> "$BUNDLE/deps.txt"
tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "バンドル: $BUNDLE.tar.gz"
バンドルの分析
tar -xzf debug-appfolio-*.tar.gz
cat debug-appfolio-*/environment.txt # 認証情報が設定されているか確認
cat debug-appfolio-*/api-health.txt # HTTP ステータスとレイテンシを確認
cat debug-appfolio-*/rate-limits.txt # スロットリングされていないか確認
jq '.errors' debug-appfolio-*/work-orders.txt 2>/dev/null # エラーペイロードを解析
よくある問題
| 症状 | バンドルでの確認箇所 | 修正方法 |
|---|---|---|
| すべてのエンドポイントで 401 | environment.txt にクライアントID/シークレットが設定されていない | 環境変数 APPFOLIO_CLIENT_ID と APPFOLIO_CLIENT_SECRET を設定する |
| テナントで 403 Forbidden | tenants.txt HTTP 403 | Stack API スコープが不足; AppFolio パートナーポータルでテナント読み取り権限をリクエストする |
| 429 Too Many Requests | rate-limits.txt に retry-after ヘッダーが表示される | バックオフして指数バックオフリトライを実装する; AppFolio は 120 req/min を許可 |
| 作業依頼でタイムアウト | api-health.txt に 30秒以上の時間が表示される | per_page パラメータを減らす; updated_since でフィルタリングして結果セットを絞る |
| 空のプロパティリスト | api-health.txt が [] を返す | APPFOLIO_BASE_URL が正しいポートフォリオを指しているか確認; プロパティグループフィルターを確認する |
| SSL 証明書エラー | api-health.txt に curl SSL エラーが表示される | CA バンドルを更新: sudo update-ca-certificates; プロキシ設定を確認する |
出力
- 確認可能で秘匿化された設定の存在確認、エンドポイントステータスとレイテンシ、レート制限ヘッダー、ログ目録、依存関係メタデータのバンドル
- テナント、支払い、または生のアプリケーションレコードではなく、インシデントの範囲と機密データの除外を指定するサポート引き継ぎレシート
- 必要な証拠を安全に収集できない場合のフェイルクローズ判断
エラーハンドリング
プローブの失敗は、より大きな応答をキャプチャしたり、認証情報制御をバイパスしたりする許可ではなく、プローブの失敗の証拠として扱います。401/403 の場合は、管理対象クライアントの設定を認証情報所有者と確認します。429 の場合は、レートヘッダーを保存し、それ以上のプローブを一時停止します。5xx またはタイムアウトの場合は、秘匿化されたタイミング/ステータスの証拠のみを収集し、プロバイダーのステータスページを確認します。サポートが特定のテナントや支払いレコードを必要とする場合は、独自の保持およびアクセス制御を備えた個別に承認された最小限のエクスポートを使用します。
使用例
本番環境の同期タイムアウトに対して、影響を受ける時間枠と1回のプロパティ安全読み取りプローブを含むバンドルを作成します。ステータス/レイテンシ、レートヘッダー、依存関係バージョン、ログファイルのメタデータが含まれていること、ただし応答ボディ、認証情報、テナント、財務データが含まれていないことを確認します。アーカイブを承認された暗号化サポートチャネルにアップロードする前に、アーカイブを確認します。確認で生のペイロードや秘密情報が見つかった場合は、アーカイブを削除し、必要に応じてローテーションし、エスカレーション前に最小限のバンドルを再生成します。
自動ヘルスチェック
async function checkAppFolioHealth(): Promise<{
status: string;
latencyMs: number;
endpoints: Record<string, number>;
}> {
const baseUrl = process.env.APPFOLIO_BASE_URL;
const creds = Buffer.from(
`${process.env.APPFOLIO_CLIENT_ID}:${process.env.APPFOLIO_CLIENT_SECRET}`
).toString("base64");
const headers = { Authorization: `Basic ${creds}` };
const endpoints = ["properties", "tenants", "work_orders"];
const results: Record<string, number> = {};
const start = Date.now();
for (const ep of endpoints) {
const res = await fetch(`${baseUrl}/${ep}?per_page=1`, { headers });
results[ep] = res.status;
}
return {
status: Object.values(results).every((s) => s === 200) ? "healthy" : "degraded",
latencyMs: Date.now() - start,
endpoints: results,
};
}
リソース
次のステップ
appfolio-rate-limits を参照してください。