AppFolio Debug Bundle
Übersicht
Dieses Debug-Bundle sammelt diagnostische Beweise aus AppFolio-Property-Management-API-Integrationen für Support-Eskalationen und Ursachenanalysen. Es erfasst die API-Konnektivität zu den Endpunkten für Immobilien, Mieter und Arbeitsaufträge, den Authentifizierungsstatus unter Verwendung von Client-Anmeldedaten, aktuelle Fehlerprotokolle aus Integrations-Pipelines sowie SDK-Versionsinformationen. Das resultierende Tarball gibt Support-Ingenieuren alles, was sie benötigen, um Konnektivitätsfehler, Authentifizierungsablehnungen und Datensynchronisationsprobleme zu diagnostizieren, ohne dass Live-Zugriff auf Ihre Umgebung erforderlich ist.
Voraussetzungen
curl,jq,tarinstalliertAPPFOLIO_CLIENT_IDundAPPFOLIO_CLIENT_SECRETkonfiguriert (Basis-Authentifizierungspaar)APPFOLIO_BASE_URLauf Ihre Stack-API-Basis gesetzt (z. B.https://ihre-firma.appfolio.com/api/v1)
Anleitung
- Holen Sie die Genehmigung für den Vorfall ein und definieren Sie das betroffene Zeitfenster, das Portfolio und die sicheren Lese-Sonden; sammeln Sie keine Mieter-, Mietvertrags-, Zahlungs- oder Rohprotokollinhalte, nur weil sie verfügbar sind.
- Erstellen Sie das Bundle mit redigiertem Konfigurationszustand, Provider-Status/Latenz, Ratenbegrenzungs-Headern und ausschließlich Paketversionen; halten Sie Anmeldedaten aus dem Befehlsaufruf heraus.
- Überprüfen Sie jede Datei vor dem Teilen, verschlüsseln Sie das Archiv oder verwenden Sie den genehmigten Support-Kanal und löschen Sie die lokale Kopie gemäß der Vorfallrichtlinie.
- Wenn Beweise sensible Daten erfordern, stoppen Sie und holen Sie einen separat genehmigten minimalen Export ein, anstatt dieses allgemeine Debug-Bundle zu erweitern.
Debug-Sammelskript
#!/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'
}
# Umgebungsprüfung
echo "=== Environment ===" > "$BUNDLE/environment.txt"
echo "Base URL: ${APPFOLIO_BASE_URL:-NOT SET}" >> "$BUNDLE/environment.txt"
echo "Client ID: ${APPFOLIO_CLIENT_ID:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Client Secret: ${APPFOLIO_CLIENT_SECRET:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo 'not installed')" >> "$BUNDLE/environment.txt"
echo "Timestamp: $(date -u)" >> "$BUNDLE/environment.txt"
# API-Konnektivitätsmetadaten nur – niemals API-Inhalte in dieses Bundle schreiben.
echo "=== API Health ===" > "$BUNDLE/api-health.txt"
probe properties >> "$BUNDLE/api-health.txt"
# Endpunkt für Arbeitsaufträge sondieren
echo "=== Work Orders ===" > "$BUNDLE/work-orders.txt"
probe work_orders >> "$BUNDLE/work-orders.txt"
# Endpunkt für Mieter sondieren
echo "=== Tenants ===" > "$BUNDLE/tenants.txt"
probe tenants >> "$BUNDLE/tenants.txt"
# Nur Protokollbestand; Rohprotokolle können Mieter- und Finanzdaten enthalten.
echo "=== Log Inventory ===" > "$BUNDLE/app-logs.txt"
find /var/log/appfolio-sync -maxdepth 1 -type f -printf '%f %s bytes\n' 2>/dev/null \
|| echo "No sync logs found" >> "$BUNDLE/app-logs.txt"
# Ratenbegrenzungs-Header
echo "=== Rate Limits ===" > "$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 "No rate limit headers" >> "$BUNDLE/rate-limits.txt"
# Paketversionen
echo "=== Dependencies ===" > "$BUNDLE/deps.txt"
npm ls 2>/dev/null | grep -i appfolio >> "$BUNDLE/deps.txt" || echo "No AppFolio npm packages found" >> "$BUNDLE/deps.txt"
tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"
Analyse des Bundles
tar -xzf debug-appfolio-*.tar.gz
cat debug-appfolio-*/environment.txt # Überprüfen, ob Anmeldedaten gesetzt sind
cat debug-appfolio-*/api-health.txt # HTTP-Status und Latenz prüfen
cat debug-appfolio-*/rate-limits.txt # Bestätigen, dass keine Drosselung vorliegt
jq '.errors' debug-appfolio-*/work-orders.txt 2>/dev/null # Fehlerantworten parsen
Häufige Probleme
| Symptom | Prüfen im Bundle | Behebung |
|---|---|---|
| 401 auf allen Endpunkten | environment.txt zeigt Client-ID/Geheimnis NICHT GESETZT | Setzen Sie APPFOLIO_CLIENT_ID und APPFOLIO_CLIENT_SECRET in der Umgebung |
| 403 Verboten bei Mietern | tenants.txt HTTP 403 | Stack-API-Bereich fehlt; fordern Sie Leseberechtigung für Mieter im AppFolio-Partnerportal an |
| 429 Zu viele Anfragen | rate-limits.txt zeigt Retry-After-Header | Zurückfahren und exponentielle Wiederholung implementieren; AppFolio erlaubt 120 Anfragen/min |
| Zeitüberschreitung bei Arbeitsaufträgen | api-health.txt zeigt Zeit > 30s | Reduzieren Sie den Parameter per_page; filtern Sie nach updated_since, um die Ergebnismenge einzugrenzen |
| Leere Immobilienliste | api-health.txt gibt [] zurück | Überprüfen Sie, ob APPFOLIO_BASE_URL auf das richtige Portfolio verweist; prüfen Sie Immobiliengruppenfilter |
| SSL-Zertifikatsfehler | api-health.txt zeigt curl-SSL-Fehler | Aktualisieren Sie das CA-Bundle: sudo update-ca-certificates; überprüfen Sie die Proxy-Einstellungen |
Ausgabe
- Ein überprüfbares, redigiertes Bundle aus Konfigurationsvorhandensein, Endpunktstatus und -latenz, Ratenbegrenzungs-Headern, Protokollbestand und Abhängigkeitsmetadaten
- Eine Support-Übergabequittung, die den Vorfallbereich und Ausschlüsse von sensiblen Daten benennt, anstatt Mieter-, Zahlungs- oder Rohprotokolldatensätze zu verpacken
- Eine Entscheidung zum Fail-Close, wenn die erforderlichen Beweise nicht sicher gesammelt werden können
Fehlerbehandlung
Behandeln Sie einen Sondenfehler als Beweis für eine fehlgeschlagene Sonde, nicht als Berechtigung, größere Antworten zu erfassen oder Anmeldekontrollen zu umgehen. Bei 401/403 überprüfen Sie die verwaltete Client-Konfiguration mit dem Anmeldedateninhaber; bei 429 bewahren Sie die Raten-Header und pausieren Sie weitere Sonden; bei 5xx oder Zeitüberschreitung sammeln Sie nur die redigierten Zeit-/Statusbeweise und überprüfen Sie die Statusseite des Providers. Wenn der Support einen bestimmten Mieter- oder Zahlungsdatensatz benötigt, verwenden Sie einen separat genehmigten minimalen Export mit eigenen Aufbewahrungs- und Zugriffskontrollen.
Beispiele
Erstellen Sie für eine Produktionssynchronisations-Zeitüberschreitung ein Bundle, das das betroffene Zeitfenster und eine sichere Lese-Sonde für Immobilien abdeckt. Bestätigen Sie, dass es Status/Latenz, Raten-Header, Abhängigkeitsversionen und Protokolldateimetadaten enthält – aber keine Antwortinhalte, Anmeldedaten, Mieter- oder Finanzdaten. Überprüfen Sie das Archiv, bevor Sie es auf den genehmigten verschlüsselten Support-Kanal hochladen. Wenn die Überprüfung einen Rohinhalt oder ein Geheimnis ergibt, löschen Sie das Archiv, rotieren Sie gegebenenfalls und generieren Sie ein minimiertes Bundle vor der Eskalation.
Automatisierter Gesundheitscheck
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,
};
}
Ressourcen
Nächste Schritte
Siehe appfolio-rate-limits.