מדריך העזר ל-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 או תעבורה פרטית.
• הקפידו שהתנהגות התוסף תהיה מפורשת ומובנת למשתמש.