إعادة المحاولة بأمان باستخدام مفتاح عدم التكرار
توضّح هذه الوصفة كيفية إعادة محاولة استدعاء بدء الاستيراد بأمان بعد عطل في الشبكة أو خطأ ملتبس. تجعل ترويسة Idempotency-Key في POST /api/v1/monitoring/loan/imports الاستدعاء الثاني يُعيد معرّف الاستيراد نفسه الذي أعاده الأول، مع عنوان رفع مُصدَر حديثًا — ولا يُنشأ أي استيراد مكرّر.
متى تستخدم هذا
كلما لم تتمكن من معرفة ما إذا كان استدعاء بدء الاستيراد السابق قد وصل. والحالتان النموذجيتان:
- أطلق عميل HTTP لديك مهلة انتهاء قبل وصول الاستجابة. ربما وصل الطلب إلى Waafir وبدأ استيرادًا؛ وأنت لا تعرف.
- تلقّيت خطأ 5xx من واجهة غير متساوية الأثر وتريد إعادة المحاولة دون المخاطرة بعمل مكرّر.
الاصطلاح المعتمد على مستوى المنصة هو أن كل نقطة نهاية تُجري تعديلًا تقبل Idempotency-Key — نقطة نهاية بدء الاستيراد هنا، ونقطة نهاية التصدير، ونقاط نهاية تعديلات التدقيق في مواضع أخرى. استخدم مفتاحًا جديدًا لكل عملية منطقية؛ وأعد استخدامه عبر إعادات المحاولة للعملية نفسها. ومن الأنماط الشائعة معرّف UUID v4 يُولَّد مرة واحدة لكل نيّة "daily-import-batch" ويُحتفظ به في حالة المهمة لديك حتى ينجح الاستدعاء.
العقد
- الترويسة هي
Idempotency-Key: <your-string>. بحد أقصى 255 حرفًا. - يقبل محتوى الطلب أيضًا الحقل
idempotencyKey؛ وتكون الأولوية للترويسة عند وجود الاثنين. فضّل الترويسة — فهي الموضع المعتمد على مستوى المنصة. - يُعيد الاستدعاء المتكرر بالقيمة نفسها
(orgId, idempotencyKey):- قيمة
importIdنفسها، reused: trueفي الاستجابة،- عنوان رفع مُصدَرًا حديثًا (ينتهي العنوان الأصلي؛ والعنوان الجديد هو الآمن للاستخدام).
- قيمة
- يُرفض الاستدعاء المتكرر بمحتوى مختلف والمفتاح نفسه؛ إذ يرتبط المفتاح ببنية الطلب الأصلي.
الوصفة
# curl — start an import with an idempotency key, then retry safely
set -euo pipefail
PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
NDJSON_FILE="loans-2026-05-22.ndjson"
# Generate a fresh key per logical batch intent; keep it stable across retries.
IDEMPOTENCY_KEY="loan-import-2026-05-22-$(uuidgen)"
start_import() {
curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports" \
-H "Authorization: Bearer ${PAT}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
-d "$(cat <<JSON
{
"kind": "loan",
"filename": "${NDJSON_FILE}",
"sizeBytes": $(stat -c%s "${NDJSON_FILE}")
}
JSON
)"
}
# First call. If the network bombs out we have no idea whether the
# request landed — but the same key on the next attempt guarantees no
# duplicate import.
RESULT=$(start_import || true)
if [ -z "${RESULT}" ] || ! echo "${RESULT}" | jq -e .importId > /dev/null; then
echo "first call ambiguous; retrying with the same idempotency key…"
RESULT=$(start_import)
fi
echo "${RESULT}" | jq '{importId, reused, uploadUrl}'
# On a retry, reused == true; the importId matches the first call's; the
# uploadUrl is fresh.// TypeScript — retry start-import safely with an Idempotency-Key
import { randomUUID } from "node:crypto";
import { 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-2026-05-22.ndjson";
const idempotencyKey = `loan-import-2026-05-22-${randomUUID()}`;
async function startImport() {
return fetch(`${BASE_URL}/api/v1/monitoring/loan/imports`, {
method: "POST",
headers: {
Authorization: `Bearer ${PAT}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify({
kind: "loan",
filename: NDJSON_FILE,
sizeBytes: statSync(NDJSON_FILE).size,
}),
});
}
// Retry up to 3 times on transient failures; the same key makes this safe.
let lastError: unknown;
let result: { importId: string; reused: boolean; uploadUrl: string } | null = null;
for (let attempt = 1; attempt <= 3; attempt++) {
try {
const res = await startImport();
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
result = (await res.json()) as typeof result;
break;
} catch (err) {
lastError = err;
console.warn(`attempt ${attempt} failed; retrying with same idempotency key`, err);
await new Promise((r) => setTimeout(r, 1_000 * attempt));
}
}
if (!result) throw lastError;
console.log({ importId: result.importId, reused: result.reused, uploadUrl: result.uploadUrl });# python — retry start-import safely with an Idempotency-Key
import os
import uuid
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-2026-05-22.ndjson")
idempotency_key = f"loan-import-2026-05-22-{uuid.uuid4()}"
def start_import():
return requests.post(
f"{BASE_URL}/api/v1/monitoring/loan/imports",
headers={
"Authorization": f"Bearer {PAT}",
"Content-Type": "application/json",
"Idempotency-Key": idempotency_key,
},
json={
"kind": "loan",
"filename": NDJSON_FILE.name,
"sizeBytes": NDJSON_FILE.stat().st_size,
},
timeout=30,
)
# Retry up to 3 times on transient errors. The same key makes a second
# successful call a guaranteed replay of the first.
last_exc = None
result = None
for attempt in range(1, 4):
try:
response = start_import()
response.raise_for_status()
result = response.json()
break
except requests.RequestException as exc:
last_exc = exc
print(f"attempt {attempt} failed; retrying with same idempotency key: {exc}")
time.sleep(attempt)
if result is None:
raise RuntimeError("all retries exhausted") from last_exc
print({
"importId": result["importId"],
"reused": result["reused"],
"uploadUrl": result["uploadUrl"],
})ما يجب التحقق منه
في الاستدعاء الأول الناجح، تكون reused مساوية لـ false. وفي أي استدعاء لاحق بالمفتاح نفسه، تكون reused مساوية لـ true وتساوي importId قيمة الاستدعاء الأول. ويُعاد توليد uploadUrl في كل استدعاء، لذا فإن إعادة المحاولة بعد انتهاء صلاحية عنوان قديم آمنة — استخدم دائمًا العنوان من أحدث استجابة.
إذا أعدت المحاولة بمحتوى طلب مختلف والمفتاح نفسه، تُعيد الواجهة خطأً يشير إلى أن المفتاح مرتبط ببنية طلب متعارضة؛ فبدّل المفتاح للنيّة الجديدة.