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

インポート後に部分的な失敗のエラーを調査する

このレシピでは、ワーカーの処理が完了した後に、非同期インポートの行ごとのエラーを調査する方法を紹介します。ステータスエンドポイントは読み取りのたびに短いサンプルを返します。同じエンドポイントのページ単位のエラー取得モードでは、すべてのエラーを行番号、エラーコード、エラーメッセージ、元の行のペイロードとともに順に取得できます。

partial / failed のステータスが返されたとき

1つの不正な行が原因でインポート全体が中止されることはありません。Waafirのワーカーは各行を個別に検証し、有効な行はすべて保存し、不正な行ごとに行単位のエラーレコードを書き込みます。その後、インポートは次の2つの終了ステータスのいずれかに落ち着きます。

  • partial:少なくとも1行が成功し、かつ 少なくとも1行が失敗しました。有効な行は登録されており、無効な行はこのレシピの方法で照会できます。
  • failed:成功した行が0件です。すべての行が無効だったか、インポートが致命的なエラー(不正な形式のNDJSON、ファイルの読み取り失敗、ワーカーの例外)に遭遇したかのどちらかです。後者の場合、errorSummary には致命的なエラーの形式のエラーが含まれます。

どちらの終了状態でも、詳しく調べるには以下のレシピが適しています。

エラー情報の形式

ステータスエンドポイント(GET /api/v1/monitoring/loan/imports/{id})は errorSummary フィールドを返します。その形式は、何が起きたかによって2種類あります。

  • 行単位のエラー(partial とほとんどの failed の実行で一般的なケース):errorSummary は { samples, totals } です。samples 配列には、最初の10件のエラーが { rowNumber, errorCode, errorMessage, rawRow } の形式で含まれます。totals フィールドには集計した件数が示されます。
  • 致命的なエラー(行を1つも処理する前に停止したインポート):errorSummary は { fatal } で、ワーカーレベルの失敗を説明する1件のエラーです。

最初の10件を超えるエラーを確認するには、ページ単位のエラー取得モード GET /api/v1/monitoring/loan/imports/{id}?errors=true&limit=&offset= を使って順に取得します。

レシピ

# 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

確認すべきこと

partial のインポートでは、rowCountSucceeded と rowCountFailed の合計が rowCountProcessed と等しく、rowCountSucceeded は0ではありません。failed のインポートでは rowCountSucceeded が0です。到達可能だったすべての行が検証に失敗したか、または errorSummary.fatal フィールドがワーカーレベルの失敗を説明しています。

rowNumber フィールドは、NDJSONファイル内の行番号(1始まり)です。これを元のデータの行に対応づけて問題のあるレコードを見つけて修正し、修正した行だけ、またはファイル全体を再送信します(新しい意図には新しい冪等キーを使用してください。リトライのレシピを参照)。

rawRow フィールドには、Waafirが受信したとおりの解析済みペイロードが含まれます(そのため、送信された形式がコードで生成したものと一致しているかを確認できます)。errorCode は、発動した検証ルールの安定した識別子です(そのため、エラーのグループを修正リストと照合できます)。