バンドルを手動で作成する

[アーティクル]
10/07/2024

このチュートリアルでは、Databricks アセットバンドルを最初から作成します。このシンプルなバンドルは、2 つのノートブックと、これらのノートブックを実行するための Azure Databricks ジョブの定義で構成されています。その後、お使いの Azure Databricks ワークスペースでジョブを検証、デプロイ、実行します。これらの手順では、「Azure Databricks ジョブを使用して最初のワークフローを作成する」というクイックスタートを自動化します。

要件

Databricks CLI バージョン 0.218.0 以降。お使いのインストールされている Databricks CLI のバージョンをチェックするには、databricks -v コマンドを実行します。 Databricks CLI をインストールするには、「Databricks CLI のインストールまたは更新」を参照してください。
Databricks CLI 用に構成された認証。 Databricks CLI の認証に関する記事を参照してください。
リモート Databricks ワークスペースでは、ワークスペースファイルが有効になっている必要があります。「ワークスペースファイルとは」を参照してください。

手順 1: バンドルを作成する

バンドルには、デプロイする成果物と、実行するリソースの設定が含まれます。

お使いの開発マシン上で空のディレクトリを作成または指定します。
ターミナル内の空のディレクトリに切り替えるか、IDE で空のディレクトリを開きます。

ヒント

Git プロバイダーからクローンされたリポジトリを含むディレクトリを使用することもできます。これにより、外部のバージョンコントロールを使用してお使いのバンドルを管理し、プロジェクトの他の開発者や IT プロフェッショナルとより簡単に共同作業することができます。

このデモ用にリポジトリをクローンすることを選択した場合、Databricks では、そのリポジトリが空であるか、README や .gitignore などの基本的なファイルのみが含まれるようにすることをお勧めします。それ以外の場合、そのリポジトリ内の既存ファイルが、お使いの Azure Databricks ワークスペースへ不必要に同期されることがあります。

手順 2: ノートブックをプロジェクトに追加する

この手順では、お使いのワークスペースにノートブックを 2 つ追加します。最初のノートブックは、ニューヨーク州保険局の公開データソースから、2007 年以降に人気の赤ちゃんの名前の一覧を取得します。保険局の Web サイトにある「Baby Names: Trending by Name: Beginning 2007 (赤ちゃんの名前: 名前のトレンド: 2007年以降)」を参照してください。最初のノートブックでは、my-volume という名前のカタログ内の default という名前のスキーマで、main という名前の Azure Databricks Unity Catalog ボリュームにこのデータを保存します。 2 番目のノートブックは、保存されたデータに対するクエリを実行し、2014 年の名と性別による赤ちゃんの名前の集計数を表示します。

そのディレクトリのルートから、最初のノートブック (retrieve-baby-names.py という名前のファイル) を作成します。

次のコードを retrieve-baby-names.py ファイルに追加します。

# Databricks notebook source
import requests

response = requests.get('http://health.data.ny.gov/api/views/jxy9-yhdk/rows.csv')
csvfile = response.content.decode('utf-8')
dbutils.fs.put("/Volumes/main/default/my-volume/babynames.csv", csvfile, True)

2 つ目のノートブック (filter-baby-names.pyという名前のファイル) を同じディレクトリに作成します。

次のコードを filter-baby-names.py ファイルに追加します。

# Databricks notebook source
babynames = spark.read.format("csv").option("header", "true").option("inferSchema", "true").load("/Volumes/main/default/my-volume/babynames.csv")
babynames.createOrReplaceTempView("babynames_table")
years = spark.sql("select distinct(Year) from babynames_table").toPandas()['Year'].tolist()
years.sort()
dbutils.widgets.dropdown("year", "2014", [str(x) for x in years])
display(babynames.filter(babynames.Year == dbutils.widgets.get("year")))

手順 3: バンドル構成スキーマファイルをプロジェクトに追加する

YAML ファイルや JSON スキーマファイルをサポートする Visual Studio Code、PyCharm Professional、IntelliJ IDEA Ultimate などの IDE を使用している場合は、IDE を使用してバンドル構成スキーマファイルを作成するだけでなく、プロジェクトのバンドル構成ファイルの構文と書式設定をチェックすることができます。手順 5 で後ほど作成するバンドル構成ファイルは YAML ベースですが、この手順のバンドル構成スキーマファイルは JSON ベースです。

