Přejít na obsah
Sursa Developers

GET/v1/jobs/stream

Streamovat změny úloh (SSE)

jobs_stream

Server-Sent Events: snímek aktuální dávky, poté změny úloh organizace (fáze, procento, název souboru).

Každá událost má id, což je kurzor v podobě časového razítka. Při opětovném připojení ho prohlížeč odešle v Last-Event-ID (nebo klient předá ?since=) a snímek se doplní o vše, co se změnilo během výpadku spojení.

Běhy zdrojů mohou vytvářet i události {"type": "source", "source": {"id", "status", "updated_at"}} bez kurzoru ID. status je fáze probíhající synchronizace (listing, syncing, retry) nebo její výsledek (ok, partial, error). Stažené soubory indexují úlohy a přicházejí jako události job, stejně jako nahrané soubory.

Autentizace

Odešlete klíč API v hlavičce Authorization: Authorization: Bearer <klíč>.

Parametry dotazu

  • sincestring | null

    Kurzor pro obnovení (čas ve formátu ISO s časovým pásmem), alternativa k Last-Event-ID.

Parametry hlavičky

  • X-View-Asstring

    Jen pro klíče API s rolí admin. Provede požadavek jako datový profil <profile>[:viewer|verifier|editor], například employee:viewer. Instalační klíč tuto hlavičku použít nemůže (403).

  • Last-Event-IDstring | null

    ID poslední přijaté události (opětovné připojení EventSource). Stream začne událostmi, které po ní následují.

Parametry cookie

  • kb_view_asstring

    Cookie režimu „View as“ pro relaci. POST /auth/view-as ji nastaví a DELETE /auth/view-as ji smaže.

Odpovědi

200`text/event-stream`. Prvním polem je `retry: 3000`, pak následuje událost `snapshot` s aktuálními úlohami a souhrnem a po ní události `job` (změnila se úloha) a `summary` (souhrn po změně stavu). Každá událost nese `id:`, kurzor v podobě časového razítka (ISO). Při opětovném připojení ho prohlížeč odešle v `Last-Event-ID` (nebo ho klient předá v `?since=`) a snímek se doplní o vše, co se změnilo během výpadku spojení (až 24 hodin zpětně). Po každých 15 sekundách ticha server odešle komentář `: keep-alive`. Hlavičky odpovědi: `Cache-Control: no-cache`, `X-Accel-Buffering: no`.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

text/event-stream

Objekt: JobStreamEvent

Jedna z možností

401Nebyly odeslány žádné přihlašovací údaje (ani cookie relace, ani klíč API), nebo klíč nebyl nalezen.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

403Akce není povolena: role nestačí, chybí přístup ke kolekci nebo kartě, požadavek běží v režimu „View as“, nebo je organizace pozastavená či smazaná (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

422Chyba validace: tělo nebo parametry neodpovídají schématu (`detail` je seznam chyb validace), nebo je hodnota parametru mimo povolený rozsah (`detail` je zpráva).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

429Příliš mnoho požadavků (`api.rate_limited`), kvóta organizace na minutu, den nebo měsíc je vyčerpána (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), organizace dosáhla svého limitu nebo je služba odpovědí vytížená (`answers.engine_busy`). Počkejte dobu uvedenou v hlavičce `Retry-After`.

Hlavičky odpovědi

  • Retry-After

    Počet sekund, které je třeba počkat před opakováním požadavku.

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, které tato operace může vrátit v error.code, kromě obecných kódů každého požadavku.

Limity četnosti

Odpovědi obsahují hlavičky RateLimit a RateLimit-Policy a starší X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpověď 429 má hlavičku Retry-After v sekundách: počkejte a požadavek zopakujte.

← jobs · Reference API