Einen Import vor dem Übernehmen der Daten per Probelauf validieren
Dieses Rezept zeigt, wie Sie den Endpunkt für asynchrone Importe als nebenwirkungsfreien Validator verwenden, bevor Sie Daten übernehmen. Der Ablauf ist identisch mit dem Rezept zum Massenimport – starten, hochladen, committen, abfragen – mit einem umgestellten Parameter: dryRun: true. Der Worker durchläuft die vollständige Validierungspipeline, zählt validierte Zeilen zur Erfolgssumme und schreibt nie eine Zeile.
Wann Sie dies verwenden
Der Probelauf ist das richtige Werkzeug, wenn Sie wissen möchten, ob eine von Ihnen erzeugte Datei korrekt aufgebaut ist, bevor Sie ihr eine tägliche Übermittlung anvertrauen. Typische Einsatzfälle sind:
- Das erste Mal, wenn Sie Ihren Loan-Tape-Export anbinden und bestätigen möchten, dass die JSON-Struktur den Erwartungen von Waafir entspricht.
- Ein nächtlicher Canary-Lauf mit den ersten 100 Zeilen einer neuen Datei, bevor Sie den Rest übermitteln.
- Nach einer internen Schemaänderung auf Ihrer Seite, um zu prüfen, ob die übertragene Struktur weiterhin fehlerfrei geparst wird.
Der Probelauf führt dieselben Validatoren aus wie der echte Erfassungsweg, sodass ein bestandener Probelauf eine starke Garantie dafür ist, dass dieselbe Datei bei einer echten Übermittlung erfolgreich ankommt. Die Asymmetrie: Ein Probelauf prüft keine Eindeutigkeitsbedingungen der Datenbank (da keine Zeilen geschrieben werden), sodass ein echter Lauf dennoch an doppelten externen IDs scheitern kann, die der Probelauf akzeptiert hat. Gleichen Sie nach dem echten Lauf anhand der externen ID ab, wenn Sie diese Garantie benötigen.
Das Rezept
# curl — dry-run validation
set -euo pipefail
PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
NDJSON_FILE="loans-canary.ndjson"
# Step 1 — start an import with dryRun=true. The query parameter and
# the body field are both accepted; the query is the curl-friendly form.
START=$(curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports?dryRun=true" \
-H "Authorization: Bearer ${PAT}" \
-H "Content-Type: application/json" \
-d "$(cat <<JSON
{
"kind": "loan",
"filename": "${NDJSON_FILE}",
"sizeBytes": $(stat -c%s "${NDJSON_FILE}")
}
JSON
)")
IMPORT_ID=$(echo "$START" | jq -r .importId)
UPLOAD_URL=$(echo "$START" | jq -r .uploadUrl)
# Step 2 — upload the file, applying the signed-in headers the start
# response returned (same shape as a real import — see the
# async-import recipe for the full rationale).
HEADER_ARGS=$(echo "$START" | jq -r '.headers | to_entries[] | "-H \"\(.key): \(.value)\""')
eval curl -fsS -X PUT --data-binary @"\"${NDJSON_FILE}\"" $HEADER_ARGS "\"${UPLOAD_URL}\""
# Step 3 — commit; the worker enqueues but the row processor short-circuits.
curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}/commit" \
-H "Authorization: Bearer ${PAT}"
# Step 4 — poll. Terminal status + dryRun:true means the file is structurally valid.
while :; do
BODY=$(curl -fsS "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}" \
-H "Authorization: Bearer ${PAT}")
STATUS=$(echo "$BODY" | jq -r .status)
echo "dry-run ${IMPORT_ID}: ${STATUS}"
case "${STATUS}" in
succeeded|partial|failed|cancelled) break ;;
esac
sleep 5
done
# At terminal, inspect the row counts. `dryRun: true` should be present.
echo "$BODY" | jq '{status, dryRun, rowCountProcessed, rowCountSucceeded, rowCountFailed}'// TypeScript — dry-run validation
import { readFileSync, statSync } from "node:fs";
const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const NDJSON_FILE = "loans-canary.ndjson";
const auth = { Authorization: `Bearer ${PAT}` };
// Step 1 — start with dryRun=true via the body. (?dryRun=true is also accepted.)
const startRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports`, {
method: "POST",
headers: { ...auth, "Content-Type": "application/json" },
body: JSON.stringify({
kind: "loan",
filename: NDJSON_FILE,
sizeBytes: statSync(NDJSON_FILE).size,
dryRun: true,
}),
});
if (!startRes.ok) throw new Error(`start failed: ${startRes.status} ${await startRes.text()}`);
const { importId, uploadUrl, headers: uploadHeaders } = (await startRes.json()) as {
importId: string;
uploadUrl: string;
headers: Record<string, string>;
};
// Step 2 — upload, applying the signed-in headers.
const putRes = await fetch(uploadUrl, {
method: "PUT",
headers: uploadHeaders,
body: readFileSync(NDJSON_FILE),
});
if (!putRes.ok) throw new Error(`upload failed: ${putRes.status}`);
// Step 3 — commit.
const commitRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}/commit`, {
method: "POST",
headers: auth,
});
if (!commitRes.ok) throw new Error(`commit failed: ${commitRes.status} ${await commitRes.text()}`);
// Step 4 — poll until terminal.
const TERMINAL = new Set(["succeeded", "partial", "failed", "cancelled"]);
let final: { status: string; dryRun: boolean; rowCountProcessed: number; rowCountSucceeded: number; rowCountFailed: number };
while (true) {
const statusRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}`, { headers: auth });
final = (await statusRes.json()) as typeof final;
console.log(`dry-run ${importId}: ${final.status}`);
if (TERMINAL.has(final.status)) break;
await new Promise((r) => setTimeout(r, 5_000));
}
console.log({
status: final.status,
dryRun: final.dryRun,
rowCountProcessed: final.rowCountProcessed,
rowCountSucceeded: final.rowCountSucceeded,
rowCountFailed: final.rowCountFailed,
});# python — dry-run validation
import os
import time
import requests
from pathlib import Path
PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
NDJSON_FILE = Path("loans-canary.ndjson")
auth = {"Authorization": f"Bearer {PAT}"}
# Step 1 — start with dryRun=True. The body field is the structured form;
# `?dryRun=true` on the query string is equivalent for curl ergonomics.
start = requests.post(
f"{BASE_URL}/api/v1/monitoring/loan/imports",
headers={**auth, "Content-Type": "application/json"},
json={
"kind": "loan",
"filename": NDJSON_FILE.name,
"sizeBytes": NDJSON_FILE.stat().st_size,
"dryRun": True,
},
timeout=30,
)
start.raise_for_status()
payload = start.json()
import_id = payload["importId"]
upload_url = payload["uploadUrl"]
upload_headers = payload["headers"]
# Step 2 — upload, applying the signed-in headers.
with NDJSON_FILE.open("rb") as fh:
requests.put(upload_url, data=fh, headers=upload_headers, timeout=300).raise_for_status()
# Step 3 — commit.
requests.post(
f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}/commit",
headers=auth,
timeout=30,
).raise_for_status()
# Step 4 — poll until terminal.
terminal = {"succeeded", "partial", "failed", "cancelled"}
while True:
body = requests.get(
f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}",
headers=auth,
timeout=30,
).json()
print(f"dry-run {import_id}: {body['status']}")
if body["status"] in terminal:
break
time.sleep(5)
print({
"status": body["status"],
"dryRun": body["dryRun"],
"rowCountProcessed": body["rowCountProcessed"],
"rowCountSucceeded": body["rowCountSucceeded"],
"rowCountFailed": body["rowCountFailed"],
})Was Sie überprüfen sollten
Das Statusobjekt im Endzustand enthält dryRun: true, sodass Sie bestätigen können, dass der Worker im Probelaufmodus lief. Die Zeilenzählungen haben im Probelauf eine bestimmte Bedeutung:
rowCountSucceededist die Anzahl der Zeilen, die die Validierung bestanden haben – genau die Anzahl, die bei einem echten Lauf als aktive Zeilen angekommen wäre.rowCountFailedist die Anzahl der Zeilen, die bei der Validierung durchgefallen sind. Gehen Sie diese mit dem Rezept zur Untersuchung von Teilfehlern durch – der Endpunkt für seitenweise abgerufene Fehler funktioniert im Probelauf identisch.rowCountProcessedist die Summe: jede Zeile, die der Worker berücksichtigt hat.
Wenn Ihre Datei im Probelauf keine fehlgeschlagenen Zeilen hat, kommt dieselbe Datei bei einer echten Übermittlung (ohne dryRun: true) fehlerfrei an, abgesehen von der oben beschriebenen Asymmetrie bei der Eindeutigkeit in der Datenbank.