مرجع 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 أو حركة البيانات الخاصة افتراضيًا.
• اجعل سلوك الإضافة صريحًا ومفهومًا للمستخدم.