---
url: https://docs.ogmabox.com/ar/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 أو حركة البيانات الخاصة افتراضيًا.
* اجعل سلوك الإضافة صريحًا ومفهومًا للمستخدم.