Databricks アプリの開発

備考

プレビュー

Databricks Apps は パブリック プレビュー段階です。

注記

Databricks ワークスペースでアプリをデプロイして実行するには、ファイアウォールがドメイン *.databricksapps.comをブロックしていないことを確認する必要があります。

この記事では、UI でAIアプリを作成および編集する方法、Databricks SQLウェアハウス、シークレット、Databricksジョブなどの プラットフォーム機能の使用方法、アプリ開発のベストDatabricks プラクティス、サポートされているフレームワークを使用してアプリを開発するための重要な情報など、Databricks Apps を使用してデータ アプリとAIアプリを作成する方法について詳しく説明します。

Databricks Apps UI でアプリを作成するにはどうすればよいですか?

1. サイドバーで「 新規 」をクリックし、メニューから「 アプリ 」を選択します。

2. 完全な事前構築済みのサンプル アプリから始めることも、ソース コードとアーティファクトを使用することもできます。

   • サンプル アプリから開始するには、 テンプレート を選択し、優先するフレームワークのタブをクリックして、アプリの一覧から選択します。
   • コードを使用してアプリを作成するには、 カスタム を選択します。

   

3. 「 次へ 」をクリックします。

4. アプリ名フィールドに 、アプリの名前を入力し、オプションで説明を入力します。

注記

• Databricks アプリに割り当てられた名前は、アプリの作成後に変更することはできず、Databricks ワークスペースにアクセスできるすべてのユーザーは、ワークスペース内のすべての Databricks アプリの名前とデプロイ履歴を確認できます。 さらに、アプリ名はシステムテーブルに書き込まれるレコードに含まれます。 この可視性のため、Databricks アプリに名前を付けるときに機密情報を含めないでください。

• 名前は、アプリをホストする Databricks ワークスペース内で一意である必要があり、小文字、数字、ハイフンのみを含める必要があります。

カスタム を選択した場合は、 アプリを作成 をクリックします。 テンプレート を選択した場合は、必要なリソースを構成し、 アプリの作成とデプロイ をクリックします。「 Databricks プラットフォーム機能を Databricks アプリに割り当てる」を参照してください。

アプリの詳細ページは、[ アプリの作成とデプロイ ] または [ アプリの作成 ] をクリックすると表示されます。 [テンプレート] を選択した場合、Databricks Apps はアプリを作成し、テンプレートのサンプル コードとアプリの必要な構成を含むアプリをデプロイします。アプリの詳細ページには、次の情報が表示されます。

• アプリの作成と展開のステータス。
• アプリのアーティファクトをローカル環境にコピーしたり、ローカルの変更を Databricks ワークスペースに同期したりするなど、アプリをローカルで開発を続行するために使用できる手順。

カスタム を選択した場合は、Databricks Apps によってアプリが作成されます。アプリのコードとアーティファクトを追加する必要があるため、アプリを別のステップとしてデプロイする必要があります。 アプリの詳細ページには、次の情報が表示されます。

• アプリの作成ステータス。
• アプリのコードとアーティファクトをローカル開発環境から Databricks ワークスペースに同期し、アプリをデプロイする手順。

ローカル開発環境を設定する方法、アプリのコードと構成をローカルで作成または更新する方法、アプリを Databricks ワークスペースに同期してデプロイする方法については、「 Databricks アプリの概要」を参照してください。 5. テンプレート を選択し、アプリのアーティファクトをワークスペースからローカル開発環境にコピーする場合は、次のDatabricks CLIを使用できます。

Bash

databricks workspace export-dir <workspace-path> <target-path>

以下のように置き換えてください。

• <workspace-path> は、アプリのコードとアーティファクトを含むワークスペースファイルディレクトリへのパスに置き換えます。
• <target-path> を、ファイルのコピー先となるローカル環境内のパスに置き換えます。

Databricks プラットフォーム機能を Databricks アプリに割り当てる

注記

Databricks SQLを使用するには、サービスプリンシパルはSQLウェアハウスとクエリによってアクセスされるテーブルへのアクセスが必要です。

Databricks SQL、Databricks Jobs、Mosaic AI Model Serving 、Databricks シークレットなどの Databricksプラットフォームの機能を使用するには、これらの機能をリソースとしてアプリに追加します。リソースは、アプリを作成 または編集するときに追加できます。

1. 新しいアプリの作成 または アプリの編集 カードで、 詳細設定 > + リソースの追加 をクリックし、リソースの種類を選択します。

   

2. リソースのタイプに応じて、リソースの設定に必要なフィールド ( リソースキー フィールドなど) を入力します。 このキーは、後でリソースを参照するために使用されます。

3. [ 保存 ]をクリックします。

