---
url: https://docs.ogmabox.com/zh-Hant/plugins/backend-sdk.md
description: Ogma 後端外掛 API 參考，涵蓋沙箱執行、儲存路徑、HTTP 歷程記錄存取、檢測發現、命令及主應用程式整合。
---

# 外掛後端 SDK 參考 {#plugin-backend-sdk-reference}

後端外掛程式碼在 Ogma 的 JavaScript 沙箱內執行，並從主應用程式接收 `sdk` 物件。

完整外掛套件格式、資訊清單欄位、權限及範例，請先參閱[外掛系統指南](./README.md)。

## 進入點 {#entry-point}

後端外掛提供 `init` 函式：

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

啟用外掛時，Ogma 會呼叫 `init(sdk)`。

## 核心命名空間 {#core-namespaces}

| 命名空間 | 用途 |
| --- | --- |
| `sdk.console` | 將訊息寫入外掛記錄緩衝區。 |
| `sdk.meta` | 讀取外掛中繼資料及資料路徑。 |
| `sdk.events` | 為 Ogma 事件註冊回呼。 |
| `sdk.requests` | 查詢 HTTP 歷程記錄及請求資料。 |
| `sdk.findings` | 在權限允許時查詢或建立檢測發現。 |
| `sdk.scope` | 讀取目前測試範圍資訊。 |
| `sdk.storage` | 以索引鍵/值方式持久儲存外掛狀態。 |
| `sdk.fs` | 在外掛私有資料目錄內操作檔案。 |
| `sdk.path` | 用於組合外掛資料目錄內路徑的輔助函式。 |
| `sdk.api` | 向外掛前端提供後端處理函式。 |

## 記錄 {#logging}

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

訊息會顯示在外掛記錄 UI 中。請保持記錄簡潔，避免寫入機密資訊。

## 中繼資料 {#metadata}

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

使用 `sdk.meta.path()` 儲存外掛專屬資料。不要假設沙箱中的外掛程式碼可以存取任意檔案系統路徑。

```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")
```

## 事件 {#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")
})
```

回呼應快速完成。耗時較長的工作應改由明確的使用者操作或後端 API 處理函式觸發。

## 前端橋接處理函式 {#frontend-bridge-handlers}

後端外掛可向前端外掛面板提供處理函式：

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

前端會透過 Ogma 前端 SDK 呼叫處理函式。參閱[前端 SDK 參考](./frontend-sdk.md)。

## 安全要求 {#security-expectations}

* 將 HTTP 流量、檢測發現、記錄及匯出內容視為敏感資料。
* 只申請外掛所需的權限。
* 預設情況下，絕不記錄認證資訊、Cookie、Bearer 權杖或私有流量。
* 讓外掛行為明確，且容易讓使用者理解。