アプリ開発

このページは、Databricks Apps と AppKit の CLI およびワークフローのリファレンスです。プラグインの追加、scaffold、デプロイ、管理、トラブルシューティングまでを解説します。

以下の各コマンドでは、代表的な実行例、利用可能なフラグの一覧、および各フラグの説明表を示します。CLI が信頼できる情報源であるため、フラグの最新の挙動は databricks <command> --help を実行して確認してください。

ローカルセットアップ

npm run dev を実行する前に、.env.example を .env にコピーし、ワークスペースの URL とリソース ID を記入してください。AppKit はこれらの値を読み取り、Databricks リソースへのローカル接続に使用します。

Lakebase Postgres を使用するアプリの .env の例:

DATABRICKS_HOST=https://<workspace>.cloud.databricks.com
LAKEBASE_ENDPOINT=projects/<project>/branches/production/endpoints/primary

アプリが Lakebase を使用している場合は、ローカルで実行する前にローカルユーザーにも databricks_superuser ロールを付与してください。スキーマとテーブルは初回デプロイ時にアプリのサービスプリンシパルが作成し、その所有者になります。このロールを付与しないと、ローカルの ID ではこれらのオブジェクトにアクセスできません。

GRANT databricks_superuser TO "<your-email>";

ローカルアクセスのワークフロー全体については、Lakebase 開発を参照してください。

再デプロイせずに本番データに対してテストする方法については、リモートブリッジを参照してください。

プラグインを追加する

既存のアプリにプラグインを追加するには、server/server.ts の createApp でプラグインをインポートして登録します。

import { createApp, genie, lakebase, server } from "@databricks/appkit";

const AppKit = await createApp({
  plugins: [server(), lakebase(), genie()],
});

次に、更新されたリソース要件を反映して appkit.plugins.json を再生成します。

npx @databricks/appkit plugin sync --write

これは npm run dev および npm run build の実行時に自動的に行われます。更新された appkit.plugins.json はコードと一緒にコミットしてください。このファイルによって、デプロイパイプラインはどのリソースをプロビジョニングするかを判断します。

各プラグインの設定オプションについては AppKit プラグインリファレンス を、独自のプラグインを追加する方法については カスタムプラグインの作成 を参照してください。

プラグインを探す

利用可能なプラグインと、それぞれに必要なリソースフィールドを一覧表示します。

databricks apps manifest

Scaffold オプション

新しい AppKit プロジェクトを scaffold するには、databricks apps init を使用します。最短の手順については Apps クイックスタート を参照してください。非対話的な scaffold や高度な scaffold を行う場合は、以下のオプションを使用します。

databricks apps init --name my-app

--name を指定するとプロンプトは表示されず、指定しなかったオプションにはデフォルト値が使われます。アプリ名は小文字とハイフンのみで、26 文字以内にする必要があります。利用可能なプラグインとその --set キーを確認するには databricks apps manifest を実行してください。

環境設定

ローカル (npm run dev) : プロジェクトルートの .env で定義した変数が使われます。

デプロイ時: app.yaml の env エントリで定義した変数が使われます。単純な文字列には value、リソースバインディングには valueFrom を指定します:

env:
  - name: LAKEBASE_ENDPOINT
    valueFrom: postgres
  - name: WAREHOUSE_ID
    valueFrom: sql-warehouse
  - name: APP_LOG_LEVEL
    value: info

valueFrom で参照するリソースは databricks.yml で宣言する必要があります。リソースの一覧については 設定 を参照してください。

デプロイ前チェックリスト

本番環境へデプロイする前に、以下を確認してください。

• アプリが DATABRICKS_APP_PORT の 0.0.0.0 にバインドしている
• app.yaml の command が配列構文になっている（シェル文字列ではない）
• プロジェクト内に 10 MB を超えるファイルがない
• シークレットに valueFrom を使用している（value は使わない）
• databricks.yml に必要なリソースがすべて宣言されている
• databricks apps validate が成功する（--skip-tests を指定するとテストをスキップして実行を短縮できます）
• ローカルで npm run build が成功する

検証

デプロイ前に、アプリのプロジェクトディレクトリから検証を実行します。

databricks apps validate --profile $DATABRICKS_PROFILE

検証ではビルド、型チェック、リントを実行します。実行時間を短縮するには --skip-tests を指定してください。

デプロイ

databricks apps deploy

CLI は設定を検証し、プロジェクトをビルドしてアップロードしたうえでアプリを起動します。既定では databricks apps validate と同じプロジェクト検証 (ビルド、型チェック、lint) を実行します。この手順をスキップするには --skip-validation を指定してください。scaffold した AppKit プロジェクトからデプロイする場合、--source-code-path の指定は不要です。

デプロイを確認する

アプリが正常にデプロイされたことを確認します。

databricks apps get my-app -o json

