Waafir
이 페이지는 사람의 검토를 기다리는 기계 번역입니다. 오류가 있을 수 있습니다.

가져오기 후 부분 실패 오류 검사하기

이 레시피는 워커가 작업을 마친 후 비동기 가져오기의 행별 오류를 검사하는 방법을 보여 줍니다. 상태 엔드포인트는 조회할 때마다 짧은 샘플을 표시하며, 같은 엔드포인트의 페이지 단위 오류 모드는 행 번호, 오류 코드, 오류 메시지, 원시 행 페이로드와 함께 모든 오류를 스트리밍합니다.

partial / failed 상태를 받았을 때

잘못된 행 하나 때문에 가져오기가 중단되는 일은 없습니다. Waafir의 워커는 각 행을 독립적으로 검증하여 유효한 행은 모두 저장하고, 잘못된 행마다 행별 오류 레코드를 기록합니다. 그런 다음 가져오기는 두 가지 최종 상태 중 하나로 확정됩니다.

  • partial — 하나 이상의 행이 성공했고, 동시에 하나 이상의 행이 실패했습니다. 유효한 행은 반영되었고, 유효하지 않은 행은 이 레시피로 조회할 수 있습니다.
  • failed — 성공한 행이 0개입니다. 모든 행이 유효하지 않았거나, 가져오기에 치명적 오류(잘못된 형식의 NDJSON, 파일 읽기 실패, 워커 예외)가 발생한 경우입니다. 후자의 경우 errorSummary에 치명적 형태의 오류가 담깁니다.

두 최종 상태 모두에서 아래 레시피가 자세히 살펴보기에 적합한 도구입니다.

오류 정보의 구조

상태 엔드포인트(GET /api/v1/monitoring/loan/imports/{id})는 무슨 일이 일어났는지에 따라 두 가지 형태 중 하나로 errorSummary 필드를 반환합니다.

  • 행 수준 오류(partial 및 대부분의 failed 실행에서 흔한 경우): errorSummary는 { samples, totals }입니다. samples 배열에는 처음 10개의 오류가 { rowNumber, errorCode, errorMessage, rawRow } 형태로 담깁니다. totals 필드는 전체 건수를 보여 줍니다.
  • 치명적 오류(어떤 행도 처리하기 전에 중단된 가져오기): errorSummary는 { fatal }이며, 워커 수준의 실패를 설명하는 단일 오류입니다.

처음 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는 발생한 검증 규칙의 안정적인 식별자이므로, 오류 그룹을 수정 목록과 대조할 수 있습니다.