---
url: https://docs.ogmabox.com/th/plugins/frontend-sdk.md
description: >-
  เอกสารอ้างอิง API ของปลั๊กอินฟรอนต์เอนด์ Ogma การผสานรวม iframe การเรียกบริดจ์
  แผง UI คำสั่ง และการสื่อสารกับโฮสต์
---

# เอกสารอ้างอิง 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 ของหน้าที่ครอบ iframe | ถูกปิดกั้น (ไม่มี `allow-same-origin`) |
| คุกกี้เซสชันของ Ogma | ปลั๊กอินเข้าถึงไม่ได้ |
| การสื่อสารระหว่างปลั๊กอิน | ไม่รองรับ |

การเรียกบริดจ์ข้อมูลจะได้รับการตรวจสอบสิทธิ์ฝั่งเซิร์ฟเวอร์ในทุกคำขอ ส่วนการแสดงผลและการนำทางจัดการโดย UI ของโฮสต์ แคชสิทธิ์ที่แสดงในแท็บสิทธิ์มีไว้เพื่อแสดงผลเท่านั้น ไม่ได้ใช้ควบคุมการเข้าถึงข้อมูล

***

## โปรโตคอลบริดจ์ {#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 ยังคงอยู่ภายใน iframe ไม่ได้ซีเรียลไลซ์ส่งผ่านบริดจ์

### `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 }`

ลงทะเบียนคำสั่งปลั๊กอินในที่เก็บคำสั่งของโฮสต์ เมื่อโฮสต์ดำเนินการ จะส่งข้อความ `plugin_command` ที่มี `commandId` และบริบทกลับไปยัง iframe; ปลั๊กอินต้องจัดเตรียมคอลแบ็กที่ตรงกัน การลงทะเบียนเพียงอย่างเดียวไม่ทำให้คำสั่งทำงาน

### `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 และสมัครรับการอัปเดตธีมจากโฮสต์โดยไม่ต้องมีคำสั่งบริดจ์ข้อมูลแยกต่างหาก ใช้เพื่อให้ UI ของปลั๊กอินสอดคล้องกับรูปแบบสว่าง/มืดของ 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`.