--- url: https://docs.ogmabox.com/tr/plugins/frontend-sdk.md description: >- Ogma frontend eklenti API'leri, iframe entegrasyonu, köprü çağrıları, arayüz panelleri, komutlar ve ana uygulamayla iletişim için başvuru. --- # Eklenti frontend SDK başvurusu {#plugin-frontend-sdk-reference} Eklentinin frontend kodu, korumalı bir iframe içinde çalışır. Bu belge düşük seviyeli bir başvuru kaynağıdır. Daha genel bir giriş için [README.md](./README.md) sayfasına bakın. *** ## Güvenlik modeli {#security-model} | Özellik | Değer | |----------|-------| | Iframe korumalı alanı | Yalnızca `allow-scripts` (`allow-same-origin` yok) | | CSP `script-src` | Nonce ile sınırlandırılır; yalnızca giriş noktası betiği yüklenir | | CSP `connect-src` | `'self'` — eklenti `/plugins/{id}/api/*` adresine POST isteği gönderebilir ve `/plugins/{id}/events/poll` adresini düzenli olarak sorgulayabilir | | CSP `default-src` | `'none'` | | Üst öğenin DOM'una erişim | Engellenir (`allow-same-origin` yok) | | Ogma oturum çerezleri | Eklenti tarafından erişilemez | | Eklentiler arası iletişim | Kullanılamaz | Veri köprüsü çağrıları her istekte sunucu tarafında yetkilendirilir; görüntüleme ve gezinme işlemlerini ana uygulamanın arayüzü yürütür. İzinler sekmesinde gösterilen izin önbelleği yalnızca bilgi amaçlıdır; veri erişimini denetlemez. *** ## Köprü protokolü {#bridge-protocol} Eklenti JS kodu, Ogma ana uygulamasıyla `postMessage` üzerinden iletişim kurar. Ana uygulama tarafındaki kod `PluginsView.vue` içinde bulunur ve `bridge_request` mesajlarını işler. ### İstek zarfı {#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 } ``` Toplam mesaj boyutu en fazla 65 536 bayttır. ### Yanıt zarfı {#response-envelope} ```ts interface BridgeResponse { type: 'bridge_response' requestId: string ok: boolean result?: unknown error?: string code?: string } ``` ### SDK kullanımı (önerilen) {#using-the-sdk-recommended} Ham `postMessage` köprü isteklerini elle göndermeyin. Global `ogmaSDK` nesnesini kullanın: ```js ogmaSDK.ready(function(sdk) { sdk.meta.get().then(function(meta) { sdk.log.info("running as " + meta.pluginId); }); }); ``` SDK, tüm köprü iletişimini sarmalar; isteklerin eşleştirilmesini, sessionId yönetimini ve Promise'lerin sonuçlandırılmasını üstlenir. *** ## Komut başvurusu {#command-reference} ### `ogma.meta.get` {#ogma-meta-get} İstek verisi gerekmez. `{ pluginId, packageId, name, version, ogmaVersion }` döndürür. ### `ogma.requests.get` {#ogma-requests-get} İstek verisi: `{ id: string }` Seçilmiş alanlardan oluşan bir HTTP kaydı döndürür. Alanlar: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Bu görünüm başlıkları veya gövde baytlarını içermez. Gerekli izin: `read_http_history` (otomatik verilir). ### `ogma.requests.getRaw` {#ogma-requests-getraw} İstek verisi: `{ id: string }`. `sdk.requests.getRaw(id)` üzerinden çağırın. `requestBodyBase64`, `responseBodyBase64`, bunların çözülmüş uzunlukları (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` ve `maxBodyBytes` döndürür. Adına rağmen bu işlem, tam bir ham HTTP mesajı yerine gövde baytlarını döndürür. Desteklenen içerik kodlamaları, alanlar seçilmeden önce çözülür. Her gövde 256 KiB ile sınırlıdır; bir varlığın tamamını işlemeden önce kesilme bayraklarını kontrol edin. Gerekli izin: `read_http_history` (otomatik verilir). ### `ogma.requests.search` {#ogma-requests-search} İstek verisi: `{ limit?: number, offset?: number, query?: string }` `query`, HTTPQL filtre ifadelerini destekler. En büyük `limit`: 20. `{ items: [...], total: number, limit: number, offset: number }` döndürür. Gerekli izin: `read_http_history` (otomatik verilir). ### `ogma.findings.list` {#ogma-findings-list} İstek verisi: `{ limit?: number, offset?: number }` Sayfa başına en fazla 20 bulguyla `{ items: [...], total: number, limit: number, offset: number }` döndürür. Öğeler özet niteliğindedir; alanlar arasında `id`, `title`, `severity`, `status`, `reporter`, `tags` ve `created_at` bulunur. Gerekli izin: `read_findings` (otomatik verilir). ### `ogma.scope.getActive` {#ogma-scope-getactive} İstek verisi yoktur. Etkin kapsam ön ayarını veya `null` döndürür. Gerekli izin: `read_scope` (otomatik verilir). ### `ogma.projects.getCurrent` {#ogma-projects-getcurrent} İstek verisi yoktur. `{ id, name, status }` veya `null` döndürür. Gerekli izin: `read_projects` (otomatik verilir). ### `ogma.log` {#ogma-log} İstek verisi: `{ message: string }` Eklentinin günlük tamponuna yazar. ### `ogma.ui.resize` {#ogma-ui-resize} İstek verisi: `{ height: number }` (en fazla 2000) Ana uygulamadan iframe yüksekliğini ayarlamasını ister. ### `ogma.ui.sidebar.registerItem` {#ogma-ui-sidebar-registeritem} İstek verisi: `{ name: string, path: string }` (ad en fazla 64, yol en fazla 256 karakter) Eklenti paneli içinde bir gezinme öğesi kaydeder. Eklenti başına en fazla 20 öğe kullanılabilir. Eşleşen sayfa gövdelerini `sdk.navigation.addPage(path, { title, body })` ile kaydedin; öğe seçildiğinde bu sayfa iframe içinde gösterilir, Ogma çalışma alanında yeni bir üst düzey rota açılmaz. ### `ogma.backend.call` {#ogma-backend-call} İstek verisi: `{ method: string, args: unknown[] }` `sdk.api.register(method, fn)` ile kaydedilmiş bir backend RPC işleyicisini çağırır. Metot adının uzunluğu en fazla 64 karakterdir. Backend işleyicisinin döndürdüğü değeri JSON olarak serileştirip döndürür. ### `ogma.backend.onEvent` {#ogma-backend-onevent} İstek verisi gerekmez. Yalnızca alındı onayı verir. Olayları gerçekten almak için `ogma.events.poll` kullanın. ### `ogma.events.poll` {#ogma-events-poll} İstek verisi: `{ since: number }` (son sorgudaki indeks; 0 ile başlayın) `{ events: [{ event: string, args: unknown[] }], next_since: number }` döndürür. ### `ogma.navigation.addPage` {#ogma-navigation-addpage} İstek verisi: `{ path: string, title?: string }` Köprü, sayfa yolunun alındığını onaylar. Enjekte edilen SDK ayrıca `sdk.navigation.addPage(path, options)` çağrısında `{ body: HTMLElement }` seçeneğini kabul eder, gövdeyi iframe içine ekler ve ana uygulama eşleşen kenar çubuğu öğesini seçtiğinde sayfa görünürlüğünü değiştirir. DOM düğümü yerel kalır; köprü üzerinden serileştirilmez. ### `ogma.window.showToast` {#ogma-window-showtoast} İstek verisi: `{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }` Eklenti panelinde geçici bir bildirim gösterir. Süre milisaniye cinsindendir (en fazla 10000, varsayılan 3000). ### `ogma.commands.register` {#ogma-commands-register} İstek verisi: `{ id: string, name: string }` Eklenti komutunu ana uygulamanın komut deposuna kaydeder. Ana uygulamada çalıştırılması, `commandId` ve bağlam içeren bir `plugin_command` mesajını iframe'e geri gönderir; eklenti buna karşılık gelen geri çağırma işlevini sağlamalıdır. Yalnızca kaydetmek komutu çalıştırmaz. ### `ogma.menu.registerItem` {#ogma-menu-registeritem} İstek verisi: `{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }` Bir eklenti komutuna bağlı bağlam menüsü öğesi kaydeder. Önce komutu kaydedin. Etiket varsayılan olarak komutun kayıtlı adını, yoksa kimliğini kullanır; belirtilmeyen `type` için varsayılan `Request` olur. `leadingIcon`, ana uygulama köprüsü tarafından kullanılmaz. ### Tema yardımcıları {#theme-helpers} Enjekte edilen SDK, `sdk.theme.get()` ve `sdk.theme.onChange(callback)` işlevlerini de sağlar. Bunlar ayrı bir veri köprüsü komutu olmadan iframe temasını okur ve ana uygulamanın tema güncellemelerine abone olur. Eklenti arayüzünü Ogma'nın açık/koyu görünümüyle uyumlu tutmak için kullanın. *** ## Hata kodları {#error-codes} | Kod | Anlamı | |------|---------| | `PERMISSION_DENIED` | Eklentinin gerekli izni yoktur. | | `PLUGIN_DISABLED` | Eklenti şu anda etkin değildir. | | `UNKNOWN_COMMAND` | Komut desteklenenler listesinde değildir. | | `INVALID_PAYLOAD` | Gerekli bir istek verisi alanı eksiktir veya türü yanlıştır. | | `NOT_FOUND` | İstenen kaynak mevcut değildir. | | `LIMIT_EXCEEDED` | Eklenti başına sayı sınırına ulaşılmıştır (örneğin kenar çubuğu öğeleri). | | `SERVER_ERROR` | Dahili hata. Eklenti günlüklerini kontrol edin. | *** ## Desteklenen komutların listesi {#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`.