プラグインバックエンド SDK リファレンス

バックエンドプラグインのコードは Ogma の JavaScript サンドボックスで実行され、ホストアプリケーションから 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")

メッセージはプラグインのログ UI に表示されます。ログは簡潔にし、機密情報を書き込まないでください。

メタデータ

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

フロントエンドは Ogma フロントエンド SDK を通じてハンドラーを呼び出します。フロントエンド SDK リファレンスをご覧ください。

セキュリティ上の要件

• HTTP 通信、指摘事項、ログ、エクスポートを機密データとして扱ってください。
• プラグインに必要な権限のみを要求してください。
• 既定では、認証情報、Cookie、Bearer トークン、非公開の通信を決してログに記録しないでください。
• プラグインの動作を明示的にし、ユーザーが理解できるようにしてください。