跳转到内容

Πρόοδος σε πραγματικό χρόνο με το SSE

Λάβετε την πρόοδο των εργασιών μετάφρασης αρχείων (/jobs) σε πραγματικό χρόνο μέσω SSE (Server-Sent Events). Όταν το SSE δεν είναι διαθέσιμο, η σύνδεση επιστρέφει 404; ελέγξτε αντί γι’ αυτό την κατάσταση της εργασίας.

Ο EventSource του προγράμματος περιήγησης δεν μπορεί να στείλει προσαρμοσμένα κεφαλίδες, οπότε τα διαπιστευτήρια απαιτούν δύο βήματα:

  1. Ο διακομιστής σας ανταλλάσσει το API key με ένα ticket (ισχύει για 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 ή χρησιμοποιήστε poll αντί γι’ αυτό
  • Όταν δεν υπάρχουν εκδηλώσεις εργασίας για μεγάλο χρονικό διάστημα, ο διακομιστής στέλνει μια εκδήλωση timeout; λάβετε ένα νέο εισιτήριο και επανασυνδεθείτε
  • Όσο η σύνδεση είναι ανενεργή, ο διακομιστής στέλνει σχόλια καρδιοπάλμου· οι πελάτες θα πρέπει να αγνοούν τις γραμμές σχολίων.
  • Εάν η σύνδεση διακοπεί, η ανάκτηση GET /jobs/{id} λειτουργεί ως εφεδρική λύση