API 路由

外掛可以為其管理 UI 和外部整合暴露 API 路由。路由掛載在 /_emdash/api/plugins/<slug>/<路由名> 下，並在沙盒執行時期中執行，使用與鉤子相同的 PluginContext。

本頁介紹沙盒外掛。原生外掛的 API 表面相同，唯一區別是處理函式簽名 — 參見原生外掛。

定義路由

沙盒路由處理函式接受兩個參數：(routeCtx, ctx)。

過濾索引內容欄位

路由 URL

認證和 CSRF

外掛路由預設需要認證。 公開路由使用 public: true。

已認證的呼叫者

在私有路由中，routeCtx.user 是已認證的使用者。

將路由暴露為 MCP 工具

輸入驗證

input 接受 Zod 模式。

回傳值

回傳任何 JSON 可序列化的值。

錯誤

拋出錯誤以回傳錯誤回應。

HTTP 方法

路由回應所有方法。在 routeCtx.request.method 上進行分支。

常見模式

透過 KV 管理設定

分頁清單

外部 API 代理

從管理 UI 呼叫路由

import { usePluginAPI } from "@emdash-cms/admin";

從佇列和排程處理函式呼叫路由

使用 emdash/middleware 中的 withEmDashRuntime()。

從外部呼叫路由

公開路由可以直接呼叫。私有路由需要工作階段憑證或 API 權杖。

路由上下文參考

interface SandboxedRouteContext {
	input: unknown;
	request: SandboxedRequest;
	requestMeta?: unknown;
	user?: UserInfo;
}

interface PluginContext {
	plugin: { id: string; version: string };
	storage: PluginStorage;
	kv: KVAccess;
	log: LogAccess;
	site: SiteInfo;
	content?: ContentAccess;
	taxonomies?: TaxonomyAccess;
	media?: MediaAccess;
	http?: HttpAccess;
	users?: UserAccess;
	email?: EmailAccess;
}