Visual Studio Code

Visual Studio Code Marketplace から YAML 拡張機能をインストールするなどして、Visual Studio Code に YAML 言語サーバーのサポートを追加します。
Databricks CLI を使用して bundle schema コマンドを実行し、出力を JSON ファイルにリダイレクトして、Databricks アセットバンドル構成 JSON スキーマファイルを生成します。たとえば、次のように、現在のディレクトリ内で bundle_config_schema.json という名前のファイルを生成します。
```
databricks bundle schema > bundle_config_schema.json
```
手順 5 では、バンドル構成ファイルの先頭に次のコメントを追加し、バンドル構成ファイルを指定した JSON スキーマファイルに関連付けます。
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Note

前のコメントで、Databricks アセットバンドル構成 JSON スキーマファイルが別のパスにある場合は、bundle_config_schema.json をスキーマファイルへの完全パスに置き換えます。

PyCharm Professional

Databricks CLI を使用して bundle schema コマンドを実行し、出力を JSON ファイルにリダイレクトして、Databricks アセットバンドル構成 JSON スキーマファイルを生成します。たとえば、次のように、現在のディレクトリ内で bundle_config_schema.json という名前のファイルを生成します。
```
databricks bundle schema > bundle_config_schema.json
```
バンドル構成 JSON スキーマファイルが認識されるように PyCharm を構成し、「Configure a custom JSON schema (カスタム JSON スキーマを構成する)」の手順に従って、JSON スキーママッピングを完了します。
手順 5 では、PyCharm を使用してバンドル構成ファイルを作成または開きます。通常、このファイルの名前は databricks.yml になります。

IntelliJ IDEA Ultimate

Databricks CLI を使用して bundle schema コマンドを実行し、出力を JSON ファイルにリダイレクトして、Databricks アセットバンドル構成 JSON スキーマファイルを生成します。たとえば、次のように、現在のディレクトリ内で bundle_config_schema.json という名前のファイルを生成します。
```
databricks bundle schema > bundle_config_schema.json
```
バンドル構成 JSON スキーマファイルが認識されるように IntelliJ IDEA を構成し、「カスタム JSON スキーマを構成する」の手順に従って、JSON スキーママッピングを完了します。
手順 5 では、IntelliJ IDEA を使用してバンドル構成ファイルを作成または開きます。通常、このファイルの名前は databricks.yml になります。

手順 4: 認証を設定する

この手順では、お使いの開発マシン上の Databricks CLI とお使いの Azure Databricks ワークスペース間の認証を設定します。この記事では、OAuth ユーザー対マシン (U2M) 認証と、DEFAULT という名前の対応する Azure Databricks 構成プロファイルを認証に使用することを前提としています。

Note

U2M 認証は、これらの手順をリアルタイムで試す場合に適しています。完全に自動化されたワークフローの場合、Databricks では代わりに OAuth マシン間 (M2M) 認証を使用することをお勧めします。「認証」内の、M2M 認証のセットアップ手順をご参照ください。

Databricks CLI を使用して、ターゲットワークスペースごとに次のコマンドを実行し、OAuth トークン管理をローカルで開始します。

