تخطَّ إلى المحتوى

تقدم في الوقت الفعلي مع SSE

استلم تقدم مهام ترجمة الملفات (/jobs) في الوقت الفعلي عبر SSE (Server-Sent Events). عند عدم توفر SSE، يُرجع الاتصال 404؛ استعلم عن حالة المهمة بدلاً من ذلك.

لا يمكن لمتصفح EventSource إرسال رؤوس مخصصة، لذا تتطلب بيانات الاعتماد خطوتين:

  1. يقوم الخادم الخاص بك باستبدال مفتاح API بتذكرة (صالحة لمدة 30 ثانية، قابلة للاستخدام مرة واحدة)
  2. اتصل بـ SSE باستخدام التذكرة (يمكن أن يحدث ذلك في المتصفح؛ التذكرة ليست بيانات اعتماد طويلة الأمد)
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}
GET /api/v1/sse/jobs/{job_id}?ticket=...

احتفظ بمفتاح API على الخادم: يحصل الخادم على التذكرة ويمررها إلى المتصفح.

// Server (Node.js 18+): exchange the key for a ticket
async 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 server
const 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();
});
الحدثالوصف
job_updateتم تغيير الحالة أو المرحلة (يُرسل لقطة للحالة الحالية فور الاتصال)
job_doneانتهى العمل (completed أو failed); يمكنك إغلاق الاتصال
timeoutوصلت المدّة الزمنية للتدفق إلى الحد الأقصى؛ يُرجى إعادة الاتصال
errorمشكلة في جانب الخادم؛ احصل على تذكرة جديدة وأعد الاتصال لاحقًا

خادم stage_message باللغة الصينية:

event: job_update
data: {"status":"processing","stage":"translating","stage_progress":45,"stage_message":"正在翻译..."}
event: job_done
data: {"status":"completed","stage":"completed","stage_progress":100,"stage_message":""}

عند اكتمال المهمة، احصل على قائمة النتائج باستخدام GET /api/v1/artifacts?job_id=....

Terminal window
pip install requests sseclient-py
import json
import requests
import 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 connected
response = 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
  • التذكرة صالحة للاستخدام مرة واحدة؛ احصل على تذكرة جديدة قبل إعادة الاتصال
  • يمكن لكل حساب إبقاء ما يصل إلى 6 اتصالات SSE مفتوحة في الوقت نفسه وتبادل ما لا يزيد عن 30 تذكرة في الدقيقة؛ وإذا تجاوز ذلك، تكون الاستجابة 429، لذا انتظر Retry-After أو استخدم طلب الاستعلام بدلاً من ذلك.
  • عند عدم وجود أحداث وظيفية لفترة طويلة، يرسل الخادم حدث timeout؛ احصل على تذكرة جديدة وأعد الاتصال
  • أثناء بقاء الاتصال في حالة الخمول، يرسل الخادم تعليقات نبضية؛ ويجب على العميل تجاهل أسطر التعليقات.
  • إذا انقطع الاتصال، يعمل الاستعلام الدوري GET /jobs/{id} كخيار احتياطي.