4. SQLウェアハウス リソース キーを使用して、app.yaml 構成ファイルにリソースのエントリを追加します。これは実際の値ではなくパラメーター値のソースを参照しているため、valueの代わりに valueFrom を使用します。

   YAML

   env:
     - name: 'DATABRICKS_WAREHOUSE_ID'
       valueFrom: 'sql-warehouse'

5. アプリ コードでリソースを参照するには、 name フィールドの値 (この例ではDATABRICKS_WAREHOUSE_ID ) を使用して、構成されたキー値を参照します。

   Python

   import os
   
   os.getenv('DATABRICKS_WAREHOUSE_ID')

SQLウェアハウス エンドポイントやモデル サービング エンドポイントなど、アプリでリソースを使用するその他の例については、アプリ作成時のテンプレートの例とベスト プラクティス: シークレットを使用してDatabricksアプリの機密情報を格納する方法をご覧ください。

Databricks アプリの詳細を表示する

Databricks アプリの詳細ページを表示するには:

1. サイドバーの［ コンピュート ］をクリックします。
2. アプリ タブに移動します。
3. [ 名前 ] 列で、アプリ名をクリックします。
4. [ 概要 ] タブが表示され、アプリのステータス、デプロイ場所、関連リソースなど、アプリの詳細が表示されます。
   • アプリのデプロイ履歴にアクセスするには、[ デプロイ ] タブに移動します。
   • アプリのログを表示するには、[ ログ ] タブに移動します。
   • 環境変数やインストール済みパッケージなど、アプリのランタイム環境を表示するには、[ 環境 ] タブに移動します。

Databricks アプリのアクセス許可を構成する

アプリの権限を管理するには、 CAN MANAGE または IS OWNER の権限が必要です。アプリにアクセスするには、ユーザーはアプリに対する CAN_USE または CAN_MANAGE 権限を持っている必要があります。ユーザーがアプリに対して CAN_MANAGE 権限を必要としない限り、Databricks では CAN_USE 権限のみを割り当てることをお勧めします。

1. アプリの詳細ページで、 権限 をクリックします。
2. 権限設定 で、 ユーザー、グループ、またはサービスプリンシパルの選択 ドロップダウンメニューを選択し、ユーザー、グループ、サービスプリンシパル、またはすべてのワークスペースユーザーを選択します。
3. 権限のドロップダウンメニューから権限を選択します。
4. [ 追加 ] をクリックし、[ 保存 ] をクリックします。

Databricks Apps 承認モデルの使用

Databricks アプリの承認モデルでは、OAuth 2.0 プロトコルが使用され、アプリに割り当てられたアクセス許可と、アプリにアクセスするユーザーに割り当てられたアクセス許可が含まれます。アプリの権限は、アプリに割り当てられた Databricks サービスプリンシパルによって決定され、ユーザーの権限は、ログインしているワークスペース ユーザーに割り当てられたユーザー トークンによって決定されます。 このモデルでは、アプリがアクセスできるリソースと、アプリ ユーザーがアクセスできるリソースを制御および分離できます。

以下は、アプリとユーザーのアクセス許可の管理方法の概要です。

• アプリにアクセスするには、ユーザーはアプリに対するCAN_USEまたはCAN_MANAGE権限を持っている必要があります。アプリのアクセス許可 (アプリへのアクセスを含む) を管理するには、 CAN MANAGE または IS OWNER のアクセス許可が必要です。アプリへのアクセス許可の割り当ての詳細については、Databricks アプリのアクセス許可を構成するを参照してください。

• アプリが作成されると、 Databricks Apps によって Databricks サービスプリンシパルが自動的に作成され、そのサービスプリンシパルがアプリに割り当てられます。 アプリのサービスプリンシパルは一意であり、そのアプリにのみ関連付けられます。 サービスプリンシパルは、アプリが作成され、 SQLウェアハウス、モデルサービング エンドポイント、 Unity Catalog内のセキュリティ保護可能なオブジェクトなど、ワークスペース内のリソースへのアクセスを認証および承認するために使用されるワークスペースにのみアクセスできます。

  サービスプリンシパルの名前は、アプリの詳細を表示するときに 承認 タブで確認できます。 サービスプリンシパルには、アプリ名が含まれます。 たとえば、 my-hello-world-app, という名前のアプリの場合、サービスプリンシパルの名前は app-22ixod my-hello-world-appになります。

• アプリのサービスプリンシパルに割り当てられたアクセス許可を使用して Databricks ワークスペース内のリソースにアクセスするだけでなく、 ユーザー代理 承認を使用して、アプリ ユーザーに割り当てられたアクセス許可を使用してアプリがリソースと対話するようにすることができます。 UC-マネージドテーブルやモデルサービングエンドポイントなどのリソースへのアクセスを、ユーザーに割り当てられた権限によって制限する必要がある場合は、ユーザー代理認証を使用します。

