Tovább a tartalomhoz

Valós idejű haladás a SSE segítségével

A fájlfordítási munkák (/jobs) előrehaladását valós időben a SSE (Server-Sent Events) segítségével kaphatja meg. Ha a SSE nem érhető el, a kapcsolat 404-ot ad vissza; ellenkező esetben kérdezze le a munka állapotát.

A böngésző EventSource nem képes egyéni fejlécet küldeni, ezért az hitelesítési adatok két lépést igényelnek:

  1. A szervere az API-kulcsot jegyre cseréli (30 másodpercig érvényes, egyszer használható)
  2. Csatlakozzon a SSE rendszerhez a jegy segítségével (ez a böngészőben is megtörténhet; a jegy nem hosszan érvényes hitelesítési adat).
POST /api/v1/sse/ticket/{job_id} → {"ticket": "..."}
GET /api/v1/sse/jobs/{job_id}?ticket=...

Tartsa meg az API-kulcsot a szerveren: a szerver lekéri a jegyet, majd átadja azt a böngészőnek.

// 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();
});
EseményLeírás
job_updateÁllapot vagy fázis megváltozott (a jelenlegi állapot pillanatképe a csatlakozás után azonnal elküldésre kerül)
job_doneA feladat befejeződött (completed vagy failed); a kapcsolatot lezárhatja.
timeoutA stream elérte maximális időtartamát; kapcsolódjon újra
errorSzerveroldali probléma; kérjen új jegyet, és próbáljon újra csatlakozni később

A szerver stage_message nyelvének kódja kínai:

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":""}

Amikor a feladat befejeződik, szerezze be az eredménylistát a GET /api/v1/artifacts?job_id=... segítségével.

Terminál
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
  • Az jegy egyszer használható; kapjon újat a csatlakozás előtt.
  • Minden fiók egyszerre legfeljebb 6 SSE kapcsolatot tarthat nyitva és percenként legfeljebb 30 jegyet cserélhet; ezen felül a válasz 429, ezért várjon Retry-After-et, vagy használjon lekérdezést helyette.
  • Ha hosszú ideig nincsenek munkafolyamat-események, a szerver küld egy timeout eseményt; szerezzen be új jegyet és kapcsolódjon újra.
  • Amíg az összeköttetés üres, a szerver szívverés-jelentéseket küld; a klienseknek figyelmen kívül kell hagyniuk a komment sorokat.
  • Ha a kapcsolat megszakad, az GET /jobs/{id} lekérdezés visszaváltásként működik.