---
url: https://docs.ogmabox.com/he/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`) |
| עוגיות ההפעלה של Ogma | אינן נגישות לתוסף |
| תקשורת בין תוספים | אינה זמינה |

ההרשאות לקריאות גשר הנתונים נבדקות בצד השרת בכל בקשה; פעולות תצוגה וניווט מטופלות בממשק המשתמש של המארח. מטמון ההרשאות המוצג בלשונית הרשאות מיועד לתצוגה בלבד; הוא אינו קובע את הגישה לנתונים.

***

## פרוטוקול הגשר {#bridge-protocol}

קוד ה-JS של התוסף מתקשר עם מארח 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 KiB; בדקו את דגלי הקיטוע לפני עיבוד נכס שלם.

נדרשת: `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 }`

רושמת פריט בתפריט הקשר המקושר לפקודת תוסף. רשמו תחילה את הפקודה. התווית היא כברירת מחדל השם הרשום של הפקודה, ואם אין שם, המזהה שלה; כאשר `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`.