認証関連の制限については、 制限事項を参照してください。

Databricks アプリにユーザー代理認証を追加する

ユーザーに代理認証をアプリに追加するには、アプリの設定の一部として スコープ を定義します。スコープは、ユーザーの ID を使用してリソースにアクセスするときにアプリが実行できる操作を制限します。スコープを選択しない場合、アプリのアクセスは、アプリに自動的に割り当てられる次のデフォルト スコープのセットに基づいて制限されます。 これらのスコープを使用すると、アプリはアプリ ユーザーに関する情報を取得でき、アプリでユーザー代理承認をサポートする必要があります。スコープは、アプリを作成または編集するときに追加します。

• iam.access-control:read
• iam.current-user:read

Databricks では、 最小特権の原則 に従い、アプリに必要なスコープのみを追加することをお勧めします。

ユーザーは、ユーザー代理承認用に構成されたアプリを使用する前に、同意を付与する必要があります。ユーザーが初めてアプリにアクセスすると、アプリのリクエストされたアクセススコープと説明が記載されたユーザーの同意ページに移動します。アプリを承認すると、ユーザーはアプリの使用に進むことができます。ユーザーは、アプリのスコープに変更がない限り、アプリを一度だけ承認します。

アプリにスコープを追加し、Databricks Apps UI でアプリを作成または編集するときに、ユーザー代理承認を有効にすることができます。

1. アプリのインストール または アプリの編集 カードで、 詳細設定 をクリックします。
2. ユーザー承認済み API スコープ セクションで、アプリに割り当てるスコープを選択します。
3. アプリのインストール または 保存 をクリックします。

リソースにアクセスするときに使用する ID をどのように決定しますか?

アプリを実装するときは、リソースにアクセスするときに使用する ID を決定する必要があります。Databricks では、アプリの機能要件を実装するために使用されるリソースにアクセスするために、ユーザーの ID を使用することをお勧めします。それ以外の場合、アプリが機能するために必要なリソースは、アプリの ID を使用する必要があります。

アプリの ID を使用して、次のことを行います。

• データウェアハウスに接続して、アプリ固有のデータまたはメタデータの読み取りまたは書き込みを行います。
• アプリから Unity Catalog-マネージドテーブルまたはボリュームにログを記録します。

ユーザーの ID を使用して、次のことを行います。

• Unity Catalog で管理されるオブジェクト内のデータをクエリします。
• モデルサービングエンドポイントに接続します。

コード内のアプリとユーザーの ID にアクセスする

アプリのサービスプリンシパルの値は、次の環境変数で使用できます。

変数	説明
DATABRICKS_CLIENT_ID	アプリに割り当てられた Databricks サービスプリンシパルのクライアント ID。
DATABRICKS_CLIENT_SECRET	OAuthDatabricksアプリに割り当てられた サービスプリンシパルの シークレット。

アプリでこれらの値を読み取るには:

Python

import os

client_id = os.getenv('DATABRICKS_CLIENT_ID')
client_secret = os.getenv('DATABRICKS_CLIENT_SECRET')

ユーザーのアクセストークンを含むユーザー情報は、アプリに渡される HTTP ヘッダー にあります。HTTP ヘッダーからの値の取得は、フレームワークによって異なります。以下は、いくつかの一般的なフレームワークでユーザーのアクセストークンを取得する例です。

Streamlit

Python

import streamlit as st
user_access_token = st.context.headers.get('X-Forwarded-Access-Token')

Gradio

Python

from fastapi import Request
import gradio as gr

request: Request = gr.Request().get("request")
user_access_token = dict(request.headers).get('X-Forwarded-Access-Token')

Dash and Flask

Python

from flask import request

headers = request.headers
user_token = headers.get('X-Forwarded-Access-Token')

Shiny

Python

user_token = session.http_conn.headers.get('X-Forwarded-Access-Token', None)

Databricks アプリの状態の維持

アプリがメモリに保持している状態は、再起動すると失われます。 アプリで再起動間で状態を維持する必要がある場合は、状態を外部に保存します。 たとえば、アプリでは Databricks SQL、 ワークスペース ファイル、 または Unity Catalog ボリューム を使用して状態を保持できます。

Databricks アプリからのログ記録

注記

Databricks Apps UI またはアプリの URL でログを表示するには、アプリで stdout と stderrにログを記録する必要があります。

アプリの標準出力と標準エラーを表示するには、アプリの詳細ページで ログ タブをクリックします。 Databricks アプリの詳細を表示するを参照してください。

