パイプラインをバンドルプロジェクトに変換する

既存のパイプラインを宣言型オートメーションバンドルプロジェクトに変換できます。バンドルを使用すると、単一のソース管理された YAML ファイルで Azure Databricks データ処理構成を定義および管理できます。これにより、メンテナンスが容易になり、ターゲット環境への自動デプロイが可能になります。

databricks pipelines コマンドを使用してパイプラインプロジェクトを作成し、パイプラインをデプロイして実行するチュートリアルについては、「宣言型オートメーションバンドルを使用したパイプラインの開発」を参照してください。

変換プロセスの概要

既存のパイプラインをバンドルに変換する具体的な手順を示す図

既存のパイプラインをバンドルに変換するために実行する手順は次のとおりです。

バンドルに変換する、以前に構成されたパイプラインにアクセスできることを確認します。
バンドルを格納するフォルダー (できればソース管理階層) を作成または準備します。
Databricks CLI を使用して、既存のパイプラインからバンドルの構成を生成します。
生成されたバンドル構成を確認して、完了していることを確認します。
バンドルを元のパイプラインにリンクします。
バンドル構成を使用して、パイプラインをターゲットワークスペースにデプロイします。

Requirements

開始する前に、以下が必要です。

ローカル開発マシンにインストールされている Databricks CLI 。宣言型オートメーションバンドルを使用するには、Databricks CLI バージョン 0.218.0 以降が必要です。
バンドルで管理する既存の宣言型パイプラインの ID。この ID を取得する方法については、「 UI を使用して既存のパイプライン定義を取得する」を参照してください。
既存のパイプラインが実行される Azure Databricks ワークスペースの承認。 Databricks CLI 呼び出しの認証と承認を構成するには、「 Azure Databricks リソースへのアクセスを承認する」を参照してください。
パイプラインとその出力を作成、実行、更新、および表示するために必要な権限の完全なセットについては、「パイプラインの ID、アクセス許可、および特権の管理」を参照してください。

手順 1: バンドルプロジェクトのフォルダーを設定する

Azure Databricks で Git フォルダーとして構成されている Git リポジトリにアクセスできる必要があります。このリポジトリにバンドルプロジェクトを作成します。これにより、ソース管理が適用され、対応する Azure Databricks ワークスペース内の Git フォルダーを介して他のコラボレーターが使用できるようになります。 (Git フォルダーの詳細については、 Azure Databricks Git フォルダーを参照してください)。

ローカルコンピューター上の複製された Git リポジトリのルートに移動します。
フォルダー階層の適切な場所に、バンドルプロジェクト専用のフォルダーを作成します。例えば次が挙げられます。
```
mkdir -p ~/source/my-pipelines/ingestion/events/my-bundle
```
現在の作業ディレクトリをこの新しいフォルダーに変更します。例えば次が挙げられます。
```
cd ~/source/my-pipelines/ingestion/events/my-bundle
```
次を実行して、新しいバンドルを初期化します。
```
databricks bundle init
```
プロンプトに応答します。完了すると、プロジェクトの新しいホームフォルダーに databricks.yml という名前のプロジェクト構成ファイルが作成されます。このファイルは、コマンドラインからパイプラインをデプロイするために必要です。この構成ファイルの詳細については、「宣言型オートメーションバンドルの構成」を参照してください。

手順 2: パイプライン構成を生成する

複製した Git リポジトリのフォルダーツリーにあるこの新しいディレクトリから、Databricks CLI バンドル生成コマンドを実行し、パイプラインの ID を <pipeline-id>として指定します。

databricks bundle generate pipeline --existing-pipeline-id <pipeline-id> --profile <profile-name>

generate コマンドを実行すると、パイプラインのバンドル構成ファイルがバンドルの resources フォルダーに作成され、参照されている成果物が src フォルダーにダウンロードされます。 --profile (または-p フラグ) は省略可能ですが、既定のプロファイルではなく使用する特定の Databricks 構成プロファイル (Databricks CLI のインストール時に作成された.databrickscfg ファイルで定義されている) がある場合は、このコマンドで指定します。 Databricks 構成プロファイルの詳細については、 Azure Databricks 構成プロファイルに関するページを参照してください。

ヒント

既存の Spark 宣言パイプライン (SDP) プロジェクト ( spark-pipeline.yml ファイル) がある場合は、そのパイプラインプロジェクトをバンドルの src フォルダーにコピーし、 databricks pipelines generate コマンドを使用してバンドル構成を生成できます。 databricks パイプラインの生成を参照してください。

