カスタムプラグインの作成
カスタムプラグインの作成
カスタムのAPIルートやバックグラウンド処理が必要な場合は、AppKit pluginを実装します。最も手軽なのはCLIを使う方法です。
# 対話モード
npx @databricks/appkit plugin create
# 非対話モード
npx @databricks/appkit plugin create --placement in-repo --path plugins/my-plugin --name my-plugin --description "My plugin" --forcepluginの構造をさらに深く理解したい場合は、このまま読み進めてください。
基本的な plugin の例
マニフェストを JSON として記述してインポートし、static manifest で Plugin のサブクラスに紐付けます。エクスポートには toPlugin() を使用します。
// my-plugin/manifest.json
{
"$schema": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
"name": "my-plugin",
"displayName": "My Plugin",
"description": "A custom plugin",
"resources": {
"required": [
{
"type": "secret",
"alias": "apiKey",
"resourceKey": "api-key",
"description": "API key for external service",
"permission": "READ",
"fields": {
"scope": { "env": "MY_SECRET_SCOPE", "description": "Secret scope" },
"key": { "env": "MY_API_KEY", "description": "Secret key name" }
}
}
],
"optional": []
}
}// my-plugin/index.ts
import { Plugin, toPlugin, type PluginManifest } from "@databricks/appkit";
import manifest from "./manifest.json";
class MyPlugin extends Plugin {
static manifest = manifest as PluginManifest<"my-plugin">;
async setup() {
// pluginを初期化
}
myCustomMethod() {
// 何らかの実装
}
async shutdown() {
// リソースをクリーンアップ
}
exports() {
return {
myCustomMethod: this.myCustomMethod
}
}
}
export const myPlugin = toPlugin(MyPlugin);JSON が正式なオーサリング形式です。appkit plugin sync が templates 向けにマニフェストを集約する際に読み取るのも、この JSON です。v2.0 マニフェスト仕様の全体 (リソース、ディスカバリー記述子、スキャフォールディングルール) については、pluginマニフェストを参照してください。
設定に依存するリソース
マニフェストでは、リソースを required (常に必要) または optional (必要になる場合がある) のいずれかとして定義します。
plugin の設定によって必須になるリソースについては、静的メソッド
getResourceRequirements(config) を実装します。
interface MyPluginConfig extends BasePluginConfig {
enableCaching?: boolean;
}
class MyPlugin extends Plugin<MyPluginConfig> {
static manifest = {
name: "myPlugin",
displayName: "My Plugin",
description: "A plugin with optional caching",
resources: {
required: [
{ type: "sql_warehouse", alias: "warehouse", resourceKey: "sqlWarehouse", description: "Query execution", permission: "CAN_USE", fields: { id: { env: "DATABRICKS_WAREHOUSE_ID" } } }
],
optional: [
// 静的解析用にマニフェストでは optional として記載
{ type: "database", alias: "cache", resourceKey: "cache", description: "Query result caching (if enabled)", permission: "CAN_CONNECT_AND_CREATE", fields: { instance_name: { env: "DATABRICKS_CACHE_INSTANCE" }, database_name: { env: "DATABRICKS_CACHE_DB" } } }
]
}
} satisfies PluginManifest<"myPlugin">;
// 実行時: 設定に応じて optional なリソースを required に変換
static getResourceRequirements(config: MyPluginConfig) {
const resources = [];
if (config.enableCaching) {
// キャッシュが有効な場合は Database が必須になる
resources.push({
type: "database",
alias: "cache",
resourceKey: "cache",
description: "Query result caching",
permission: "CAN_CONNECT_AND_CREATE",
fields: {
instance_name: { env: "DATABRICKS_CACHE_INSTANCE" },
database_name: { env: "DATABRICKS_CACHE_DB" },
},
required: true // 実行時に必須としてマーク
});
}
return resources;
}
}このパターンにより、次のことが可能になります。
- 静的ツール (CLI、ドキュメント) で、利用可能なすべてのリソースを表示する
- 実行時の検証で、実際の設定に基づいてリソースを適用する
主要な拡張ポイント
- ルートの注入:
injectRoutes()を実装し、IAppRouterを使ってカスタム endpoint を追加します - ライフサイクルフック:
setup()およびshutdown()メソッドをオーバーライドします - 共有 services:
- キャッシュ管理:
this.cache経由でキャッシュ service にアクセスします。設定についてはCacheConfigを参照してください。 - テレメトリ:
this.telemetryを使って、トレースとメトリクスで plugin を計測します。ITelemetryを参照してください。
- キャッシュ管理:
- 実行インターセプター:
execute()とexecuteStream()をStreamExecutionSettingsと組み合わせて使用すると、キャッシュ、リトライ、タイムアウト、テレメトリスパン属性 (execution.context、caller.id) が自動的に適用されます
plugin をプログラムから利用する
必要に応じて、AppKit オブジェクトを介して plugin をプログラムから利用できるようにすることもできます。
その場合は、plugin に exports メソッドを実装し、公開したいメソッドを持つオブジェクトを返します。前述の例であれば、plugin は次のように利用できます。
const AppKit = await createApp({
plugins: [
server({ port: 8000 }),
analytics(),
myPlugin(),
],
});
AppKit.myPlugin.myCustomMethod();詳細なドキュメントについては、Plugin API リファレンスを参照してください。