Databricks アプリの開発
プレビュー
Databricks Apps は パブリック プレビュー段階です。
Databricks ワークスペースでアプリをデプロイして実行するには、ファイアウォールがドメイン *.databricksapps.com
をブロックしていないことを確認する必要があります。
AIDatabricksこの記事では、UI でアプリを作成および編集する方法、Databricks SQLウェアハウス、シークレット、 ジョブなどの プラットフォーム機能の使用方法、アプリ開発のベストDatabricks プラクティス、サポートされているフレームワークを使用してアプリを開発するための重要な情報など、 Apps を使用してデータ アプリと アプリを作成する方法について詳しく説明します。
Databricks Apps UI でアプリを作成するにはどうすればよいですか?
-
サイドバーで「
新規 」をクリックし、メニューから「 アプリ 」を選択します。
-
完全な事前構築済みのサンプル アプリから始めることも、ソース コードとアーティファクトを使用することもできます。
- サンプル アプリから開始するには、[ テンプレート] を選択し、優先するフレームワークのタブをクリックして、アプリの一覧から選択します。
- コードを使用してアプリを作成するには、[ カスタム ] を選択します。
-
「 次へ 」をクリックします。
-
アプリ名フィールドに 、アプリの名前を入力し、オプションで説明を入力します。
-
Databricks アプリに割り当てられた名前は、アプリの作成後に変更することはできず、Databricks ワークスペースにアクセスできるすべてのユーザーは、ワークスペース内のすべての Databricks アプリの名前とデプロイ履歴を確認できます。 さらに、アプリ名はシステムテーブルに書き込まれるレコードに含まれます。 この可視性のため、Databricks アプリに名前を付けるときに機密情報を含めないでください。
-
名前は、アプリをホストする Databricks ワークスペース内で一意である必要があり、小文字、数字、ハイフンのみを含める必要があります。
[カスタム ] を選択した場合は、[ アプリを作成 ] をクリックします。 [テンプレート] を選択した場合は、必要なリソースを構成し、[ アプリの作成とデプロイ ] をクリックします。「 Databricks プラットフォーム機能を Databricks アプリに割り当てる」を参照してください。
アプリの詳細ページは、[ アプリの作成とデプロイ ] または [ アプリの作成 ] をクリックすると表示されます。 [テンプレート] を選択した場合、Databricks Apps はアプリを作成し、テンプレートのサンプル コードとアプリの必要な構成を含むアプリをデプロイします。アプリの詳細ページには、次の情報が表示されます。
- アプリの作成と展開のステータス。
- アプリのアーティファクトをローカル環境にコピーしたり、ローカルの変更を Databricks ワークスペースに同期したりするなど、アプリをローカルで開発を続行するために使用できる手順。
[カスタム ] を選択した場合は、Databricks Apps によってアプリが作成されます。アプリのコードとアーティファクトを追加する必要があるため、アプリを別のステップとしてデプロイする必要があります。 アプリの詳細ページには、次の情報が表示されます。
- アプリの作成ステータス。
- アプリのコードとアーティファクトをローカル開発環境から Databricks ワークスペースに同期し、アプリをデプロイする手順。
ローカル開発環境を設定する方法、アプリのコードと構成をローカルで作成または更新する方法、アプリを Databricks ワークスペースに同期してデプロイする方法については、「 Databricks アプリの概要」を参照してください。 5. [テンプレート ] を選択し、アプリのアーティファクトをワークスペースからローカル開発環境にコピーする場合は、次のDatabricks CLIを使用できます。
databricks workspace export-dir <workspace-path> <target-path>
以下のように置き換えてください。
<workspace-path>
は、アプリのコードとアーティファクトを含むワークスペースファイルディレクトリへのパスに置き換えます。<target-path>
を、ファイルのコピー先となるローカル環境内のパスに置き換えます。
Databricks プラットフォーム機能を Databricks アプリに割り当てる
Databricks SQLを使用するには、サービスプリンシパルはSQLウェアハウスとクエリによってアクセスされるテーブルへのアクセスが必要です。
DatabricksDatabricks SQL、Databricks Jobs、Mosaic AI Model Serving 、Databricks シークレットなどの プラットフォームの機能を使用するには、これらの機能をリソースとしてアプリに追加します。リソースは、アプリ を作成 または編集するときに追加できます。
-
[新しいアプリの作成 ] または [アプリの編集 ] カードで、[ 詳細設定 ] > [+ リソースの追加 ] をクリックし、リソースの種類を選択します。
-
リソースのタイプに応じて、リソースの設定に必要なフィールド ( リソースキー フィールドなど) を入力します。 このキーは、後でリソースを参照するために使用されます。
-
[ 保存 ]をクリックします。
-
SQLウェアハウス リソース キーを使用して、
app.yaml
構成ファイルにリソースのエントリを追加します。これは実際の値ではなくパラメーター値のソースを参照しているため、value
の代わりにvalueFrom
を使用します。YAMLenv:
- name: 'DATABRICKS_WAREHOUSE_ID'
valueFrom: 'sql-warehouse' -
アプリ コードでリソースを参照するには、
name
フィールドの値 (この例ではDATABRICKS_WAREHOUSE_ID
) を使用して、構成されたキー値を参照します。Pythonimport os
os.getenv('DATABRICKS_WAREHOUSE_ID')
SQLウェアハウス エンドポイントやモデル サービング エンドポイントなど、アプリでリソースを使用するその他の例については、アプリ作成時のテンプレートの例とベスト プラクティス: シークレットを使用してDatabricksアプリの機密情報を格納する方法をご覧ください。
Databricks アプリの詳細を表示する
Databricks アプリの詳細ページを表示するには:
- サイドバーの
[ コンピュート ]をクリックします。
- [アプリ ] タブに移動します。
- [ 名前 ] 列で、アプリ名をクリックします。
- [ 概要 ] タブが表示され、アプリのステータス、デプロイ場所、関連リソースなど、アプリの詳細が表示されます。
- アプリのデプロイ履歴にアクセスするには、[ デプロイ ] タブに移動します。
- アプリのログを表示するには、[ ログ ] タブに移動します。
- 環境変数やインストール済みパッケージなど、アプリのランタイム環境を表示するには、[ 環境 ] タブに移動します。
Databricks アプリのアクセス許可を構成する
アプリの権限を管理するには、 CAN MANAGE
または IS OWNER
の権限が必要です。アプリにアクセスするには、ユーザーはアプリに対する CAN_USE
または CAN_MANAGE
権限を持っている必要があります。ユーザーがアプリに対して CAN_MANAGE
権限を必要としない限り、Databricks では CAN_USE
権限のみを割り当てることをお勧めします。
- アプリの詳細ページで、[ 権限] をクリックします。
- [権限設定 ] で、[ ユーザー、グループ、またはサービスプリンシパルの選択 ] ドロップダウンメニューを選択し、ユーザー、グループ、サービスプリンシパル、またはすべてのワークスペースユーザーを選択します。
- 権限のドロップダウンメニューから権限を選択します。
- [ 追加 ] をクリックし、[ 保存 ] をクリックします。
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 でアプリを作成または編集するときに、ユーザー代理承認を有効にすることができます。
- [ アプリのインストール ] または [アプリの編集 ] カードで、[ 詳細設定 ] をクリックします。
- [ ユーザー承認済み API スコープ] セクションで、アプリに割り当てるスコープを選択します。
- [アプリのインストール ] または [保存 ] をクリックします。
リソースにアクセスするときに使用する ID をどのように決定しますか?
アプリを実装するときは、リソースにアクセスするときに使用する ID を決定する必要があります。Databricks では、アプリの機能要件を実装するために使用されるリソースにアクセスするために、ユーザーの ID を使用することをお勧めします。それ以外の場合、アプリが機能するために必要なリソースは、アプリの ID を使用する必要があります。
アプリの ID を使用して、次のことを行います。
- データウェアハウスに接続して、アプリ固有のデータまたはメタデータの読み取りまたは書き込みを行います。
- アプリから Unity Catalog-マネージドテーブルまたはボリュームにログを記録します。
ユーザーの ID を使用して、次のことを行います。
- Unity Catalog で管理されるオブジェクト内のデータをクエリします。
- モデルサービングエンドポイントに接続します。
コード内のアプリとユーザーの ID にアクセスする
アプリのサービスプリンシパルの値は、次の環境変数で使用できます。
変数 | 説明 |
---|---|
| アプリに割り当てられた Databricks サービスプリンシパルのクライアント ID。 |
| OAuthDatabricksアプリに割り当てられた サービスプリンシパルの シークレット。 |
アプリでこれらの値を読み取るには:
import os
client_id = os.getenv('DATABRICKS_CLIENT_ID')
client_secret = os.getenv('DATABRICKS_CLIENT_SECRET')
ユーザーのアクセストークンを含むユーザー情報は、アプリに渡される HTTP ヘッダー にあります。HTTP ヘッダーからの値の取得は、フレームワークによって異なります。以下は、いくつかの一般的なフレームワークでユーザーのアクセストークンを取得する例です。
- Streamlit
- Gradio
- Dash and Flask
- Shiny
import streamlit as st
user_access_token = st.context.headers.get('X-Forwarded-Access-Token')
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')
from flask import request
headers = request.headers
user_token = headers.get('X-Forwarded-Access-Token')
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 | 説明 |
---|---|
| クライアントによって要求された元のホストまたはドメイン。 |
| IdPから提供されたユーザー名。 |
| IdP によって提供されるユーザー識別子。 |
| IdPが提供するユーザーEメール。 |
| 元の要求を行ったクライアントの IP アドレス。 |
| リクエストのUUID。 |
Databricks Apps ではどのようなフレームワークがサポートされていますか?
ほとんどの Python フレームワークを使用してアプリを開発できます。 Dash、Gradio、Streamlitなどの特定のフレームワークの使用例を表示するには、UIで新しいアプリを作成するときにテンプレートアプリのライブラリから選択します。 「Databricks Apps UI でアプリを作成するにはどうすればよいですか?」を参照してください。
Databricks Apps ランタイム環境で設定される Streamlit 固有の変数については、Stream の デフォルト 環境変数 を参照してください。
ベスト プラクティス: シークレットを使用して Databricks アプリの機密情報を保存する
Databricks では、シークレットを使用して、認証資格情報などの機密情報を格納することをお勧めします。 シークレットの使用の詳細については、「 シークレットの管理」を参照してください。
アプリでシークレットを使用するには:
-
シークレットを アプリ リソースとして構成します。
-
アプリの
app.yaml
設定ファイルにシークレットのエントリを追加します。YAMLenv:
- name: 'API_TOKEN'
valueFrom: 'api-token-value' -
アプリコードのシークレットを参照するには、
name
フィールドの値(この例ではAPI_TOKEN
)を使用して、設定されたキー値を参照します。
token = os.getenv('API_TOKEN')
ベスト プラクティス: Databricks の機能を使用してデータ処理を行う
Databricks Apps コンピュートは、UI を提供するために設計されています。 アプリが複数のユーザーを効率的にサポートできるようにするには、Databricks の機能を使用して、単純なデータ処理以外のことを行う必要があります。 たとえば、クエリ処理とデータセットの保存には a 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
環境変数で指定されたポート番号を使用する必要があります。 環境変数を参照してください。