Průběh provisioningu v reálném čase

Vytvořili jste provisioning job a během milisekund dostali zpět ID jobu pjb_ a ID enginu eng_. Engine je už použitelný, ale stále se doplňuje: AI agent prochází vaše zdroje a zapisuje do něj hlas značky, položky glosáře a instrukce. Během toho chcete ukazovat, co se děje – řádek typu „Procházíme váš style guide… konfigurujeme engine… hotovo“, podobně jako v instalačním průvodci, místo spinneru, který nic neříká.

WebSocket vám dává přesně tenhle přehled. Připojte se k jobu a server pošle snapshot aktuálního stavu, pak událost provisioning.progress pokaždé, když workflow přejde do dalšího kroku. A protože server při připojení posílá aktuální stav a dokončený job hned poté uzavírá, můžete se připojit kdykoli, i po jeho dokončení – není tu žádné okno, které byste museli stihnout.

GET /jobs/provisioning/:jobId/ws

jobId je hodnota pjb_ z create call. S asynchronním provisioningem teprve začínáte? Začněte v Přehled, kde najdete základní mentální model.

Na této stránce

• Typy zpráv
• Snapshot při připojení
• Události průběhu
• Připojení po dokončení jobu
• Jak to zapojit do UI
• API klíč nechte na serveru

Typy zpráv#

Přes socket chodí dva typy zpráv. První dorazí jednou při připojení, druhý pak opakovaně podle toho, jak job postupuje.

Tohle je feed o živém stavu, ne o výsledcích: řekne vám, kde se job nachází a jestli selhal, ale ne které záznamy AI vytvořila. Souhrn všeho, co se provisionovalo – ID hlasu značky, glosáře a instrukcí – dorazí zvlášť, v completion webhooku nebo načtením jobu po jeho dokončení. Socket si nechte pro progress bar; pro payload použijte webhook.

Snapshot při připojení#

Jakmile se připojíte, server načte z databáze aktuální stav jobu a pošle ho. Není potřeba, aby předtím dorazila nějaká událost průběhu – snapshot funguje sám o sobě.

{
  "type": "provisioning.snapshot",
  "jobId": "pjb_A1b2C3d4E5f6G7h8",
  "status": "in_progress",
  "errorMessage": null
}

Snapshot je jediná zpráva, kterou máte zaručeně dostat. Pokud job stále běží, po ní přijdou události průběhu; pokud už job skončil, dostanete snapshot a nic víc (viz níže).

Události průběhu#

Jak workflow běží, server vysílá událost provisioning.progress pokaždé, když vstoupí do nového kroku. Každá událost pojmenuje step a nese čitelný detail pro člověka.

{
  "type": "provisioning.progress",
  "jobId": "pjb_A1b2C3d4E5f6G7h8",
  "step": "crawling",
  "detail": "Crawling source URLs..."
}

Připojení po dokončení jobu#

Zásadní otázka u každého progress socketu zní: co se stane, když se připojíte pozdě – po dokončení crawlu, po tom, co se panel znovu připojí po deployi, nebo když job už mezitím selhal? Tady je odpověď zabudovaná přímo do toho, jak funguje snapshot.

Pokud job už dosáhl stavu completed nebo failed, server pošle snapshot s tímto finálním status (a errorMessage, pokud selhal) a spojení okamžitě uzavře. Nejsou tu žádné události průběhu k přehrání, protože finální stav je právě snapshot. Job, který je stále v běhu, nechá spojení otevřené a streamuje průběh; dokončený job vám předá výsledek a zavěsí.

V obou případech vám první zpráva řekne, na čem jste. Připojte se kdykoli, i po dokončení – nemůžete se připojit ani příliš brzy, ani příliš pozdě.

Jak to zapojit do UI#

Otevřete socket nad ID jobu pjb_, ze snapshotu nastavte počáteční stav, pak stav aktualizujte při každé události průběhu a spojení zavřete, jakmile job dosáhne completed nebo failed:

import WebSocket from "ws";

const jobId = "pjb_A1b2C3d4E5f6G7h8";
const ws = new WebSocket(
  `wss://api.lingo.dev/jobs/provisioning/${jobId}/ws`,
  { headers: { "X-API-Key": process.env.LINGO_API_KEY } }
);

ws.on("message", (raw) => {
  const event = JSON.parse(raw);

  switch (event.type) {
    case "provisioning.snapshot":
      console.log(`status: ${event.status}`);
      break;

    case "provisioning.progress":
      console.log(`${event.step}: ${event.detail}`);
      if (event.step === "completed" || event.step === "failed") {
        ws.close();
      }
      break;
  }
});

Spusťte to na jobu, který projde crawlingem bez problémů a krok za krokem vypisuje, jak konfigurace probíhá:

status: in_progress
crawling: Crawling source URLs...
configuring: AI agent analyzing content and configuring engine...
completed: Provisioning complete

To je celý průběh na obrazovce: job se otevře ve stavu in_progress, sledujete crawling a pak konfiguraci a completed vám řekne, že engine je plně provisionovaný. Stejná smyčka funguje správně i při pozdním připojení – dokončený job pošle jeden snapshot se svým finálním status a socket se zavře, takže kód, který zpracovává živý běh, zvládne i replay bez speciální podmínky.

API klíč nechte na serveru#

Socket se autentizuje vaším API klíčem – stejným organization-scoped key, který používají REST endpointy. Tento klíč dává přístup ke každému enginu ve vaší organizaci, takže prohlížeč je pro otevření spojení to poslední správné místo: kdokoli, kdo si zobrazí zdrojový kód, by ho uviděl.

Je to stejný model jako u webhooku: spojení, které komunikuje s Lingo.dev, běží na serveru a k uživateli dorazí jen to, co se vaše aplikace rozhodne poslat dál.

Kam to zapadá#

WebSocket je živý pohled – je navázaný na jeden job a zavře se, jakmile je hotovo. Pokud chcete trvalý server-to-server záznam výsledku, který přežije zavřený panel nebo deploy, spárujte ho s completion webhookem: socket pohání progress bar, zatímco je job na obrazovce, webhook doručí souhrn všeho, co AI vytvořila, ve chvíli, kdy je hotovo. Obojí zapojíte ze stejného create call.