Waafir
Diese Seite ist eine maschinelle Übersetzung, die noch auf eine menschliche Prüfung wartet. Sie kann Fehler enthalten.

Teilfehler nach einem Import untersuchen

Dieses Rezept zeigt, wie Sie die zeilenbezogenen Fehler eines asynchronen Imports untersuchen, nachdem der Worker fertig ist. Der Status-Endpunkt liefert bei jedem Abruf eine kurze Stichprobe; der Modus für seitenweise abgerufene Fehler desselben Endpunkts liefert jeden Fehler mit Zeilennummer, Fehlercode, Fehlermeldung und dem unverarbeiteten Payload der Zeile.

Wenn der Status partial / failed eintrifft

Eine einzelne fehlerhafte Zeile bricht einen Import nie ab – der Worker von Waafir validiert jede Zeile unabhängig, speichert jede gültige und schreibt für jede fehlerhafte einen zeilenbezogenen Fehlerdatensatz. Der Import endet dann in einem von zwei Endzuständen:

  • partial – mindestens eine Zeile war erfolgreich und mindestens eine Zeile ist fehlgeschlagen. Die gültigen Zeilen sind angekommen; die ungültigen lassen sich mit diesem Rezept abfragen.
  • failed – keine Zeile war erfolgreich. Entweder war jede Zeile ungültig, oder der Import ist auf einen schwerwiegenden Fehler gestoßen (fehlerhaftes NDJSON, ein Fehler beim Lesen der Datei, eine Worker-Ausnahme); in diesem Fall enthält errorSummary einen Fehler in der Form für schwerwiegende Fehler.

Für beide Endzustände ist das folgende Rezept das richtige Werkzeug, um ins Detail zu gehen.

Der Aufbau der Fehlerinformationen

Der Status-Endpunkt (GET /api/v1/monitoring/loan/imports/{id}) gibt ein Feld errorSummary zurück, das je nach Ereignis eine von zwei Formen hat:

  • Zeilenfehler (der übliche Fall bei partial und den meisten failed-Läufen): errorSummary ist { samples, totals }. Das Array samples enthält die ersten zehn Fehler als { rowNumber, errorCode, errorMessage, rawRow }. Das Feld totals liefert eine Gesamtzahl.
  • Schwerwiegende Fehler (ein Import, der abgebrochen ist, bevor eine Zeile verarbeitet wurde): errorSummary ist { fatal } – ein einzelner Fehler, der den Fehler auf Worker-Ebene beschreibt.

Für mehr als die ersten zehn Fehler verwenden Sie den Modus für seitenweise abgerufene Fehler: GET /api/v1/monitoring/loan/imports/{id}?errors=true&limit=&offset=.

Das Rezept

# curl — inspect a partial / failed import's errors
set -euo pipefail

PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
IMPORT_ID="${1:?supply the import id}"

# Step 1 — fetch the terminal status, see the error summary.
STATUS=$(curl -fsS "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}" \
  -H "Authorization: Bearer ${PAT}")

echo "status:" && echo "$STATUS" | jq '{status, rowCountProcessed, rowCountSucceeded, rowCountFailed}'
echo "first ten errors (sampled):"
echo "$STATUS" | jq '.errorSummary'

# Step 2 — page through every row error. Limit/offset are bounded
# (limit max 100; default 20).
LIMIT=100
OFFSET=0
TOTAL_FAILED=$(echo "$STATUS" | jq -r .rowCountFailed)

while [ "${OFFSET}" -lt "${TOTAL_FAILED}" ]; do
  PAGE=$(curl -fsS \
    "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}?errors=true&limit=${LIMIT}&offset=${OFFSET}" \
    -H "Authorization: Bearer ${PAT}")
  echo "$PAGE" | jq -c '.items[] | {rowNumber, errorCode, errorMessage}'
  OFFSET=$((OFFSET + LIMIT))
done
// TypeScript — inspect a partial / failed import's errors
const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const importId = process.argv[2];
if (!importId) throw new Error("usage: ts-node inspect.ts <importId>");

