Πρόοδος σε πραγματικό χρόνο με το SSE
Λάβετε την πρόοδο των εργασιών μετάφρασης αρχείων (/jobs) σε πραγματικό χρόνο μέσω SSE (Server-Sent Events). Όταν το SSE δεν είναι διαθέσιμο, η σύνδεση επιστρέφει 404; ελέγξτε αντί γι’ αυτό την κατάσταση της εργασίας.
Ροή σύνδεσης
Section titled “Ροή σύνδεσης”Ο EventSource του προγράμματος περιήγησης δεν μπορεί να στείλει προσαρμοσμένα κεφαλίδες, οπότε τα διαπιστευτήρια απαιτούν δύο βήματα:
- Ο διακομιστής σας ανταλλάσσει το API key με ένα ticket (ισχύει για 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ή χρησιμοποιήστε poll αντί γι’ αυτό - Όταν δεν υπάρχουν εκδηλώσεις εργασίας για μεγάλο χρονικό διάστημα, ο διακομιστής στέλνει μια εκδήλωση
timeout; λάβετε ένα νέο εισιτήριο και επανασυνδεθείτε - Όσο η σύνδεση είναι ανενεργή, ο διακομιστής στέλνει σχόλια καρδιοπάλμου· οι πελάτες θα πρέπει να αγνοούν τις γραμμές σχολίων.
- Εάν η σύνδεση διακοπεί, η ανάκτηση
GET /jobs/{id}λειτουργεί ως εφεδρική λύση