تقدم في الوقت الفعلي مع SSE
استلم تقدم مهام ترجمة الملفات (/jobs) في الوقت الفعلي عبر SSE (Server-Sent Events). عند عدم توفر SSE، يُرجع الاتصال 404؛ استعلم عن حالة المهمة بدلاً من ذلك.
تدفق الاتصال
Section titled “تدفق الاتصال”لا يمكن لمتصفح EventSource إرسال رؤوس مخصصة، لذا تتطلب بيانات الاعتماد خطوتين:
- يقوم الخادم الخاص بك باستبدال مفتاح API بتذكرة (صالحة لمدة 30 ثانية، قابلة للاستخدام مرة واحدة)
- اتصل بـ SSE باستخدام التذكرة (يمكن أن يحدث ذلك في المتصفح؛ التذكرة ليست بيانات اعتماد طويلة الأمد)
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}GET /api/v1/sse/jobs/{job_id}?ticket=...JavaScript مثال
Section titled “JavaScript مثال”احتفظ بمفتاح API على الخادم: يحصل الخادم على التذكرة ويمررها إلى المتصفح.
// Server (Node.js 18+): exchange the key for a ticketasync function createSseTicket(jobId) { const response = await fetch( `https://omnidoc.top/api/v1/sse/ticket/${jobId}`, { method: 'POST', headers: { 'X-API-Key': process.env.OMNIDOC_API_KEY } } ); if (!response.ok) throw new Error(`ticket failed: ${response.status}`); return (await response.json()).ticket;}// Browser: connect to SSE with the ticket from your serverconst source = new EventSource( `https://omnidoc.top/api/v1/sse/jobs/${jobId}?ticket=${encodeURIComponent(ticket)}`);
// The events are named, so use addEventListener (onmessage does not receive them)source.addEventListener('job_update', (event) => { const data = JSON.parse(event.data); console.log(`status: ${data.status}, stage: ${data.stage}, progress: ${data.stage_progress}%`);});
source.addEventListener('job_done', (event) => { const data = JSON.parse(event.data); console.log(`finished: ${data.status}`); source.close();});أنواع الأحداث
Section titled “أنواع الأحداث”| الحدث | الوصف |
|---|---|
job_update | تم تغيير الحالة أو المرحلة (يُرسل لقطة للحالة الحالية فور الاتصال) |
job_done | انتهى العمل (completed أو failed); يمكنك إغلاق الاتصال |
timeout | وصلت المدّة الزمنية للتدفق إلى الحد الأقصى؛ يُرجى إعادة الاتصال |
error | مشكلة في جانب الخادم؛ احصل على تذكرة جديدة وأعد الاتصال لاحقًا |
بيانات الحدث
Section titled “بيانات الحدث”خادم stage_message باللغة الصينية:
event: job_updatedata: {"status":"processing","stage":"translating","stage_progress":45,"stage_message":"正在翻译..."}
event: job_donedata: {"status":"completed","stage":"completed","stage_progress":100,"stage_message":""}عند اكتمال المهمة، احصل على قائمة النتائج باستخدام GET /api/v1/artifacts?job_id=....
Python مثال
Section titled “Python مثال”pip install requests sseclient-pyimport json
import requestsimport sseclient # sseclient-py
BASE = "https://omnidoc.top/api/v1"HEADERS = {"X-API-Key": "sk_your_key"}job_id = "q3f8s6c2a9m1k4tx"
ticket_response = requests.post( f"{BASE}/sse/ticket/{job_id}", headers=HEADERS, timeout=20)ticket_response.raise_for_status()ticket = ticket_response.json()["ticket"]
# Read timeout longer than the 15-second heartbeat; no API key while connectedresponse = requests.get( f"{BASE}/sse/jobs/{job_id}", params={"ticket": ticket}, stream=True, timeout=(10, 60),)response.raise_for_status()client = sseclient.SSEClient(response)
for event in client.events(): data = json.loads(event.data) print(f"[{event.event}] {data.get('stage')} {data.get('stage_progress', 0)}%") if event.event in {"job_done", "timeout", "error"}: break # timeout / error: get a new ticket and reconnect, or poll insteadملاحظات
Section titled “ملاحظات”- التذكرة صالحة للاستخدام مرة واحدة؛ احصل على تذكرة جديدة قبل إعادة الاتصال
- يمكن لكل حساب إبقاء ما يصل إلى 6 اتصالات SSE مفتوحة في الوقت نفسه وتبادل ما لا يزيد عن 30 تذكرة في الدقيقة؛ وإذا تجاوز ذلك، تكون الاستجابة
429، لذا انتظرRetry-Afterأو استخدم طلب الاستعلام بدلاً من ذلك. - عند عدم وجود أحداث وظيفية لفترة طويلة، يرسل الخادم حدث
timeout؛ احصل على تذكرة جديدة وأعد الاتصال - أثناء بقاء الاتصال في حالة الخمول، يرسل الخادم تعليقات نبضية؛ ويجب على العميل تجاهل أسطر التعليقات.
- إذا انقطع الاتصال، يعمل الاستعلام الدوري
GET /jobs/{id}كخيار احتياطي.