手順 3: バンドルプロジェクトファイルを確認する

bundle generate コマンドが完了すると、次の 2 つの新しいフォルダーが作成されます。

resources は、プロジェクト構成ファイルを含むプロジェクトサブディレクトリです。
src は、クエリやノートブックなどのソースファイルが格納されるプロジェクトフォルダーです。

このコマンドでは、いくつかの追加ファイルも作成されます。

*.pipeline.yml サブディレクトリの下に resources があります。このファイルには、パイプラインの特定の構成と設定が含まれています。
既存のパイプラインからコピーされた、 src サブディレクトリの SQL クエリなどのソースファイル。

├── databricks.yml                            # Project configuration file created with the bundle init command
├── resources/
│   └── {your-pipeline-name.pipeline}.yml     # Pipeline configuration
└── src/
    └── {source folders and files...}         # Your pipeline's declarative queries

手順 4: バンドルパイプラインを既存のパイプラインにバインドする

変更時に最新の状態に保つために、バンドル内のパイプライン定義を既存のパイプラインにリンクするか、バインドする必要があります。これを行うには、Databricks CLI バンドルデプロイバインドコマンドを実行します。

databricks bundle deployment bind <pipeline-name> <pipeline-ID> --profile <profile-name>

<pipeline-name> はパイプラインの名前です。この名前は、新しい resources ディレクトリ内のパイプライン構成のファイル名のプレフィックス付き文字列値と同じである必要があります。たとえば、ingestion_data_pipeline.pipeline.yml フォルダーに resources という名前のパイプライン構成ファイルがある場合は、パイプライン名として ingestion_data_pipeline を指定する必要があります。

<pipeline-ID> は、パイプラインの ID です。それは、これらの指示の要件としてあなたがコピーしたものと同じです。

手順 5: 新しいバンドルを使用してパイプラインをデプロイする

次に、Databricks CLI バンドルデプロイコマンドを使用して、パイプラインバンドルをターゲットワークスペースにデプロイします。

databricks bundle deploy --target <target-name> --profile <profile-name>

--target フラグは必須であり、development や productionなど、構成されたターゲットワークスペース名と一致する文字列に設定する必要があります。

このコマンドが成功すると、外部プロジェクトにパイプライン構成が作成され、他のワークスペースに読み込んで実行でき、アカウント内の他の Azure Databricks ユーザーと簡単に共有できるようになります。

ターゲットを使用して環境間で昇格する

バンドルは、databricks.ymlのターゲットと呼ばれる名前付きデプロイメント環境を定義し、それぞれが自分のワークスペース、カタログ、変数の値を指しています。ターゲットとは、同じパイプラインを開発、ステージング、本番環境を通じて促進し、編集せずに各環境に同一のソースコードをデプロイする方法です:

bundle:
  name: orders_pipeline

variables:
  catalog:
    description: Unity Catalog to write to
    default: dev_catalog

targets:
  dev:
    mode: development
    default: true
    variables:
      catalog: dev_catalog

  prod:
    mode: production
    variables:
      catalog: prod_catalog
    run_as:
      service_principal_name: '12345678-90ab-cdef-1234-567890abcdef'

各ターゲットに設定した mode は、その展開の挙動を変えます:

mode: development は、ターゲットを個人用の一時的なデプロイとしてマークします。リソースには [dev username] のプレフィックスが付けられ、スケジュールはデフォルトで一時停止されるため、あなたの作業が他の誰にも影響しません。
mode: production これらの安全デフォルトを無効にします。 run_asと組み合わせることで、個人のアカウントではなくサービスプリンシパルとしてパイプラインを運営できるため、誰かがチームを離れたり役割が変わってもランが途切れません。 Azure Databricks では、ステージング環境と本番環境でサービスプリンシパルを使用することを推奨しています。 service_principal_name には、表示名ではなく、サービスプリンシパルのアプリケーション ID を指定します。ワークスペースの管理設定にあるサービスプリンシパルのページからアプリケーションIDを取得することができます。

モードの全動作については、「宣言的自動化バンドルの展開モード」および「宣言的自動化バンドルワークフローの実行識別を指定」を参照してください。

昇格するには 、同じ バンドルを各ターゲットに順番に展開し、各段階で検証を行います:

databricks bundle validate --target prod
databricks bundle deploy --target prod
databricks bundle run orders_pipeline --target prod

