مرجع SDK بک‌اند افزونه‌ها

کد افزونهٔ بک‌اند در محیط ایزولهٔ JavaScript در Ogma اجرا می‌شود و یک شیء sdk از برنامهٔ میزبان دریافت می‌کند.

برای قالب کامل بستهٔ افزونه، فیلدهای مانیفست، مجوزها و نمونه‌ها، از راهنمای نظام افزونه‌ها شروع کنید.

نقطهٔ ورود

افزونه‌های بک‌اند یک تابع init ارائه می‌کنند:

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

Ogma هنگام فعال‌سازی افزونه، init(sdk) را فراخوانی می‌کند.

فضاهای نام اصلی

فضای نام	کاربرد
sdk.console	نوشتن پیام در بافر گزارش رویدادهای افزونه.
sdk.meta	خواندن فرادادهٔ افزونه و مسیرهای داده.
sdk.events	ثبت توابع فراخوانی برگشتی برای رویدادهای Ogma.
sdk.requests	جست‌وجو در تاریخچهٔ HTTP و داده‌های درخواست.
sdk.findings	جست‌وجو یا ایجاد یافته‌ها در صورت اجازهٔ مجوزها.
sdk.scope	خواندن اطلاعات محدودهٔ آزمون فعال.
sdk.storage	ذخیره‌سازی پایدار کلید/مقدار برای وضعیت افزونه.
sdk.fs	عملیات فایل در پوشهٔ خصوصی داده‌های افزونه.
sdk.path	ابزارهای کمکی مسیر برای ساخت مسیرها در پوشهٔ داده‌های افزونه.
sdk.api	در اختیار گذاشتن پردازشگرهای بک‌اند برای فرانت‌اند افزونه.

ثبت رویدادها

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

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

فراداده

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

از sdk.meta.path() برای داده‌های مختص افزونه استفاده کنید. فرض نکنید کد افزونهٔ ایزوله به مسیرهای دلخواه سیستم فایل دسترسی دارد.

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

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

رویدادها

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 بک‌اند منتقل کنید.

پردازشگرهای پل فرانت‌اند

افزونه‌های بک‌اند می‌توانند پردازشگرهایی برای پنل‌های فرانت‌اند افزونه ارائه کنند:

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

فرانت‌اند پردازشگر را از طریق SDK فرانت‌اند Ogma فراخوانی می‌کند. به مرجع SDK فرانت‌اند مراجعه کنید.

انتظارات امنیتی

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