---
url: https://docs.ogmabox.com/ja/plugins/frontend-sdk.md
description: Ogma フロントエンドプラグイン API のリファレンス。iframe 統合、ブリッジ呼び出し、UI パネル、コマンド、ホストとの通信を説明します。
---

# プラグインフロントエンド SDK リファレンス {#plugin-frontend-sdk-reference}

プラグインのフロントエンドコードは、サンドボックス化された iframe 内で実行されます。このドキュメントは低レベルのリファレンスです。概要については [README.md](./README.md) をご覧ください。

***

## セキュリティモデル {#security-model}

| 項目 | 値 |
|----------|-------|
| iframe サンドボックス | `allow-scripts` のみ（`allow-same-origin` なし） |
| CSP `script-src` | nonce による制限。エントリポイントのスクリプトのみを読み込みます |
| CSP `connect-src` | `'self'`：プラグインは `/plugins/{id}/api/*` に POST し、`/plugins/{id}/events/poll` をポーリングできます |
| CSP `default-src` | `'none'` |
| 親 DOM へのアクセス | ブロック（`allow-same-origin` なし） |
| Ogma セッション Cookie | プラグインからはアクセス不可 |
| プラグイン間の通信 | 利用不可 |

データブリッジの呼び出しは、リクエストごとにサーバー側で認可されます。表示やナビゲーション操作はホスト UI が処理します。権限タブに表示される権限キャッシュは表示専用で、データアクセスの制御には使用されません。

***

## ブリッジプロトコル {#bridge-protocol}

プラグインの JS は `postMessage` で Ogma ホストと通信します。ホスト側の処理は `PluginsView.vue` にあり、`bridge_request` メッセージを扱います。

### リクエストエンベロープ {#request-envelope}

```ts
interface BridgeRequest {
  type: 'bridge_request'
  sessionId: string     // nonce assigned when the bridge is set up; prevents stale messages
  requestId: string     // caller-generated correlation id (max 128 chars)
  command: string       // e.g. "ogma.requests.get"
  payload?: unknown     // command-specific input
}
```

メッセージ全体のサイズ上限：65 536 バイト。

### レスポンスエンベロープ {#response-envelope}

```ts
interface BridgeResponse {
  type: 'bridge_response'
  requestId: string
  ok: boolean
  result?: unknown
  error?: string
  code?: string
}
```

### SDK の使用（推奨） {#using-the-sdk-recommended}

生の `postMessage` ブリッジリクエストを手動で送信しないでください。グローバルの `ogmaSDK` を使用します。

```js
ogmaSDK.ready(function(sdk) {
  sdk.meta.get().then(function(meta) {
    sdk.log.info("running as " + meta.pluginId);
  });
});
```

SDK はすべてのブリッジ通信をラップし、リクエストの対応付け、sessionId の管理、Promise の解決を処理します。

***

## コマンドリファレンス {#command-reference}

### `ogma.meta.get` {#ogma-meta-get}

ペイロードは不要です。

`{ pluginId, packageId, name, version, ogmaVersion }` を返します。

### `ogma.requests.get` {#ogma-requests-get}

ペイロード：`{ id: string }`

必要なフィールドを抽出した HTTP エントリを返します。フィールド：`id`、`method`、`host`、`port`、`path`、`query`、`req_len`、`resp_status`、`resp_len`、`roundtrip_ms`、`created_at`。この抽出結果にはヘッダーやボディのバイト列は含まれません。

必要な権限：`read_http_history`（自動付与）。

### `ogma.requests.getRaw` {#ogma-requests-getraw}

ペイロード：`{ id: string }`。`sdk.requests.getRaw(id)` で呼び出します。

`requestBodyBase64`、`responseBodyBase64`、デコード後の長さ（`requestBodyLength`、`responseBodyLength`）、`requestBodyTruncated`、`responseBodyTruncated`、`maxBodyBytes` を返します。名前に Raw が含まれますが、返すのはボディのバイト列であり、生の HTTP メッセージ全体ではありません。サポートされるコンテンツエンコーディングは、抽出前にデコードされます。各ボディの上限は 256 KiB です。完全なアセットとして処理する前に、切り詰めフラグを確認してください。

必要な権限：`read_http_history`（自動付与）。

### `ogma.requests.search` {#ogma-requests-search}

ペイロード：`{ limit?: number, offset?: number, query?: string }`

`query` は HTTPQL のフィルター式に対応しています。`limit` の上限：20。`{ items: [...], total: number, limit: number, offset: number }` を返します。

必要な権限：`read_http_history`（自動付与）。

### `ogma.findings.list` {#ogma-findings-list}

ペイロード：`{ limit?: number, offset?: number }`

`{ items: [...], total: number, limit: number, offset: number }` を返し、各ページには最大 20 件の指摘事項が含まれます。項目は概要であり、フィールドには `id`、`title`、`severity`、`status`、`reporter`、`tags`、`created_at` が含まれます。

必要な権限：`read_findings`（自動付与）。

### `ogma.scope.getActive` {#ogma-scope-getactive}

