--- url: https://docs.ogmabox.com/cs/plugins/frontend-sdk.md description: >- Referenční dokumentace frontendových API pluginů Ogma, integrace iframe, volání můstku, panelů rozhraní, příkazů a komunikace s hostitelskou aplikací. --- # Referenční dokumentace frontendového SDK pluginů {#plugin-frontend-sdk-reference} Frontendový kód pluginu běží v izolovaném iframe. Tento dokument je nízkoúrovňová referenční dokumentace. Obecnější úvod najdete v [README.md](./README.md). *** ## Bezpečnostní model {#security-model} | Vlastnost | Hodnota | |----------|-------| | Sandbox iframe | Pouze `allow-scripts` (bez `allow-same-origin`) | | CSP `script-src` | Načtení skriptu vyžaduje platné nonce; načítá se pouze skript vstupního bodu | | CSP `connect-src` | `'self'` – plugin může odesílat POST na `/plugins/{id}/api/*` a pravidelně získávat události z `/plugins/{id}/events/poll` | | CSP `default-src` | `'none'` | | Přístup k nadřazenému DOM | Blokován (bez `allow-same-origin`) | | Cookies relace Ogma | Pro plugin nepřístupné | | Komunikace mezi pluginy | Není dostupná | Volání datového můstku se autorizují na straně serveru při každém požadavku; zobrazování a navigaci zajišťuje rozhraní hostitelské aplikace. Mezipaměť oprávnění zobrazená na kartě Oprávnění slouží pouze k zobrazení; nevynucuje oprávnění k přístupu k datům. *** ## Protokol můstku {#bridge-protocol} JavaScript pluginu komunikuje s hostitelskou aplikací Ogma prostřednictvím `postMessage`. Hostitelská část se nachází v `PluginsView.vue` a zpracovává zprávy `bridge_request`. ### Obálka požadavku {#request-envelope} ```ts interface BridgeRequest { type: 'bridge_request' sessionId: string // nonce assigned when the bridge is set up; prevents stale messages requestId: string // caller-generated correlation id (max 128 chars) command: string // e.g. "ogma.requests.get" payload?: unknown // command-specific input } ``` Maximální celková velikost zprávy: 65 536 bajtů. ### Obálka odpovědi {#response-envelope} ```ts interface BridgeResponse { type: 'bridge_response' requestId: string ok: boolean result?: unknown error?: string code?: string } ``` ### Použití SDK (doporučeno) {#using-the-sdk-recommended} Neposílejte ručně přímé požadavky můstku přes `postMessage`. Používejte globální objekt `ogmaSDK`: ```js ogmaSDK.ready(function(sdk) { sdk.meta.get().then(function(meta) { sdk.log.info("running as " + meta.pluginId); }); }); ``` SDK zastřešuje veškerou komunikaci můstku a zajišťuje párování požadavků s odpověďmi, správu sessionId a vyřešení objektů Promise. *** ## Referenční dokumentace příkazů {#command-reference} ### `ogma.meta.get` {#ogma-meta-get} Nevyžaduje vstupní data. Vrací `{ pluginId, packageId, name, version, ogmaVersion }`. ### `ogma.requests.get` {#ogma-requests-get} Vstupní data: `{ id: string }` Vrací projekci záznamu HTTP. Pole: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Tato projekce nezahrnuje hlavičky ani bajty těla. Vyžaduje: `read_http_history` (udělováno automaticky). ### `ogma.requests.getRaw` {#ogma-requests-getraw} Vstupní data: `{ id: string }`. Volejte prostřednictvím `sdk.requests.getRaw(id)`. Vrací `requestBodyBase64`, `responseBodyBase64`, jejich délky po dekódování (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` a `maxBodyBytes`. Navzdory názvu tato operace vrací bajty těla, nikoli celou nezpracovanou zprávu HTTP. Podporovaná kódování obsahu se dekódují před projekcí. Každé tělo je omezeno na 256 KiB; před zpracováním celého prostředku zkontrolujte příznaky zkrácení. Vyžaduje: `read_http_history` (udělováno automaticky). ### `ogma.requests.search` {#ogma-requests-search} Vstupní data: `{ limit?: number, offset?: number, query?: string }` `query` podporuje filtrovací výrazy HTTPQL. Maximální `limit`: 20. Vrací `{ items: [...], total: number, limit: number, offset: number }`. Vyžaduje: `read_http_history` (udělováno automaticky). ### `ogma.findings.list` {#ogma-findings-list} Vstupní data: `{ limit?: number, offset?: number }` Vrací `{ items: [...], total: number, limit: number, offset: number }`, nejvýše 20 nálezů na stránku. Položky jsou souhrny; pole zahrnují `id`, `title`, `severity`, `status`, `reporter`, `tags` a `created_at`. Vyžaduje: `read_findings` (udělováno automaticky). ### `ogma.scope.getActive` {#ogma-scope-getactive} Bez vstupních dat. Vrací aktivní předvolbu rozsahu testování nebo `null`. Vyžaduje: `read_scope` (udělováno automaticky). ### `ogma.projects.getCurrent` {#ogma-projects-getcurrent} Bez vstupních dat. Vrací `{ id, name, status }` nebo `null`. Vyžaduje: `read_projects` (udělováno automaticky). ### `ogma.log` {#ogma-log} Vstupní data: `{ message: string }` Zapisuje do vyrovnávací paměti protokolů pluginu. ### `ogma.ui.resize` {#ogma-ui-resize} Vstupní data: `{ height: number }` (maximum 2000) Požádá hostitelskou aplikaci o nastavení výšky iframe. ### `ogma.ui.sidebar.registerItem` {#ogma-ui-sidebar-registeritem} Vstupní data: `{ name: string, path: string }` (název maximálně 64 znaků, cesta maximálně 256 znaků) Registruje navigaci v panelu pluginu. Maximálně 20 položek na plugin. Odpovídající obsah stránek zaregistrujte pomocí `sdk.navigation.addPage(path, { title, body })`; výběrem položky se daná stránka zobrazí uvnitř iframe, nevytváří se nová trasa na nejvyšší úrovni pracovního prostoru Ogma. ### `ogma.backend.call` {#ogma-backend-call} Vstupní data: `{ method: string, args: unknown[] }` Volá backendovou obslužnou funkci RPC zaregistrovanou pomocí `sdk.api.register(method, fn)`. Maximální délka názvu metody je 64 znaků. Vrací vše, co vrátila backendová obslužná funkce, serializované do JSON. ### `ogma.backend.onEvent` {#ogma-backend-onevent} Vstupní data: nejsou vyžadována. Pouze potvrzuje přijetí. Pro skutečné získávání událostí použijte `ogma.events.poll`. ### `ogma.events.poll` {#ogma-events-poll} Vstupní data: `{ since: number }` (index z posledního dotazu; začněte na 0) Vrací `{ events: [{ event: string, args: unknown[] }], next_since: number }`. ### `ogma.navigation.addPage` {#ogma-navigation-addpage} Vstupní data: `{ path: string, title?: string }` Můstek potvrzuje přijetí cesty stránky. Vložené SDK navíc přijímá `{ body: HTMLElement }` jako volbu pro `sdk.navigation.addPage(path, options)`, připojí obsah uvnitř iframe a přepíná viditelnost stránky, když hostitelská aplikace vybere odpovídající položku postranního panelu. Uzel DOM zůstává místní; přes můstek se neserializuje. ### `ogma.window.showToast` {#ogma-window-showtoast} Vstupní data: `{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }` Zobrazuje krátké oznámení v panelu pluginu. Doba zobrazení je v ms (maximum 10000, výchozí hodnota 3000). ### `ogma.commands.register` {#ogma-commands-register} Vstupní data: `{ id: string, name: string }` Registruje příkaz pluginu v úložišti příkazů hostitelské aplikace. Při spuštění v hostitelské aplikaci se zpět do iframe odešle zpráva `plugin_command` obsahující `commandId` a kontext; plugin musí poskytnout odpovídající obslužnou funkci. Samotná registrace příkaz nespouští. ### `ogma.menu.registerItem` {#ogma-menu-registeritem} Vstupní data: `{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }` Registruje položku kontextové nabídky propojenou s příkazem pluginu. Nejdříve zaregistrujte příkaz. Popiskem je ve výchozím nastavení registrovaný název příkazu, a pokud není k dispozici, jeho ID; vynechaný `type` má výchozí hodnotu `Request`. Hostitelský můstek nepoužívá `leadingIcon`. ### Pomocné funkce pro vzhled {#theme-helpers} Vložené SDK poskytuje také `sdk.theme.get()` a `sdk.theme.onChange(callback)`. Tyto funkce čtou vzhled iframe a přihlašují se k aktualizacím vzhledu hostitelské aplikace bez samostatného příkazu datového můstku. Používejte je, aby rozhraní pluginu odpovídalo světlému či tmavému vzhledu Ogma. *** ## Chybové kódy {#error-codes} | Kód | Význam | |------|---------| | `PERMISSION_DENIED` | Plugin nemá požadované oprávnění. | | `PLUGIN_DISABLED` | Plugin momentálně není zapnutý. | | `UNKNOWN_COMMAND` | Příkaz není v seznamu podporovaných příkazů. | | `INVALID_PAYLOAD` | Povinné pole vstupních dat chybí nebo má nesprávný typ. | | `NOT_FOUND` | Požadovaný zdroj neexistuje. | | `LIMIT_EXCEEDED` | Byl dosažen limit počtu pro daný plugin (například položek postranního panelu). | | `SERVER_ERROR` | Interní chyba. Zkontrolujte protokoly pluginu. | *** ## Seznam podporovaných příkazů {#supported-commands-list} `ogma.meta.get`, `ogma.log`, `ogma.ui.resize`, `ogma.ui.sidebar.registerItem`, `ogma.requests.get`, `ogma.requests.getRaw`, `ogma.requests.search`, `ogma.findings.list`, `ogma.scope.getActive`, `ogma.projects.getCurrent`, `ogma.backend.call`, `ogma.backend.onEvent`, `ogma.events.poll`, `ogma.navigation.addPage`, `ogma.window.showToast`, `ogma.commands.register`, `ogma.menu.registerItem`.