Waafir
このページは機械翻訳であり、人による確認を待っています。誤りが含まれている可能性があります。

データをコミットする前にドライランで読み込みを検証する

このレシピでは、データをコミットする前に、非同期インポートエンドポイントを副作用のないバリデーターとして使う方法を紹介します。フローは一括インポートのレシピと同じ(開始、アップロード、コミット、ポーリング)で、dryRun: true というパラメータを1つ切り替えるだけです。ワーカーは検証パイプライン全体を実行し、検証を通過した行を成功件数に加算しますが、行を書き込むことはありません。

これを使う場面

ドライランは、生成したファイルを日次の送信に使う前に、その形式が正しいかどうかを確認したい場合に適したツールです。典型的な用途は次のとおりです。

  • ローンテープのエクスポートを初めて接続するときに、JSONの形式がWaafirの想定と一致していることを確認する。
  • 新しいファイルの残りを送信する前に、最初の100行で毎晩カナリア実行を行う。
  • 自社側で内部のスキーマを変更した後に、送信する形式が引き続き問題なく解析されることを確認する。

ドライランは実際の取り込み経路と同じバリデーターを実行するため、ドライランを通過すれば、同じファイルを本番として送信したときに正常に登録されることが強く保証されます。ただし非対称な点があります。ドライランでは行が書き込まれないため、データベースの一意性制約は検証されません。そのため、ドライランで受け入れられた重複する外部IDによって、本番の実行が失敗する可能性はあります。その保証が必要な場合は、本番の実行後に外部IDで照合してください。

レシピ

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

確認すべきこと

終了時のステータスオブジェクトには dryRun: true が含まれるため、ワーカーがドライランモードで実行されたことを確認できます。ドライランでは、行数は次の特定の意味を持ちます。

  • rowCountSucceeded は、検証を通過した行の数です。本番の実行であれば有効な行として登録されていたはずの数と正確に一致します。
  • rowCountFailed は、検証に失敗した行の数です。これらは部分的な失敗を調査するレシピで確認できます。ページ単位のエラー取得エンドポイントは、ドライランでもまったく同じように動作します。
  • rowCountProcessed はその合計で、ワーカーが処理対象としたすべての行の数です。

ドライランで失敗した行が0件であれば、同じファイルを本番として(dryRun: true なしで)送信すると、上記のデータベースの一意性に関する非対称性を除き、問題なく登録されます。