--- url: https://docs.ogmabox.com/ru/plugins/frontend-sdk.md description: >- Справочник API интерфейсных плагинов Ogma, интеграции iframe, вызовов моста, панелей, команд и связи с хостом. --- # Справочник интерфейсного SDK плагинов {#plugin-frontend-sdk-reference} Код интерфейса плагина работает в изолированном iframe. Это низкоуровневый справочник. Введение более высокого уровня см. в [README.md](./README.md). *** ## Модель безопасности {#security-model} | Свойство | Значение | |----------|-------| | Изоляция iframe | Только `allow-scripts` (без `allow-same-origin`) | | CSP `script-src` | Ограничен nonce; загружается только скрипт точки входа | | CSP `connect-src` | `'self'` — плагин может отправлять POST в `/plugins/{id}/api/*` и опрашивать `/plugins/{id}/events/poll` | | CSP `default-src` | `'none'` | | Доступ к родительскому DOM | Заблокирован (нет `allow-same-origin`) | | Cookie сессии Ogma | Недоступны плагину | | Связь между плагинами | Недоступна | Вызовы моста данных авторизуются на сервере при каждом запросе; отображение и навигацию обрабатывает интерфейс хоста. Кеш разрешений вкладки используется только для отображения и не управляет доступом к данным. *** ## Протокол моста {#bridge-protocol} JavaScript плагина общается с хостом Ogma через `postMessage`. Хост находится в `PluginsView.vue` и обрабатывает сообщения `bridge_request`. ### Оболочка запроса {#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 } ``` Максимальный общий размер сообщения: 65 536 байт. ### Оболочка ответа {#response-envelope} ```ts interface BridgeResponse { type: 'bridge_response' requestId: string ok: boolean result?: unknown error?: string code?: string } ``` ### Использование SDK (рекомендуется) {#using-the-sdk-recommended} Не формируйте и не отправляйте запросы к мосту через `postMessage` вручную. Используйте глобальный `ogmaSDK`: ```js ogmaSDK.ready(function(sdk) { sdk.meta.get().then(function(meta) { sdk.log.info("running as " + meta.pluginId); }); }); ``` SDK оборачивает всю связь через мост и управляет сопоставлением запросов и ответов, sessionId и завершением Promise. *** ## Справочник команд {#command-reference} ### `ogma.meta.get` {#ogma-meta-get} Входные данные не требуются. Возвращает `{ pluginId, packageId, name, version, ogmaVersion }`. ### `ogma.requests.get` {#ogma-requests-get} Вход: `{ id: string }` Возвращает представление HTTP-записи. Поля: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Представление не включает заголовки и байты тела. Требуется: `read_http_history` (выдаётся автоматически). ### `ogma.requests.getRaw` {#ogma-requests-getraw} Вход: `{ id: string }`. Вызывайте через `sdk.requests.getRaw(id)`. Возвращает `requestBodyBase64`, `responseBodyBase64`, декодированные длины (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` и `maxBodyBytes`. Несмотря на имя, возвращаются байты тел, а не полное сообщение в сетевом HTTP-формате. Поддерживаемые кодировки содержимого декодируются перед созданием представления. Каждое тело ограничено 256 КиБ; перед обработкой полного ресурса проверьте флаги усечения. Требуется: `read_http_history` (выдаётся автоматически). ### `ogma.requests.search` {#ogma-requests-search} Вход: `{ limit?: number, offset?: number, query?: string }` `query` поддерживает фильтры HTTPQL. Максимум `limit`: 20. Возвращает `{ items: [...], total: number, limit: number, offset: number }`. Требуется: `read_http_history` (выдаётся автоматически). ### `ogma.findings.list` {#ogma-findings-list} Вход: `{ limit?: number, offset?: number }` Возвращает `{ items: [...], total: number, limit: number, offset: number }`, не более 20 результатов проверки безопасности на страницу. Элементы — сводки; поля включают `id`, `title`, `severity`, `status`, `reporter`, `tags` и `created_at`. Требуется: `read_findings` (выдаётся автоматически). ### `ogma.scope.getActive` {#ogma-scope-getactive} Без входных данных. Возвращает активный набор области или `null`. Требуется: `read_scope` (выдаётся автоматически). ### `ogma.projects.getCurrent` {#ogma-projects-getcurrent} Без входных данных. Возвращает `{ id, name, status }` или `null`. Требуется: `read_projects` (выдаётся автоматически). ### `ogma.log` {#ogma-log} Вход: `{ message: string }` Пишет в буфер журнала плагина. ### `ogma.ui.resize` {#ogma-ui-resize} Вход: `{ height: number }` (максимум 2000) Просит хост задать высоту iframe. ### `ogma.ui.sidebar.registerItem` {#ogma-ui-sidebar-registeritem} Вход: `{ name: string, path: string }` (имя до 64 символов, путь до 256) Регистрирует навигацию внутри панели плагина. Максимум 20 элементов на плагин. Зарегистрируйте соответствующие тела страниц через `sdk.navigation.addPage(path, { title, body })`; выбор элемента показывает страницу внутри iframe, а не новый маршрут верхнего уровня пространства Ogma. ### `ogma.backend.call` {#ogma-backend-call} Вход: `{ method: string, args: unknown[] }` Вызывает серверный RPC-обработчик, зарегистрированный через `sdk.api.register(method, fn)`. Имя метода — до 64 символов. Возвращает результат обработчика, сериализованный в JSON. ### `ogma.backend.onEvent` {#ogma-backend-onevent} Входные данные не требуются. Только подтверждает. Для получения событий используйте `ogma.events.poll`. ### `ogma.events.poll` {#ogma-events-poll} Вход: `{ since: number }` (индекс последнего опроса; начните с 0) Возвращает `{ events: [{ event: string, args: unknown[] }], next_since: number }`. ### `ogma.navigation.addPage` {#ogma-navigation-addpage} Вход: `{ path: string, title?: string }` Мост подтверждает путь страницы. Внедрённый SDK дополнительно принимает `{ body: HTMLElement }` в параметрах `sdk.navigation.addPage(path, options)`, прикрепляет тело внутри iframe и переключает видимость, когда хост выбирает соответствующий элемент панели. Узел DOM остаётся локальным и не сериализуется через мост. ### `ogma.window.showToast` {#ogma-window-showtoast} Вход: `{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }` Показывает уведомление в панели плагина. Длительность в мс (максимум 10000, по умолчанию 3000). ### `ogma.commands.register` {#ogma-commands-register} Вход: `{ id: string, name: string }` Регистрирует команду в хранилище команд хоста. При выполнении хост отправляет в iframe сообщение `plugin_command` с `commandId` и контекстом; плагин должен предоставить соответствующий обработчик. Одна регистрация не выполняет команду. ### `ogma.menu.registerItem` {#ogma-menu-registeritem} Вход: `{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }` Регистрирует пункт контекстного меню, связанный с командой плагина. Сначала зарегистрируйте команду. Подпись по умолчанию — имя команды, затем ID; без `type` используется `Request`. `leadingIcon` не используется мостом хоста. ### Помощники темы {#theme-helpers} Внедрённый SDK также предоставляет `sdk.theme.get()` и `sdk.theme.onChange(callback)`. Они читают тему iframe и подписываются на обновления хоста без отдельной команды моста данных. Используйте для соответствия интерфейса плагина светлой или тёмной теме Ogma. *** ## Коды ошибок {#error-codes} | Код | Значение | |------|---------| | `PERMISSION_DENIED` | У плагина нет нужного разрешения. | | `PLUGIN_DISABLED` | Плагин сейчас отключён. | | `UNKNOWN_COMMAND` | Команда отсутствует в списке поддерживаемых. | | `INVALID_PAYLOAD` | Обязательное поле отсутствует или имеет неверный тип. | | `NOT_FOUND` | Запрошенный ресурс не существует. | | `LIMIT_EXCEEDED` | Достигнут предел числа объектов плагина (например, элементов панели). | | `SERVER_ERROR` | Внутренняя ошибка. Проверьте журналы. | *** ## Список поддерживаемых команд {#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`.