const auth = { Authorization: `Bearer ${PAT}` };

// Step 1 — terminal status + error summary.
const statusRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}`, {
    headers: auth,
});
type Status = {
    status: string;
    rowCountProcessed: number;
    rowCountSucceeded: number;
    rowCountFailed: number;
    errorSummary: unknown;
};
const status = (await statusRes.json()) as Status;
console.log("status:", {
    status: status.status,
    rowCountProcessed: status.rowCountProcessed,
    rowCountSucceeded: status.rowCountSucceeded,
    rowCountFailed: status.rowCountFailed,
});
console.log("error summary (first ten):", status.errorSummary);

// Step 2 — page through every row error.
type RowError = {
    rowNumber: number;
    errorCode: string;
    errorMessage: string;
    rawRow: unknown;
    createdAt: string;
};
const limit = 100;
for (let offset = 0; offset < status.rowCountFailed; offset += limit) {
    const url = `${BASE_URL}/api/v1/monitoring/loan/imports/${importId}?errors=true&limit=${limit}&offset=${offset}`;
    const pageRes = await fetch(url, { headers: auth });
    const page = (await pageRes.json()) as { items: RowError[]; limit: number; offset: number };
    for (const error of page.items) {
        console.log({
            rowNumber: error.rowNumber,
            errorCode: error.errorCode,
            errorMessage: error.errorMessage,
        });
    }
}
# python — inspect a partial / failed import's errors
import os
import sys
import requests

PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
import_id = sys.argv[1] if len(sys.argv) > 1 else None
if not import_id:
    raise SystemExit("usage: python inspect.py <importId>")

auth = {"Authorization": f"Bearer {PAT}"}

# Step 1 — terminal status + error summary.
status = requests.get(
    f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}",
    headers=auth,
    timeout=30,
).json()
print("status:", {
    "status": status["status"],
    "rowCountProcessed": status["rowCountProcessed"],
    "rowCountSucceeded": status["rowCountSucceeded"],
    "rowCountFailed": status["rowCountFailed"],
})
print("error summary (first ten):", status.get("errorSummary"))

# Step 2 — page through every row error.
LIMIT = 100
offset = 0
total_failed = status["rowCountFailed"]
while offset < total_failed:
    page = requests.get(
        f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}",
        params={"errors": "true", "limit": LIMIT, "offset": offset},
        headers=auth,
        timeout=30,
    ).json()
    for error in page["items"]:
        print({
            "rowNumber": error["rowNumber"],
            "errorCode": error["errorCode"],
            "errorMessage": error["errorMessage"],
        })
    offset += LIMIT

Was Sie überprüfen sollten

Bei einem partial-Import ergibt die Summe aus rowCountSucceeded und rowCountFailed den Wert rowCountProcessed, und rowCountSucceeded ist ungleich null. Bei einem failed-Import ist rowCountSucceeded gleich null – jede erreichbare Zeile ist bei der Validierung durchgefallen, oder das Feld errorSummary.fatal beschreibt einen Fehler auf Worker-Ebene.

Das Feld rowNumber ist die bei eins beginnende Zeilennummer in Ihrer NDJSON-Datei. Ordnen Sie sie Ihren Quellzeilen zu, um die fehlerhaften Datensätze zu finden, korrigieren Sie diese und übermitteln Sie entweder nur die korrigierten Zeilen oder die gesamte Datei erneut (verwenden Sie für das neue Vorhaben einen neuen Idempotenzschlüssel – siehe das Rezept zu Wiederholungen).

Das Feld rawRow enthält den geparsten Payload so, wie Waafir ihn empfangen hat (damit Sie prüfen können, ob die übertragene Struktur dem entspricht, was Ihr Code erzeugt hat); errorCode ist eine stabile Kennung für die ausgelöste Validierungsregel (damit Sie Gruppen von Fehlern mit einer Korrekturliste abgleichen können).