Bundle de débogage AppFolio
Aperçu
Ce bundle de débogage collecte des preuves diagnostiques des intégrations API de gestion immobilière AppFolio pour l'escalade du support et l'analyse des causes racines. Il capture la connectivité API vers les endpoints propriétés, locataires et ordres de travail, l'état d'authentification utilisant les paires d'identifiants clients, les logs d'erreurs récents des pipelines d'intégration et les informations de version du SDK. L'archive résultante donne aux ingénieurs support tout ce dont ils ont besoin pour diagnostiquer les échecs de connectivité, les rejets d'authentification et les problèmes de synchronisation de données sans nécessiter un accès direct à votre environnement.
Prérequis
curl,jq,tarinstallésAPPFOLIO_CLIENT_IDetAPPFOLIO_CLIENT_SECRETconfigurés (paire d'authentification de base)APPFOLIO_BASE_URLdéfini sur la base de votre API Stack (ex.https://yourcompany.appfolio.com/api/v1)
Instructions
- Obtenez l'approbation de l'incident et définissez la fenêtre temporelle concernée, le portefeuille et les sondes de lecture sécurisées ; ne collectez pas les corps de locataires, baux, paiements ou logs bruts simplement parce qu'ils sont disponibles.
- Créez le bundle avec l'état de configuration masqué, le statut/la latence du fournisseur, les en-têtes de limite de débit et les versions des paquets uniquement ; gardez les identifiants hors de argv.
- Vérifiez chaque fichier avant de le partager, chiffrez ou utilisez le canal de support approuvé pour l'archive et supprimez la copie locale conformément à la politique de l'incident.
- Si les preuves nécessitent des enregistrements sensibles, arrêtez-vous et obtenez une exportation minimale approuvée séparément plutôt que d'étendre ce bundle de débogage à usage général.
Script de collecte de débogage
#!/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 'INJOIGNABLE\n'
}
# Vérification de l'environnement
echo "=== Environnement ===" > "$BUNDLE/environment.txt"
echo "URL de base : ${APPFOLIO_BASE_URL:-NON DÉFINIE}" >> "$BUNDLE/environment.txt"
echo "ID client : ${APPFOLIO_CLIENT_ID:+DÉFINI (masqué)}" >> "$BUNDLE/environment.txt"
echo "Secret client : ${APPFOLIO_CLIENT_SECRET:+DÉFINI (masqué)}" >> "$BUNDLE/environment.txt"
echo "Node : $(node -v 2>/dev/null || echo 'non installé')" >> "$BUNDLE/environment.txt"
echo "Horodatage : $(date -u)" >> "$BUNDLE/environment.txt"
# Métadonnées de connectivité API uniquement — ne jamais écrire les corps API dans ce bundle.
echo "=== Santé API ===" > "$BUNDLE/api-health.txt"
probe properties >> "$BUNDLE/api-health.txt"
# Sondage de l'endpoint des ordres de travail
echo "=== Ordres de travail ===" > "$BUNDLE/work-orders.txt"
probe work_orders >> "$BUNDLE/work-orders.txt"
# Sondage de l'endpoint des locataires
echo "=== Locataires ===" > "$BUNDLE/tenants.txt"
probe tenants >> "$BUNDLE/tenants.txt"
# Inventaire des logs uniquement ; les logs bruts peuvent contenir des données de locataires et financières.
echo "=== Inventaire des logs ===" > "$BUNDLE/app-logs.txt"
find /var/log/appfolio-sync -maxdepth 1 -type f -printf '%f %s bytes\n' 2>/dev/null \
|| echo "Aucun log de synchronisation trouvé" >> "$BUNDLE/app-logs.txt"
# En-têtes de limite de débit
echo "=== Limites de débit ===" > "$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 "Aucun en-tête de limite de débit" >> "$BUNDLE/rate-limits.txt"
# Versions des paquets
echo "=== Dépendances ===" > "$BUNDLE/deps.txt"
npm ls 2>/dev/null | grep -i appfolio >> "$BUNDLE/deps.txt" || echo "Aucun paquet npm AppFolio trouvé" >> "$BUNDLE/deps.txt"
tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle : $BUNDLE.tar.gz"
Analyse du bundle
tar -xzf debug-appfolio-*.tar.gz
cat debug-appfolio-*/environment.txt # Vérifiez que les identifiants sont définis
cat debug-appfolio-*/api-health.txt # Vérifiez le statut HTTP et la latence
cat debug-appfolio-*/rate-limits.txt # Confirmez que vous n'êtes pas limité
jq '.errors' debug-appfolio-*/work-orders.txt 2>/dev/null # Analysez les payloads d'erreur
Problèmes courants
| Symptôme | Vérifier dans le bundle | Correctif |
|---|---|---|
| 401 sur tous les endpoints | environment.txt montre ID/secret client NON DÉFINIS | Définissez les variables d'env APPFOLIO_CLIENT_ID et APPFOLIO_CLIENT_SECRET |
| 403 Interdit sur les locataires | tenants.txt HTTP 403 | Portée API Stack manquante ; demandez la permission de lecture des locataires dans le portail partenaire AppFolio |
| 429 Trop de requêtes | rate-limits.txt montre un en-tête retry-after | Reculez et implémentez une réexponentielle ; AppFolio autorise 120 req/min |
| Délai d'attente sur les ordres de travail | api-health.txt montre un temps > 30s | Réduisez le paramètre per_page ; filtrez par updated_since pour réduire l'ensemble de résultats |
| Liste de propriétés vide | api-health.txt renvoie [] | Vérifiez que APPFOLIO_BASE_URL pointe vers le bon portefeuille ; vérifiez les filtres de groupe de propriétés |
| Erreur de certificat SSL | api-health.txt montre une erreur curl SSL | Mettez à jour le bundle CA : sudo update-ca-certificates ; vérifiez les paramètres de proxy |
Sortie
- Un bundle vérifiable et masqué contenant la présence de configuration, le statut et la latence des endpoints, les en-têtes de limite de débit, l'inventaire des logs et les métadonnées des dépendances
- Un accusé de réception de transfert au support qui nomme la portée de l'incident et les exclusions de données sensibles plutôt que d'empaqueter les dossiers de locataires, de paiement ou les enregistrements d'application bruts
- Une décision de fermeture en cas d'échec lorsque les preuves requises ne peuvent pas être collectées en toute sécurité
Gestion des erreurs
Traitez un échec de sonde comme une preuve d'une sonde ayant échoué, pas une permission de capturer des réponses plus volumineuses ou de contourner les contrôles d'identifiants. Pour les erreurs 401/403, vérifiez la configuration du client géré avec le propriétaire des identifiants ; pour 429, conservez les en-têtes de débit et mettez en pause les autres sondes ; pour 5xx ou délai d'attente, collectez uniquement les preuves de temporisation/statut masquées et vérifiez la page de statut du fournisseur. Si le support a besoin d'un enregistrement de locataire ou de paiement spécifique, utilisez une exportation minimale approuvée séparément avec ses propres contrôles de rétention et d'accès.
Exemples
Pour un délai d'attente de synchronisation de production, créez un bundle couvrant la fenêtre temporelle concernée et une sonde de lecture sécurisée des propriétés. Confirmez qu'il contient le statut/la latence, les en-têtes de débit, les versions des dépendances et les métadonnées des fichiers de log — mais aucun corps de réponse, identifiant, donnée de locataire ou financière. Vérifiez l'archive avant de la télécharger sur le canal de support chiffré approuvé. Si la vérification trouve une charge utile brute ou un secret, supprimez l'archive, effectuez une rotation si nécessaire et régénérez un bundle minimisé avant l'escalade.
Vérification automatique de santé
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,
};
}
Ressources
Prochaines étapes
Voir appfolio-rate-limits.