---
url: https://docs.ogmabox.com/vi/plugins/backend-sdk.md
description: >-
  Tài liệu tham khảo API plugin backend Ogma, thực thi trong sandbox, đường dẫn
  lưu trữ, truy cập lịch sử HTTP, phát hiện, lệnh và tích hợp với ứng dụng chủ.
---

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

Mã plugin backend chạy trong sandbox JavaScript của Ogma và nhận đối tượng `sdk` từ ứng dụng chủ.

Để tìm hiểu đầy đủ định dạng gói plugin, trường manifest, quyền và ví dụ, bắt đầu với [hướng dẫn hệ thống plugin](./README.md).

## Điểm vào {#entry-point}

Plugin backend cung cấp hàm `init`:

```js
async function init(sdk) {
  sdk.console.log("plugin started");
}
```

Ogma gọi `init(sdk)` khi plugin được bật.

## Namespace chính {#core-namespaces}

| Namespace | Mục đích |
| --- | --- |
| `sdk.console` | Ghi thông điệp vào bộ đệm nhật ký của plugin. |
| `sdk.meta` | Đọc siêu dữ liệu và đường dẫn dữ liệu của plugin. |
| `sdk.events` | Đăng ký callback cho các sự kiện Ogma. |
| `sdk.requests` | Truy vấn lịch sử HTTP và dữ liệu yêu cầu. |
| `sdk.findings` | Truy vấn hoặc tạo phát hiện khi quyền cho phép. |
| `sdk.scope` | Đọc thông tin phạm vi đang hoạt động. |
| `sdk.storage` | Lưu bền vững trạng thái plugin dưới dạng khóa/giá trị. |
| `sdk.fs` | Thao tác tệp trong thư mục dữ liệu riêng của plugin. |
| `sdk.path` | Hàm hỗ trợ tạo đường dẫn trong thư mục dữ liệu plugin. |
| `sdk.api` | Cung cấp hàm xử lý backend cho frontend của plugin. |

## Ghi nhật ký {#logging}

```js
sdk.console.log("message")
sdk.console.warn("warning")
sdk.console.error("error")
```

Thông điệp xuất hiện trong giao diện nhật ký của plugin. Giữ nhật ký ngắn gọn và tránh ghi dữ liệu bí mật.

## Siêu dữ liệu {#metadata}

```js
sdk.meta.id()
sdk.meta.packageId()
sdk.meta.version()
sdk.meta.path()
```

Dùng `sdk.meta.path()` cho dữ liệu riêng của plugin. Không mặc định rằng mã plugin chạy trong sandbox có thể truy cập đường dẫn bất kỳ trong hệ thống tệp.

```js
sdk.storage.set("key", "value")
sdk.storage.get("key")
sdk.storage.keys()
sdk.storage.delete("key")
sdk.storage.clear()
```

```js
sdk.fs.readFile("relative/file.txt")
sdk.fs.writeFile("relative/file.txt", "text")
sdk.fs.appendFile("relative/file.txt", "more")
sdk.fs.exists("relative/file.txt")
sdk.fs.existsSync("relative/file.txt")
sdk.fs.mkdir("relative/dir")
sdk.path.join("a", "b", "c")
```

## Sự kiện {#events}

```js
sdk.events.onInterceptRequest(function(req) {
  return req
})

sdk.events.onInterceptResponse(function(req, res) {
  sdk.console.log(res.getCode())
})

sdk.events.onProjectChange(function() {
  sdk.console.log("project changed")
})
```

Callback cần chạy nhanh. Công việc kéo dài nên được thực hiện thông qua thao tác rõ ràng của người dùng hoặc hàm xử lý API backend.

## Hàm xử lý cầu nối frontend {#frontend-bridge-handlers}

Plugin backend có thể cung cấp hàm xử lý cho các bảng frontend của plugin:

```js
sdk.api.register("ping", async function(input) {
  return { ok: true, input: input };
});
```

Frontend gọi hàm xử lý thông qua SDK frontend của Ogma. Xem [tài liệu tham khảo SDK frontend](./frontend-sdk.md).

## Yêu cầu bảo mật {#security-expectations}

* Coi lưu lượng HTTP, phát hiện, nhật ký và bản xuất là dữ liệu nhạy cảm.
* Chỉ yêu cầu các quyền plugin của bạn cần.
* Không bao giờ ghi thông tin đăng nhập, cookie, bearer token hoặc lưu lượng riêng tư vào nhật ký theo mặc định.
* Đảm bảo hoạt động của plugin rõ ràng và dễ hiểu đối với người dùng.