ペイロードはありません。現在有効な診断対象範囲のプリセット、または `null` を返します。

必要な権限：`read_scope`（自動付与）。

### `ogma.projects.getCurrent` {#ogma-projects-getcurrent}

ペイロードはありません。`{ id, name, status }` または `null` を返します。

必要な権限：`read_projects`（自動付与）。

### `ogma.log` {#ogma-log}

ペイロード：`{ message: string }`

プラグインのログバッファーに書き込みます。

### `ogma.ui.resize` {#ogma-ui-resize}

ペイロード：`{ height: number }`（最大 2000）

iframe の高さを設定するようホストに要求します。

### `ogma.ui.sidebar.registerItem` {#ogma-ui-sidebar-registeritem}

ペイロード：`{ name: string, path: string }`（name は最大 64 文字、path は最大 256 文字）

プラグインパネル内のナビゲーションを登録します。プラグインあたり最大 20 項目です。対応するページの内容は `sdk.navigation.addPage(path, { title, body })` で登録します。項目を選択すると iframe 内にそのページが表示され、Ogma ワークスペースの新しいトップレベルルートにはなりません。

### `ogma.backend.call` {#ogma-backend-call}

ペイロード：`{ method: string, args: unknown[] }`

`sdk.api.register(method, fn)` で登録したバックエンド RPC ハンドラーを呼び出します。メソッド名は最大 64 文字です。

バックエンドハンドラーの戻り値を JSON にシリアライズして返します。

### `ogma.backend.onEvent` {#ogma-backend-onevent}

ペイロード：不要です。

受け付けの確認のみを行います。実際のイベント取得には `ogma.events.poll` を使用してください。

### `ogma.events.poll` {#ogma-events-poll}

ペイロード：`{ since: number }`（前回のポーリングからのインデックス。0 から開始）

`{ events: [{ event: string, args: unknown[] }], next_since: number }` を返します。

### `ogma.navigation.addPage` {#ogma-navigation-addpage}

ペイロード：`{ path: string, title?: string }`

ブリッジはページパスの受け付けを確認します。注入された SDK は、`sdk.navigation.addPage(path, options)` のオプションとして `{ body: HTMLElement }` も受け付けます。ボディを iframe 内に追加し、ホストが対応するサイドバー項目を選択すると、ページの表示を切り替えます。DOM ノードはローカルに留まり、ブリッジ経由でシリアライズされることはありません。

### `ogma.window.showToast` {#ogma-window-showtoast}

ペイロード：`{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }`

プラグインパネルにトーストを表示します。表示時間の単位はミリ秒です（最大 10000、既定値 3000）。

### `ogma.commands.register` {#ogma-commands-register}

ペイロード：`{ id: string, name: string }`

ホストのコマンドストアにプラグインコマンドを登録します。ホストが実行すると、`commandId` とコンテキストを含む `plugin_command` メッセージが iframe に返されます。プラグインは対応するコールバックを提供する必要があります。登録だけではコマンドは実行されません。

### `ogma.menu.registerItem` {#ogma-menu-registeritem}

ペイロード：`{ type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }`

プラグインコマンドに関連付けたコンテキストメニュー項目を登録します。先にコマンドを登録してください。ラベルには、既定でコマンドの登録名、次いで ID を使用します。`type` を省略すると `Request` になります。ホストブリッジは `leadingIcon` を使用しません。

### テーマヘルパー {#theme-helpers}

注入された SDK は `sdk.theme.get()` と `sdk.theme.onChange(callback)` も提供します。これらは別のデータブリッジコマンドを使用せずに、iframe のテーマを読み取り、ホストのテーマ更新を購読します。プラグイン UI を Ogma のライト/ダーク表示に合わせるために使用してください。

***

## エラーコード {#error-codes}

| コード | 意味 |
|------|---------|
| `PERMISSION_DENIED` | プラグインに必要な権限がありません。 |
| `PLUGIN_DISABLED` | プラグインが現在有効になっていません。 |
| `UNKNOWN_COMMAND` | コマンドがサポート対象の一覧にありません。 |
| `INVALID_PAYLOAD` | 必須のペイロードフィールドがないか、型が間違っています。 |
| `NOT_FOUND` | 要求されたリソースが存在しません。 |
| `LIMIT_EXCEEDED` | プラグインごとの件数制限に達しました（例：サイドバー項目）。 |
| `SERVER_ERROR` | 内部エラーです。プラグインのログを確認してください。 |

***

## サポートされるコマンド一覧 {#supported-commands-list}

`ogma.meta.get`, `ogma.log`, `ogma.ui.resize`, `ogma.ui.sidebar.registerItem`, `ogma.requests.get`, `ogma.requests.getRaw`, `ogma.requests.search`, `ogma.findings.list`, `ogma.scope.getActive`, `ogma.projects.getCurrent`, `ogma.backend.call`, `ogma.backend.onEvent`, `ogma.events.poll`, `ogma.navigation.addPage`, `ogma.window.showToast`, `ogma.commands.register`, `ogma.menu.registerItem`.