次のコマンド内では、<workspace-url> を Azure Databricks ワークスペース単位の URL (例: https://adb-1234567890123456.7.azuredatabricks.net) に置き換えます。
```
databricks auth login --host <workspace-url>
```
Databricks CLI では、入力した情報を Azure Databricks 構成プロファイルとして保存するように求められます。 Enter キーを押して提案されたプロファイル名を受け入れるか、新規または既存のプロファイル名を入力します。同じ名前の既存のプロファイルは、入力した情報で上書きされます。プロファイルを使用すると、複数のワークスペース間で認証コンテキストをすばやく切り替えることができます。

既存のプロファイルの一覧を取得するには、別のターミナルまたはコマンドプロンプト内で、Databricks CLI を使用してコマンド databricks auth profiles を実行します。特定のプロファイルの既存の設定を表示するには、コマンド databricks auth env --profile <profile-name> を実行します。
Web ブラウザー内で、画面の指示に従って Azure Databricks ワークスペースにログインします。
プロファイルの現在の OAuth トークン値とトークンの今後の有効期限のタイムスタンプを表示するには、次のいずれかのコマンドを実行します。
- databricks auth token --host <workspace-url>
- databricks auth token -p <profile-name>
- databricks auth token --host <workspace-url> -p <profile-name>
同じ --host 値を持つ複数のプロファイルがある場合は、Databricks CLI が正しく一致する OAuth トークン情報を見つけるのに役立つ --host と -p のオプションを一緒に指定することが必要になる場合があります。

手順 5: バンドル構成ファイルをプロジェクトに追加する

この手順では、2 つのノートブックをデプロイして実行する方法を定義します。このデモでは、Azure Databricks ジョブを使用して最初のノートブックを実行し、次に 2 番目のノートブックを実行します。 1 番目ノートブックでデータが保存され、2 番目のノートブックで保存されたデータのクエリが実行されるため、1 番目のノートブックの実行が完了してから、2 番目のノートブックが開始されるようにします。これらの目標をプロジェクトのバンドル構成ファイル内にモデル化します。

ディレクトリのルートから、バンドル構成ファイル (databricks.yml という名前のファイル) を作成します。
databricks.yml ファイルに次のコードを追加し、<workspace-url> を、ワークスペースごとの URL (例: https://adb-1234567890123456.7.azuredatabricks.net) に置き換えます。この URL は、.databrickscfg ファイル内のものと一致する必要があります。

ヒント

最初の行 (# yaml-language-server 以降) は、IDE でサポートされている場合にのみ必要です。詳細については、前の手順 3 を参照してください。

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job:
      name: retrieve-filter-baby-names-job
      job_clusters:
        - job_cluster_key: common-cluster
          new_cluster:
            spark_version: 12.2.x-scala2.12
            node_type_id: Standard_DS3_v2
            num_workers: 1
      tasks:
        - task_key: retrieve-baby-names-task
          job_cluster_key: common-cluster
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          job_cluster_key: common-cluster
          notebook_task:
            notebook_path: ./filter-baby-names.py

targets:
  development:
    workspace:
      host: <workspace-url>

ジョブをカスタマイズする場合、ジョブ宣言内のマッピングは、REST API リファレンスの POST /api/2.1/jobs/create に記載されているジョブ作成操作の要求ペイロードに対応し、YAML 形式で表されます。

ヒント

「Databricks アセットバンドルで新しいジョブクラスター設定をオーバーライドする」で説明されている手法を使用して、バンドル内のクラスターの設定を定義、結合、オーバーライドできます。

手順 6: プロジェクトのバンドル構成ファイルを検証する

この手順では、そのバンドル設定が有効かどうかを確認します。

Databricks CLI を使用して、次のように bundle validate コマンドを実行します。
```
databricks bundle validate
```
バンドル構成の概要が返されたら、検証が成功したことになります。エラーが返される場合は、エラーを修正してから、この手順を繰り返します。

この手順の後、お使いのバンドルに何か変更を加える場合はこの手順を繰り返し、お使いのバンドル構成がまだ有効かどうかをチェックする必要があります。

手順 7: ローカルプロジェクトをリモートワークスペースにデプロイする

この手順では、リモートの Azure Databricks ワークスペースに 2 つのローカルノートブックをデプロイし、ワークスペース内に Azure Databricks ジョブを作成します。

Databricks CLI を使用して、次のように bundle deploy コマンドを実行します。
```
databricks bundle deploy -t development
```
2 つのローカルノートブックがデプロイされているかどうかを確認します: Azure Databricks ワークスペースのサイドバーで [ワークスペース] をクリックします。
[Users] ><your-username>> [.bundle] >[baby-names] > [development] > [files] フォルダーをクリックします。このフォルダーに 2 つのノートブックが含まれている必要があります。
ジョブが作成されたかどうかを確認します: Azure Databricks ワークスペースのサイドバーで、[ワークフロー] をクリックします。
[ジョブ] タブで、[retrieve-filter-baby-names-job] をクリックします。
[タスク] タブをクリックします。retrieve-baby-names-task と filter-baby-names-task の 2 つのタスクがあるはずです。

この手順の後にバンドルに変更を加えた場合は、手順 6 と 7 を繰り返して、バンドル構成がまだ有効かどうかを確認してから、プロジェクトを再デプロイする必要があります。

手順 8: デプロイされたプロジェクトを実行する

この手順では、お使いのワークスペース内でその Azure Databricks ジョブを実行します。

Databricks CLI を使用して、次のように bundle run コマンドを実行します。
```
databricks bundle run -t development retrieve-filter-baby-names-job
```
お使いのターミナル内に表示される "Run URL" の値をコピーし、この値を Web ブラウザーに貼り付けて、お使いの Azure Databricks ワークスペースを開きます。
Azure Databricks ワークスペースで、2 つのタスクが正常に完了し、緑色のタイトルバーが表示されたら、filter-baby-names-task タスクをクリックしてクエリ結果を表示します。

この手順の後にバンドルに変更を加えた場合は、手順 6 から 8 を繰り返して、バンドル構成がまだ有効かどうかを確認し、プロジェクトを再デプロイして、再デプロイされたプロジェクトを実行する必要があります。

手順 9: クリーンアップする

この手順では、デプロイされた 2 つのノートブックとジョブをワークスペースから削除します。

Databricks CLI を使用して、次のように bundle destroy コマンドを実行します。
```
databricks bundle destroy
```
ジョブの削除要求を確認します: リソースを完全に破棄するように求められたら、「y」と入力し、Enter キーを押します。
ノートブックの削除要求を確認します: 以前にデプロイしたフォルダーとそのすべてのファイルを完全に破棄するように求められたら、「y」と入力し、Enter キーを押します。

bundle destroy コマンドを実行すると、デプロイされたジョブと、デプロイされた 2 つのノートブックを含むフォルダーのみが削除されます。このコマンドでは、最初のノートブックが作成した babynames.csv ファイルなど、副作用はいずれも削除されません。 babybnames.csv ファイルを削除するには、次の操作を行います。

Azure Databricks ワークスペースのサイドバーで、[カタログ] をクリックします。
[DBFS を参照] をクリックします。
FileStore フォルダーをクリックします。
babynames.csv の横にあるドロップダウン矢印をクリックし、[削除] クリックします。
開発用コンピューターからもバンドルを削除する場合は、手順 1 のローカルディレクトリを削除できます。

次の方法で共有

バンドルを手動で作成する

要件

手順 1: バンドルを作成する

手順 2: ノートブックをプロジェクトに追加する

手順 3: バンドル構成スキーマファイルをプロジェクトに追加する

Visual Studio Code

PyCharm Professional

IntelliJ IDEA Ultimate

手順 4: 認証を設定する

手順 5: バンドル構成ファイルをプロジェクトに追加する

手順 6: プロジェクトのバンドル構成ファイルを検証する

手順 7: ローカルプロジェクトをリモートワークスペースにデプロイする

手順 8: デプロイされたプロジェクトを実行する

手順 9: クリーンアップする

フィードバック

その他のリソース

次の方法で共有

バンドルを手動で作成する

要件

手順 1: バンドルを作成する

手順 2: ノートブックをプロジェクトに追加する

手順 3: バンドル構成スキーマ ファイルをプロジェクトに追加する

Visual Studio Code

PyCharm Professional

IntelliJ IDEA Ultimate

手順 4: 認証を設定する

手順 5: バンドル構成ファイルをプロジェクトに追加する

手順 6: プロジェクトのバンドル構成ファイルを検証する

手順 7: ローカル プロジェクトをリモート ワークスペースにデプロイする

手順 8: デプロイされたプロジェクトを実行する

手順 9: クリーン アップする

フィードバック

その他のリソース

手順 3: バンドル構成スキーマファイルをプロジェクトに追加する

手順 7: ローカルプロジェクトをリモートワークスペースにデプロイする

手順 9: クリーンアップする