Databricks アセットバンドルの置換と変数

Databricks Asset Bundles は、置換とカスタム変数をサポートしているため、バンドル構成ファイルのモジュール化と再利用性が向上します。 置換とカスタム変数の両方で、値を動的に取得できるため、バンドルのデプロイと実行時に設定を決定できます。

ヒント

また、ジョブパラメーターの値の動的な値参照を使用して、ジョブの実行に関するコンテキストをジョブタスクに渡すこともできます。「ジョブの実行に関するコンテキストをジョブタスクに渡す」を参照してください。

置換

置換を使用して、バンドルのデプロイメントと実行のコンテキストに基づいて変更される設定の値を取得できます。

たとえば、 bundle validate --output json コマンドを実行すると、次のようなグラフが表示される場合があります。

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

代用を使用して、バンドル name、バンドル イ target、およびワークスペース userName フィールドの値を参照し、バンドル設定ファイルにワークスペース root_path を構築できます。

bundle:
  name: hello-bundle

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

# ...

targets:
  dev:
    default: true

また、名前付きリソースの置き換えを作成することもできます。たとえば、my_pipelineという名前で構成されたパイプラインの場合は、${resources.pipelines.my_pipeline.target}がmy_pipelineのターゲットの値の置き換えになります。

有効な置き換えを決定するには、REST APIリファレンスに記載されているスキーマ階層を使用するか、bundle schemaコマンドの出力を使用します。

一般的に使用される置き換えは次のとおりです。

  • ${bundle.name}

  • ${bundle.target}  # Use this substitution instead of ${bundle.environment}

  • ${workspace.host}

  • ${workspace.current_user.short_name}

  • ${workspace.current_user.userName}

  • ${workspace.file_path}

  • ${workspace.root_path}

  • ${resources.jobs.<job-name>.id}

  • ${resources.models.<model-name>.name}

  • ${resources.pipelines.<pipeline-name>.name}

カスタム変数

バンドルに単純なカスタム変数と複雑なカスタム変数の両方を定義して、多くのシナリオで必要な値を動的に取得できるようにすることができます。 カスタム変数は、 variables マッピング内のバンドル設定ファイルで宣言されます。 変数を参照してください。

次の設定例では、変数 の my_cluster_id と my_notebook_pathを定義しています。

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

この宣言の一部として変数にdefault値を指定しない場合は、「変数の値を設定する」で説明されているように、バンドルコマンドを実行するときに、環境変数を通じて、またはバンドル構成ファイル内の他の場所で、値を設定する必要があります。

バンドル設定内でカスタム変数を参照するには、変数置換${var.<variable_name>}を使用します。たとえば、変数 my_cluster_id と my_notebook_pathを参照するには、次のようにします。

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

変数の値を設定する

変数にdefault値を指定していない場合、または変数のdefault値を一時的に上書きしたい場合は、次のいずれかの方法を使用して変数の新しい一時値を指定します。

  • 変数の値は、validate、deploy、runなどのbundleコマンドの一部として指定します。これを行うには、オプション--var="<key>=<value>"を使用します。ここで、<key>は変数の名前、<value>変数の値です。たとえば、bundle validateコマンドの一部として、1234-567890-abcde123の値をmy_cluster_idという名前の変数に提供し、./hello.pyの値をmy_notebook_pathという名前の変数に指定するには、次のようにします。

    databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"

# Or:
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"

  • 環境変数を設定して、変数の値を指定します。環境変数の名前はBUNDLE_VAR_で始まる必要があります。環境変数を設定するには、ご利用のオペレーティングシステムのドキュメントを参照してください。たとえば、1234-567890-abcde123の値をmy_cluster_idという名前の変数に指定し、./hello.pyの値をmy_notebook_pathという名前の変数に指定するには、validate、deploy、runなどのbundleコマンドを呼び出す前に、以下のコマンドを実行します。

    LinuxまたはmacOSの場合：

    export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py

    Windowsの場合：

    "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"

    または、LinuxおよびmacOSの場合、変数の値をvalidate、deploy、runなど、bundleコマンドの一部として指定します。

    BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate

    または、Windowsの場合：

    "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"

  • バンドル構成ファイル内で変数の値を指定します。これを行うには、targetsマッピング内でvariablesマッピングを使用し、次の形式に従います。

    variables:
  <variable-name>: <value>

    たとえば、2つの別々のターゲットに対してmy_cluster_idおよびmy_notebook_pathという名前の変数の値を指定するには、次のようにします。

    targets:
  dev:
    variables:
      my_cluster_id: 1234-567890-abcde123
      my_notebook_path: ./hello.py
  prod:
    variables:
      my_cluster_id: 2345-678901-bcdef234
      my_notebook_path: ./hello.py

注：

変数値を提供するためにどのアプローチを選択する場合でも、デプロイメント段階と実行段階の両方で同じアプローチを使用してください。そうしないと、デプロイメント時と、その既存のデプロイメントに基づくジョブまたはパイプラインの実行の間に、予期しない結果が生じる可能性があります。

前述の例では、Databricks CLIはmy_cluster_idとmy_notebook_pathの変数の値を以下の順序で検索し、一致する各変数の値を見つけたときに停止し、その変数の他の場所をスキップします。

  1. bundleコマンドの一部として指定された任意の--varオプション内。

  2. BUNDLE_VAR_で始まる任意の環境変数セット内。

  3. バンドル構成ファイル内のtargetsマッピングのうち、任意のvariablesマッピング内。

  4. バンドル構成ファイル内の最上位のvariablesマッピングのうち、その変数の定義の任意のdefault値。

複素変数を定義する

カスタム変数は、複合変数として定義しない限り、文字列型と見なされます。 バンドルの複合型を持つカスタム変数を定義するには、バンドル構成で type を complex に設定します。

注：

type設定に対して有効な値はcomplexのみです。さらに、typeがcomplexに設定されていて、変数に定義されているdefaultが単一の値の場合、バンドルの検証は失敗します。

次の例では、クラスター設定がmy_clusterという名前のカスタム複素変数内で定義されています。

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

オブジェクトのID値を取得する

alert、cluster_policy、cluster、dashboard、instance_pool、job、metastore、pipeline、query、service_principal、およびwarehouseオブジェクトタイプの場合、カスタム変数のlookupを定義して、次の形式を使用して名前付きオブジェクトのIDを取得できます。

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

変数にルックアップが定義されている場合、指定された名前のオブジェクトのIDが変数の値として使用されます。これにより、オブジェクトの正しい解決済みIDが常に変数に使用されるようになります。

注：

指定された名前のオブジェクトが存在しない場合、または指定された名前のオブジェクトが複数存在する場合はエラーとなります。

たとえば、次の構成では、${var.my_cluster_id}は12.2共有クラスターのIDに置き換えられます。

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}