Riferimento dell’SDK backend per i plugin

Il codice dei plugin backend viene eseguito nella sandbox JavaScript di Ogma e riceve un oggetto sdk dall’applicazione principale.

Per il formato completo del pacchetto del plugin, i campi del manifesto, le autorizzazioni e gli esempi, inizia dalla guida al sistema di plugin.

Punto di ingresso

I plugin backend espongono una funzione init:

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

Ogma chiama init(sdk) quando il plugin viene abilitato.

Namespace principali

Namespace	Funzione
sdk.console	Scrivere messaggi nel buffer dei log del plugin.
sdk.meta	Leggere metadati e percorsi dei dati del plugin.
sdk.events	Registrare callback per gli eventi Ogma.
sdk.requests	Consultare la cronologia HTTP e i dati delle richieste.
sdk.findings	Consultare o creare rilievi di sicurezza quando le autorizzazioni lo consentono.
sdk.scope	Leggere le informazioni sull’ambito attivo.
sdk.storage	Persistenza chiave/valore per lo stato del plugin.
sdk.fs	Operazioni sui file nella directory privata dei dati del plugin.
sdk.path	Funzioni di supporto per comporre percorsi nella directory dei dati del plugin.
sdk.api	Esporre i gestori backend al frontend del plugin.

Log

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

I messaggi sono visibili nell’interfaccia dei log del plugin. Mantieni i log concisi ed evita di scrivere segreti.

Metadati

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

Usa sdk.meta.path() per i dati specifici del plugin. Non dare per scontato che il codice del plugin eseguito in sandbox possa accedere a percorsi arbitrari del file system.

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

Eventi

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

I callback devono essere rapidi. Le attività di lunga durata devono essere eseguite tramite azioni esplicite dell’utente o gestori dell’API backend.

Gestori del bridge con il frontend

I plugin backend possono esporre gestori per i pannelli frontend dei plugin:

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

Il frontend chiama il gestore tramite l’SDK frontend di Ogma. Consulta il riferimento dell’SDK frontend.

Requisiti di sicurezza

• Tratta traffico HTTP, rilievi di sicurezza, log ed esportazioni come dati sensibili.
• Richiedi solo le autorizzazioni necessarie al tuo plugin.
• Non registrare mai credenziali, cookie, bearer token o traffico privato per impostazione predefinita.
• Mantieni il comportamento del plugin esplicito e comprensibile per l’utente.