---
url: https://docs.ogmabox.com/fa/plugins/backend-sdk.md
description: >-
  مرجع APIهای افزونهٔ بک‌اند Ogma، اجرای ایزوله، مسیرهای ذخیره‌سازی، دسترسی به
  تاریخچهٔ HTTP، یافته‌ها، فرمان‌ها و یکپارچه‌سازی با میزبان.
---

# مرجع SDK بک‌اند افزونه‌ها {#plugin-backend-sdk-reference}

کد افزونهٔ بک‌اند در محیط ایزولهٔ JavaScript در Ogma اجرا می‌شود و یک شیء `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")
```

پیام‌ها در رابط گزارش رویدادهای افزونه دیده می‌شوند. گزارش‌ها را مختصر نگه دارید و از نوشتن اطلاعات محرمانه خودداری کنید.

## فراداده {#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 };
});
```

فرانت‌اند پردازشگر را از طریق SDK فرانت‌اند Ogma فراخوانی می‌کند. به [مرجع SDK فرانت‌اند](./frontend-sdk.md) مراجعه کنید.

## انتظارات امنیتی {#security-expectations}

* ترافیک HTTP، یافته‌ها، گزارش رویدادها و خروجی‌ها را حساس در نظر بگیرید.
* فقط مجوزهای مورد نیاز افزونهٔ خود را درخواست کنید.
* به‌طور پیش‌فرض هرگز اطلاعات احراز هویت، کوکی‌ها، توکن‌های Bearer یا ترافیک خصوصی را ثبت نکنید.
* رفتار افزونه را برای کاربر صریح و قابل فهم نگه دارید.