{
  "name": "my-app",
  "url": "https://my-app-1234567890.us-west-2.databricksapps.com",
  "description": "A Databricks App powered by AppKit",
  "compute_size": "MEDIUM",
  "app_status": {
    "message": "App has status: App is running",
    "state": "RUNNING"
  },
  "compute_status": {
    "message": "App compute is running.",
    "state": "ACTIVE"
  },
  "active_deployment": {
    "deployment_id": "a1b2c3d4e5f6",
    "source_code_path": "/Workspace/Users/you@example.com/.bundle/my-app/default/files",
    "status": {
      "message": "App started successfully",
      "state": "SUCCEEDED"
    }
  },
  "resources": [
    {
      "name": "postgres",
      "postgres": {
        "branch": "projects/my-project/branches/production",
        "database": "projects/my-project/branches/production/databases/db-abc123",
        "permission": "CAN_CONNECT_AND_CREATE"
      }
    }
  ],
  "service_principal_client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

ログの確認:

databricks apps logs my-app

[SYSTEM] [INFO] Starting Databricks Apps runtime...
[SYSTEM] [INFO] Starting deployment a1b2c3d4e5f6...
[SYSTEM] [INFO] Downloading source code from /Workspace/Users/.../src/a1b2c3d4e5f6
[SYSTEM] [INFO] Installing dependencies...
[BUILD] added 899 packages, and audited 900 packages in 21s
[SYSTEM] [INFO] Dependencies installed successfully.
[SYSTEM] [INFO] Running build script npm run build:server && npm run build:client
[BUILD] ✔ Build complete in 30ms
[BUILD] ✓ built in 2.80s
[SYSTEM] [INFO] Build completed successfully.
[SYSTEM] [INFO] Starting app with command: [npm run start]
[APP] [appkit:lakebase] Lakebase pool initialized
[APP] [appkit:server] Server running on http://0.0.0.0:8000
[APP] [appkit:server] Mode: production (static)

アプリの管理

databricks apps stop my-app
databricks apps start my-app
databricks apps delete my-app

apps stop のオプション

apps start オプション

apps delete のオプション

apps delete は確認プロンプトを表示します。CI では --auto-approve を指定してプロンプトをスキップしてください。

CI/CD

CI で自動デプロイを行う場合は、DATABRICKS_HOST と DATABRICKS_TOKEN を設定します (または DATABRICKS_CLIENT_ID と DATABRICKS_CLIENT_SECRET を使って OAuth を利用します) :

DATABRICKS_HOST=https://<workspace>.cloud.databricks.com \
DATABRICKS_TOKEN=dapi... \
databricks apps deploy

または、事前に構成済みのプロファイルを使用します。

databricks apps deploy --profile ci-profile

すべての認証方法については、Databricks CLI の認証ドキュメントを参照してください。

トラブルシューティング

その他のトラブルシューティングについては アプリのデプロイ を、ローカル接続の問題については AppKit リモートブリッジ を参照してください。

• アプリのデプロイに失敗する: ログのエラーメッセージを確認し、app.yaml の構文を検証したうえで、env セクションのシークレットや環境変数が正しく解決されるかを確認してください。依存関係がすべて含まれている、またはインストールされていることも確認します。
• 401 エラー（認証）: トークンが有効であること（databricks auth token --profile <PROFILE>）、有効期限が切れていないこと、必要な OAuth スコープが含まれていることを確認してください。トークンのスコープは、アプリのユーザー認可に設定されたスコープを包含している必要があります。
• 403 エラー（権限拒否）: アプリに対する CAN USE 権限があることを確認してください。権限が十分でも、OAuth スコープが不足していると 403 が発生することがあります。
• 404 エラー（アプリが見つからない）: アプリ名とワークスペース URL が正しいこと、アプリがデプロイされて実行中であること、エンドポイントのパスが存在することを確認してください。
• Git デプロイに失敗する: プライベートリポジトリの場合は、アプリのサービスプリンシパルに Git 資格情報が設定されているかを確認してください。CLI/API/DABs 経由でデプロイする場合は、先にアプリを作成してから Git 資格情報を追加します。

AppKit ドキュメント

AppKit の API リファレンス、コンポーネントドキュメント、プラグインドキュメントには、ターミナルからアクセスできます。

npx @databricks/appkit docs                        # ドキュメントの索引を表示
npx @databricks/appkit docs --full                 # すべてのAPIエントリを含む完全な索引
npx @databricks/appkit docs "<query-or-doc-path>"  # 特定のセクションまたはファイルを表示

引数なしで実行すると、インデックスを閲覧できます。AI コーディングアシスタントを使って開発する際に便利です。API の形式を推測させるのではなく、ここを参照させるか、本サイトの AppKit リファレンス を参照してください。

次のステップ

テンプレートカタログを見て開発を始めるか、アプリに機能を追加しましょう。永続ストレージには Lakebase Postgres、AI 機能には Agent Bricks を利用できます。