Waafir
Эта страница переведена машинным способом и ожидает проверки человеком. Возможны неточности.

Разбор ошибок частичного сбоя после импорта

Этот рецепт показывает, как разобрать ошибки по строкам асинхронного импорта после того, как обработчик завершил работу. Эндпоинт статуса при каждом чтении возвращает небольшую выборку; режим постраничного просмотра ошибок того же эндпоинта выдаёт все ошибки с номером строки, кодом ошибки, сообщением об ошибке и исходными данными строки.

Когда приходит статус partial / failed

Одна некорректная строка никогда не прерывает импорт — обработчик Waafir проверяет каждую строку независимо, сохраняет каждую корректную и записывает запись об ошибке для каждой некорректной. Затем импорт переходит в один из двух конечных статусов:

  • partial — хотя бы одна строка обработана успешно и хотя бы одна строка завершилась ошибкой. Корректные строки записаны; некорректные можно запросить с помощью этого рецепта.
  • failed — ни одна строка не обработана успешно. Либо все строки были некорректными, либо импорт столкнулся с фатальной ошибкой (некорректный NDJSON, сбой чтения файла, исключение в обработчике); в этом случае errorSummary содержит ошибку фатального типа.

Для обоих конечных состояний рецепт ниже — подходящий инструмент для детального разбора.

Структура данных об ошибках

Эндпоинт статуса (GET /api/v1/monitoring/loan/imports/{id}) возвращает поле errorSummary, которое имеет одну из двух структур в зависимости от того, что произошло:

  • Ошибки на уровне строк (обычный случай для partial и большинства прогонов failed): errorSummary имеет вид { samples, totals }. Массив samples содержит первые десять ошибок в виде { rowNumber, errorCode, errorMessage, rawRow }. Поле totals содержит общее количество.
  • Фатальные ошибки (импорт, прервавшийся до обработки хотя бы одной строки): errorSummary имеет вид { fatal } — одна ошибка, описывающая сбой на уровне обработчика.

Чтобы получить больше первых десяти ошибок, используйте режим постраничного просмотра ошибок: 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 не равно нулю. Для импорта failed значение rowCountSucceeded равно нулю — либо каждая доступная строка не прошла проверку, либо поле errorSummary.fatal описывает сбой на уровне обработчика.

Поле rowNumber — номер строки в вашем файле NDJSON, отсчитываемый с единицы. Сопоставьте его с исходными строками, чтобы найти проблемные записи, исправьте их и отправьте повторно либо только исправленные строки, либо весь файл (для нового намерения используйте новый ключ идемпотентности — см. рецепт о повторах).

Поле rawRow содержит разобранные данные в том виде, в каком их получил Waafir (чтобы можно было убедиться, что передаваемая структура совпадает с тем, что сгенерировал ваш код); errorCode — стабильный идентификатор сработавшего правила проверки (чтобы можно было сопоставлять группы ошибок со списком исправлений).