<appurl>/logzリンクで標準出力ログと標準エラーログを表示することもできます。たとえば、アプリの URL が https://my-app-1234567890.my-instance.databricksapps.comの場合、 https://my-app-1234567890.my-instance.databricksapps.com/logzでログを表示できます。 アプリの URL を見つけるには、アプリの詳細ページに移動します。

Databricks アプリのライブラリ依存関係の指定

デプロイと共に自動的にインストールされるパッケージ以外の Python ライブラリがアプリに必要な場合は、 requirements.txt ファイルを使用してそれらのライブラリを定義します。 requirements.txtファイル内のパッケージが自動的にインストールされたパッケージの 1 つと重複している場合、requirements.txt内のバージョンが自動的にインストールされたパッケージよりも優先されます。

アプリのデプロイの一部としてインストールされるパッケージとバージョンの一覧については、「 インストールされている Python ライブラリ」を参照してください。

Databricks アプリにはどのような HTTP ヘッダーが渡されますか?

次の X-Forwarded-* ヘッダーは、Databricks アプリのリバース プロキシからアプリに渡されます。

header	説明
X-Forwarded-Host	クライアントによって要求された元のホストまたはドメイン。
X-Forwarded-Preferred-Username	IdPから提供されたユーザー名。
X-Forwarded-User	IdP によって提供されるユーザー識別子。
X-Forwarded-Email	IdPが提供するユーザーEメール。
X-Real-Ip	元の要求を行ったクライアントの IP アドレス。
X-Request-Id	リクエストのUUID。

Databricks Apps ではどのようなフレームワークがサポートされていますか?

ほとんどの Python フレームワークを使用してアプリを開発できます。 Dash、Gradio、Streamlitなどの特定のフレームワークの使用例を表示するには、UIで新しいアプリを作成するときにテンプレートアプリのライブラリから選択します。 Databricks Apps UI でアプリを作成するにはどうすればよいですか?を参照してください。

Databricks Apps ランタイム環境で設定される Streamlit 固有の変数については、Stream の デフォルト 環境変数 を参照してください。

ベスト プラクティス: シークレットを使用して Databricks アプリの機密情報を保存する

Databricks では、シークレットを使用して、認証資格情報などの機密情報を格納することをお勧めします。 シークレットの使用の詳細については、シークレットの管理を参照してください。

アプリでシークレットを使用するには：

1. シークレットを アプリ リソースとして構成します。

   

2. アプリの app.yaml 設定ファイルにシークレットのエントリを追加します。

   YAML

   env:
     - name: 'API_TOKEN'
       valueFrom: 'api-token-value'

3. アプリコードのシークレットを参照するには、name フィールドの値（この例では API_TOKEN）を使用して、設定されたキー値を参照します。

Python

token = os.getenv('API_TOKEN')

ベスト プラクティス: Databricks の機能を使用してデータ処理を行う

Databricks Apps コンピュートは、UI を提供するために設計されています。 アプリが複数のユーザーを効率的にサポートできるようにするには、Databricks の機能を使用して、単純なデータ処理以外のことを行う必要があります。 たとえば、クエリ処理とデータセットの保存にはDatabricks SQL 、データ処理には Databricks ジョブ、 AI モデルのクエリにはモデルサービングを使用します。

ベストプラクティス:安全なコーディングのベストプラクティスに従う

Databricks では、アプリを開発するときに、SQL インジェクション攻撃を回避するためのクエリのパラメーター化など、安全なコーディング プラクティスに従うことをお勧めします。 ステートメント実行 API を参照してください。

Databricks アプリの実装に関する重要なガイドライン

• Databricks アプリはSIGTERMの 15 秒後にSIGKILLシグナルを送信するため、アプリはSIGTERMシグナルを受信してから 15 秒以内に正常にシャットダウンする必要があります。アプリが 15 秒経過しても終了しない場合は、 SIGKILL シグナルが送信され、プロセスとすべての子プロセスが終了します。
• Databricks アプリは特権のないシステム ユーザーとして実行されるため、ルート ユーザーのアクセス許可が必要な操作など、特権セキュリティ コンテキストでの実行が必要な操作は実行できません。
• リクエストはリバースプロキシから転送されるため、アプリはリクエストの発信元に依存しないようにする必要があります。 Databricks アプリ環境では、サポートされているフレームワークに必要な構成パラメーターが設定されます。
• Databricks アプリ フレームワークはトランスポート層セキュリティ (TLS) 接続を管理するため、アプリで TLS 接続やハンドシェイク操作を実行してはなりません。
• アプリは、HTTP/2 クリアテキスト (H2C) 形式の要求を処理するように実装する必要があります。
• Databricks アプリは、 0.0.0.0 で HTTP サーバーをホストし、 DATABRICKS_APP_PORT 環境変数で指定されたポート番号を使用する必要があります。 環境変数を参照してください。