---
url: https://docs.ogmabox.com/vi/plugins/frontend-sdk.md
description: >-
  Tài liệu tham khảo API plugin frontend Ogma, tích hợp iframe, lệnh gọi cầu
  nối, bảng giao diện, lệnh và giao tiếp với ứng dụng chủ.
---

# Tài liệu tham khảo SDK frontend cho plugin {#plugin-frontend-sdk-reference}

Mã frontend của plugin chạy trong iframe được cách ly bằng sandbox. Tài liệu này là tài liệu tham khảo cấp thấp. Để xem phần giới thiệu ở cấp cao hơn, xem [README.md](./README.md).

***

## Mô hình bảo mật {#security-model}

| Thuộc tính | Giá trị |
|----------|-------|
| Sandbox của iframe | Chỉ có `allow-scripts` (không có `allow-same-origin`) |
| CSP `script-src` | Giới hạn bằng nonce; chỉ tải tập lệnh tại điểm vào |
| CSP `connect-src` | `'self'` - plugin có thể gửi POST đến `/plugins/{id}/api/*` và truy vấn định kỳ `/plugins/{id}/events/poll` |
| CSP `default-src` | `'none'` |
| Truy cập DOM của trang cha | Bị chặn (không có `allow-same-origin`) |
| Cookie phiên Ogma | Plugin không thể truy cập |
| Giao tiếp giữa các plugin | Không khả dụng |

Các lệnh gọi dữ liệu qua cầu nối được kiểm tra quyền ở phía máy chủ với mỗi yêu cầu; thao tác hiển thị và điều hướng do giao diện ứng dụng chủ xử lý. Bộ nhớ đệm quyền hiển thị trong thẻ Quyền chỉ dùng để hiển thị; nó không kiểm soát quyền truy cập dữ liệu.

***

## Giao thức cầu nối {#bridge-protocol}

JavaScript của plugin giao tiếp với ứng dụng chủ Ogma qua `postMessage`. Thành phần chủ nằm trong `PluginsView.vue` và xử lý thông điệp `bridge_request`.

