Waafir
Cette page est une traduction automatique en attente de relecture humaine. Elle peut contenir des erreurs.

Valider un chargement à blanc avant de valider les données

Cette recette montre comment utiliser l'endpoint d'import asynchrone comme validateur sans effet de bord avant de valider des données. Le flux est identique à celui de la recette d'import en masse — démarrer, téléverser, valider, interroger — avec un seul paramètre modifié : dryRun: true. Le worker exécute l'intégralité du pipeline de validation, compte les lignes validées dans le total des réussites et n'écrit jamais aucune ligne.

Quand l'utiliser

Le dry-run est l'outil adapté lorsque vous voulez savoir si un fichier que vous avez généré est correctement structuré avant de lui confier une soumission quotidienne. Usages typiques :

  • La première fois que vous branchez votre export de loan tape et que vous voulez confirmer que la structure JSON correspond aux attentes de Waafir.
  • Une exécution canari nocturne sur les 100 premières lignes d'un nouveau fichier avant de soumettre le reste.
  • Après un changement de schéma interne de votre côté, pour vérifier que le format transmis est toujours analysé correctement.

Le dry-run exécute les mêmes validateurs que le chemin d'ingestion réel : réussir un dry-run garantit donc fortement que le même fichier soumis pour de vrai sera enregistré avec succès. L'asymétrie : un dry-run ne sollicite pas les contraintes d'unicité de la base de données (puisqu'aucune ligne n'est écrite), si bien qu'une exécution réelle peut encore échouer sur des identifiants externes en double que le dry-run avait acceptés. Rapprochez par identifiant externe après l'exécution réelle si vous avez besoin de cette garantie.

La recette

# 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"],
})

Ce qu'il faut vérifier

L'objet de statut final porte dryRun: true, ce qui vous permet de confirmer que le worker s'est exécuté en mode dry-run. Les décomptes de lignes ont une signification particulière en dry-run :

  • rowCountSucceeded est le nombre de lignes ayant passé la validation — exactement le nombre qui aurait été enregistré comme lignes actives lors d'une exécution réelle.
  • rowCountFailed est le nombre de lignes ayant échoué à la validation. Parcourez-les avec la recette d'inspection des échecs partiels — l'endpoint d'erreurs paginées fonctionne de la même manière en dry-run.
  • rowCountProcessed est la somme : chaque ligne examinée par le worker.

Si votre fichier ne comporte aucune ligne en échec en dry-run, le même fichier soumis pour de vrai (sans dryRun: true) sera enregistré sans erreur, sous réserve de l'asymétrie liée à l'unicité en base de données mentionnée plus haut.