変換コード内で環境ごとのカタログ名やソースパスをハードコーディングするのではなく、ターゲットから値を渡して、同じソースがどこでも修正されずに実行されるようにしましょう。設定方法は元の言語によって異なります。パイプラインパラメータはSQLのソースコードにのみ適用されます。ソースコードPython、パイプラインconfigurationフィールドを使い、spark.conf.get()で値を読みます。

resources:
  pipelines:
    orders_pipeline:
      name: orders-pipeline
      # For SQL source code. Reference as ${source_catalog}.
      parameters:
        source_catalog: ${var.catalog}
        source_schema: raw
      # For Python source code. Read with spark.conf.get("source_catalog").
      configuration:
        source_catalog: ${var.catalog}
        source_schema: raw

パイプラインコードのパラメータ化について詳しくは、「 Use parameters with pipelines.」をご覧ください。

CI/CDの設定

変換されたパイプラインは完全にバンドル(YAMLとGitのソースファイル)として定義されているため、そのための継続的インテグレーションと継続的デリバリー(CI/CD)を設定するには、GitHub ActionsやAzure DevOpsなどのCIシステムからバンドルコマンドを実行する必要があります。各プルリクエストごとに、適切なベースラインが実行されます:

ユニットテスト可能な変換関数に pytest を使用します。パイプラインの単体テストを参照してください。
databricks bundle validate --target <env> 設定ミスを検出するために。
オプションとして、サンプルデータに対して期待値を測定するためのスクラッチターゲットの databricks bundle run も設けられます。

以下のGitHub Actionsワークフローは、mainへのマージ時にステージングに展開し、ストアトークンの代わりにOpenID Connect(OIDC)フェデレーションを使用します。

# .github/workflows/deploy.yml
name: Deploy pipeline bundle

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }} # Service principal application ID
    steps:
      - uses: actions/checkout@v4

      - name: Install Databricks CLI
        uses: databricks/setup-cli@main

      - name: Validate bundle
        run: databricks bundle validate --target staging

      - name: Deploy bundle
        run: databricks bundle deploy --target staging

本番環境へのデプロイは手動承認を必須にし（たとえば、GitHub Environment の承認が必要な 2 つ目のジョブや、Azure DevOps の別ステージを使用するなどして）、担当者が各昇格を明示的に承認するようにします。運用環境のジョブは、運用ワークスペースをスコープとするサービスプリンシパルを使用して、databricks bundle deploy --target prod を実行します。詳細については、Azure DatabricksのCI/CDをご覧ください。

トラブルシューティング

問題点	解決策
`databricks.yml` を実行すると「`bundle generate` が見つかりません」というエラーが発生する。	現時点では、 `bundle generate` コマンドはバンドル構成ファイル (`databricks.yml`) を自動的に作成しません。 `databricks bundle init` または手動でファイルを作成する必要があります。
既存のパイプライン設定が、生成されたパイプライン YAML 構成の値と一致しない	パイプライン ID は、バンドル構成 YML ファイルには表示されません。その他の不足している設定がある場合は、手動で適用できます。

成功のためのヒント

バージョン管理は常に使用してください。 Databricks Git フォルダーを使用していない場合は、プロジェクトのサブディレクトリとファイルを Git またはその他のバージョン管理されたリポジトリまたはファイルシステムに格納します。
運用環境にデプロイする前に、非運用環境 ("開発" や "テスト" 環境など) でパイプラインをテストします。誤った構成を誤って導入するのは簡単です。

その他のリソース

バンドルを使用してデータ処理を定義および管理する方法の詳細については、以下を参照してください。

宣言型オートメーションバンドルとは
宣言型オートメーションバンドルを使用してパイプラインを開発します。このトピックでは、既存のパイプラインではなく新しいパイプラインのバンドルを作成し、指定した処理用にバージョン管理されたソースファイルを含めます。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-08-21

パイプラインをバンドル プロジェクトに変換する

変換プロセスの概要

Requirements

手順 1: バンドル プロジェクトのフォルダーを設定する

手順 2: パイプライン構成を生成する

手順 3: バンドル プロジェクト ファイルを確認する

手順 4: バンドル パイプラインを既存のパイプラインにバインドする

手順 5: 新しいバンドルを使用してパイプラインをデプロイする

ターゲットを使用して環境間で昇格する

CI/CDの設定

トラブルシューティング

成功のためのヒント

その他のリソース

フィードバック

その他のリソース

パイプラインをバンドルプロジェクトに変換する

手順 1: バンドルプロジェクトのフォルダーを設定する

手順 3: バンドルプロジェクトファイルを確認する

手順 4: バンドルパイプラインを既存のパイプラインにバインドする