### Cấu trúc bao của yêu cầu {#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
}
```

Tổng kích thước thông điệp tối đa: 65 536 byte.

### Cấu trúc bao của phản hồi {#response-envelope}

```ts
interface BridgeResponse {
  type: 'bridge_response'
  requestId: string
  ok: boolean
  result?: unknown
  error?: string
  code?: string
}
```

### Dùng SDK (khuyến nghị) {#using-the-sdk-recommended}

Không gửi thủ công yêu cầu cầu nối thô bằng `postMessage`. Dùng đối tượng toàn cục `ogmaSDK`:

```js
ogmaSDK.ready(function(sdk) {
  sdk.meta.get().then(function(meta) {
    sdk.log.info("running as " + meta.pluginId);
  });
});
```

SDK bao bọc toàn bộ giao tiếp cầu nối và xử lý việc đối chiếu yêu cầu, quản lý sessionId và hoàn tất Promise.

***

## Tài liệu tham khảo lệnh {#command-reference}

### `ogma.meta.get` {#ogma-meta-get}

Không cần payload.

Trả về `{ pluginId, packageId, name, version, ogmaVersion }`.

### `ogma.requests.get` {#ogma-requests-get}

Payload: `{ id: string }`

Trả về mục HTTP dưới dạng bản chiếu. Các trường: `id`, `method`, `host`, `port`, `path`, `query`, `req_len`, `resp_status`, `resp_len`, `roundtrip_ms`, `created_at`. Bản chiếu này không bao gồm header hoặc byte nội dung.

Yêu cầu: `read_http_history` (được cấp tự động).

### `ogma.requests.getRaw` {#ogma-requests-getraw}

Payload: `{ id: string }`. Gọi thông qua `sdk.requests.getRaw(id)`.

Trả về `requestBodyBase64`, `responseBodyBase64`, độ dài sau khi giải mã của chúng (`requestBodyLength`, `responseBodyLength`), `requestBodyTruncated`, `responseBodyTruncated` và `maxBodyBytes`. Dù có tên như vậy, thao tác này trả về byte nội dung, không phải toàn bộ thông điệp HTTP thô. Các kiểu mã hóa nội dung được hỗ trợ sẽ được giải mã trước khi tạo bản chiếu. Mỗi phần nội dung bị giới hạn ở 256 KiB; kiểm tra cờ cắt ngắn trước khi xử lý một tài nguyên hoàn chỉnh.

Yêu cầu: `read_http_history` (được cấp tự động).

### `ogma.requests.search` {#ogma-requests-search}

Payload: `{ limit?: number, offset?: number, query?: string }`

`query` hỗ trợ biểu thức lọc HTTPQL. `limit` tối đa: 20. Trả về `{ items: [...], total: number, limit: number, offset: number }`.

Yêu cầu: `read_http_history` (được cấp tự động).

### `ogma.findings.list` {#ogma-findings-list}

Payload: `{ limit?: number, offset?: number }`

Trả về `{ items: [...], total: number, limit: number, offset: number }`, với tối đa 20 phát hiện mỗi trang. Các mục là bản tóm tắt; các trường bao gồm `id`, `title`, `severity`, `status`, `reporter`, `tags` và `created_at`.

Yêu cầu: `read_findings` (được cấp tự động).

### `ogma.scope.getActive` {#ogma-scope-getactive}

Không có payload. Trả về bộ thiết lập sẵn cho phạm vi đang hoạt động hoặc `null`.

Yêu cầu: `read_scope` (được cấp tự động).

### `ogma.projects.getCurrent` {#ogma-projects-getcurrent}

Không có payload. Trả về `{ id, name, status }` hoặc `null`.

Yêu cầu: `read_projects` (được cấp tự động).

### `ogma.log` {#ogma-log}

Payload: `{ message: string }`

Ghi vào bộ đệm nhật ký của plugin.

### `ogma.ui.resize` {#ogma-ui-resize}

Payload: `{ height: number }` (tối đa 2000)

Yêu cầu ứng dụng chủ đặt chiều cao iframe.

### `ogma.ui.sidebar.registerItem` {#ogma-ui-sidebar-registeritem}

Payload: `{ name: string, path: string }` (tên tối đa 64 ký tự, đường dẫn tối đa 256 ký tự)

Đăng ký điều hướng trong bảng plugin. Tối đa 20 mục cho mỗi plugin. Đăng ký nội dung các trang tương ứng bằng `sdk.navigation.addPage(path, { title, body })`; chọn mục sẽ hiển thị trang đó trong iframe, không phải một tuyến cấp cao nhất mới của không gian làm việc Ogma.

### `ogma.backend.call` {#ogma-backend-call}

Payload: `{ method: string, args: unknown[] }`

Gọi hàm xử lý RPC backend được đăng ký qua `sdk.api.register(method, fn)`. Độ dài tên phương thức tối đa là 64 ký tự.

Trả về giá trị hàm xử lý backend đã trả về, được tuần tự hóa thành JSON.

### `ogma.backend.onEvent` {#ogma-backend-onevent}

Payload: không cần.

Chỉ xác nhận đã nhận. Dùng `ogma.events.poll` để thực sự lấy sự kiện.

### `ogma.events.poll` {#ogma-events-poll}

Payload: `{ since: number }` (chỉ số từ lần truy vấn định kỳ trước; bắt đầu ở 0)

Trả về `{ events: [{ event: string, args: unknown[] }], next_since: number }`.

### `ogma.navigation.addPage` {#ogma-navigation-addpage}

Payload: `{ path: string, title?: string }`

Cầu nối xác nhận đã nhận đường dẫn trang. SDK được chèn vào còn chấp nhận `{ body: HTMLElement }` làm tùy chọn cho `sdk.navigation.addPage(path, options)`, gắn nội dung trong iframe và chuyển trạng thái hiển thị trang khi ứng dụng chủ chọn mục tương ứng trên thanh bên. Nút DOM vẫn ở cục bộ; nó không được tuần tự hóa qua cầu nối.

### `ogma.window.showToast` {#ogma-window-showtoast}

Payload: `{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }`

Hiển thị thông báo tạm thời trong bảng plugin. Thời lượng tính bằng ms (tối đa 10000, mặc định 3000).

### `ogma.commands.register` {#ogma-commands-register}

Payload: `{ id: string, name: string }`

Đăng ký lệnh plugin vào kho lệnh của ứng dụng chủ. Khi thực thi, ứng dụng chủ gửi thông điệp `plugin_command` chứa `commandId` và ngữ cảnh trở lại iframe; plugin phải cung cấp callback tương ứng. Chỉ đăng ký không thực thi lệnh.

### `ogma.menu.registerItem` {#ogma-menu-registeritem}

Payload: `{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }`

Đăng ký mục menu ngữ cảnh gắn với lệnh plugin. Đăng ký lệnh trước. Nhãn mặc định là tên đã đăng ký của lệnh, nếu không có thì dùng ID; khi bỏ qua `type`, mặc định là `Request`. Cầu nối của ứng dụng chủ không sử dụng `leadingIcon`.

### Hàm hỗ trợ chủ đề giao diện {#theme-helpers}

SDK được chèn vào cũng cung cấp `sdk.theme.get()` và `sdk.theme.onChange(callback)`. Các hàm này đọc chủ đề giao diện của iframe và đăng ký nhận cập nhật chủ đề từ ứng dụng chủ mà không cần lệnh dữ liệu cầu nối riêng. Dùng chúng để giao diện plugin nhất quán với giao diện sáng/tối của Ogma.

***

## Mã lỗi {#error-codes}

| Mã | Ý nghĩa |
|------|---------|
| `PERMISSION_DENIED` | Plugin thiếu quyền cần thiết. |
| `PLUGIN_DISABLED` | Plugin hiện chưa được bật. |
| `UNKNOWN_COMMAND` | Lệnh không nằm trong danh sách được hỗ trợ. |
| `INVALID_PAYLOAD` | Trường payload bắt buộc bị thiếu hoặc có kiểu không đúng. |
| `NOT_FOUND` | Tài nguyên được yêu cầu không tồn tại. |
| `LIMIT_EXCEEDED` | Đã đạt giới hạn số lượng cho mỗi plugin (ví dụ: mục trên thanh bên). |
| `SERVER_ERROR` | Lỗi nội bộ. Kiểm tra nhật ký plugin. |

***

## Danh sách lệnh được hỗ trợ {#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`.