توثيق واجهة Fileverity API
Idempotency
أرسل Idempotency-Key مع طلبات POST حتى لا تؤدي إعادة إرسال الطلب إلى تنفيذ الفحص أو احتساب رسمه مرتين. شرح السلوك والاستجابات المُعادة والتعارضات.
قد يتركك تعطّل الشبكة غير متأكد مما إذا كان طلب POST قد وصل. وإذا أعدت إرساله ببساطة، فقد يُنفَّذ الفحص ويُحتسب سعره مرتين. أرسل الترويسة Idempotency-Key فيعيد الطلب المُعاد الاستجابة الأولى بدلًا من تنفيذه من جديد.
استخدام الترويسة
curl https://api.fileverity.com/v1/analyses \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 0e5f6a64-52c2-4b36-9d0d-6f3d2f4c9a10" \ -d '{"model": "fvimg-2", "file": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB"}'async function createAnalysis(body) { const key = crypto.randomUUID(); let lastError; for (let attempt = 0; attempt < 3; attempt++) { try { return await fetch("https://api.fileverity.com/v1/analyses", { method: "POST", headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": key }, body: JSON.stringify(body), }); } catch (error) { lastError = error; } } throw lastError;}import uuid def create_analysis(body): key = str(uuid.uuid4()) last_error = None for attempt in range(3): try: return requests.post("https://api.fileverity.com/v1/analyses", headers={**headers, "Idempotency-Key": key}, json=body, timeout=90) except requests.ConnectionError as error: last_error = error raise last_error- أرسل أي سلسلة نصية فريدة طولها من 1 إلى 255 حرفًا. ويُعد معرّف UUID عشوائي خيارًا جيدًا. استخدم مفتاحًا جديدًا لكل طلب مختلف، ولا تعِد استخدام المفتاح نفسه إلا لإعادة محاولة الطلب نفسه.
- يعمل مع كل نقطة نهاية من نوع POST:
/text/detectionsو/filesو/analysesو/analyses/{id}/cancel. - يرتبط كل مفتاح بمساحة عملك وبالوضع (حقيقي أو اختبار) وبنقطة النهاية، ويُحفظ 24 ساعة. ولا يحدث تعارض إذا استُخدم المفتاح نفسه مع مفتاح حقيقي ومفتاح اختبار.
ما تحصل عليه
| الحالة | النتيجة |
|---|---|
| أول طلب بمفتاح معيّن | يُعالَج بصورة طبيعية. وتُحفظ الاستجابات الناجحة (رمز الحالة أقل من 400). |
| المفتاح نفسه ومحتوى الطلب نفسه خلال 24 ساعة | الاستجابة المحفوظة برمز الحالة نفسه، مع الترويسة idempotent-replayed: true. لا يُنفَّذ شيء ولا يُحتسب شيء مرة أخرى. |
| المفتاح نفسه مع محتوى طلب مختلف | 409 idempotency_mismatch. |
| المفتاح نفسه بينما لا يزال الطلب الأول قيد التنفيذ | 409 idempotency_in_progress. أعد المحاولة بعد قليل. |
| المفتاح نفسه بعد استجابة خطأ | يُحرَّر المفتاح. لا تُحفظ استجابة الخطأ، لذا تؤدي إعادة المحاولة إلى تنفيذ الطلب من جديد. |
تحمل الاستجابة المُعادة قيمة x-request-id الخاصة بالطلب الجديد، لا بالطلب الأصلي. وتُقارَن عمليات الرفع بصيغة multipart بحسب حقول النموذج ومحتوى الملف.
تمنع Idempotency تكرار العمل، لكنها لا تجعل الطلب الفاشل ينجح: بعد service_unavailable أو internal_error، انتظر عدد الثواني الوارد في retry-after إن كانت الاستجابة تحمل هذه الترويسة، ثم أعد المحاولة بالمفتاح نفسه.
راجع أيضًا الأخطاء وحدود المعدّل والترويسات.