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

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

ヒント

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

代替品

置換を使用して、バンドルのデプロイメントと実行のコンテキストに基づいて変更される可能性のある設定の値を取得できます。たとえば、置換を使用して、バンドル name、バンドル target、およびワークスペース userName フィールドの値を参照し、バンドル設定ファイルにワークスペース root_path を構築できます。

YAML
bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

このバンドル someone@example.com デプロイされた場合、ルートパス . /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/devにデプロイされます。

名前付きリソースの置換を作成することもできます。たとえば、次のパイプライン定義では、パイプラインのターゲットの値に ${resources.pipelines.my_pipeline.target} を使用できます。

YAML
resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      schema: pipeline_bundle_${bundle.target}
      libraries:
        - notebook:
            path: ../src/dlt_pipeline.ipynb

      configuration:
        bundle.sourcePath: ${workspace.file_path}/src

有効な置換を判別するには、バンドル構成リファレンス、リソース構成リファレンス、 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 マッピング内または variable-overrides.json ファイルで宣言されます。 variablesマッピングに関する情報については、変数を参照してください。

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

YAML
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 値を指定しない場合は、バンドルコマンドを実行するとき、環境変数、バンドル構成ファイル内の別の場所、またはバンドルプロジェクトの .databricks/bundle/<target>/variable-overrides.json ファイルで設定する必要があります。変数の値の設定を参照してください。

変数の参照

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

YAML
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 コマンドの一部として、my_cluster_idという名前の変数に 1234-567890-abcde123 の値を指定し、my_notebook_pathという名前の変数に ./hello.py の値を指定するには、次のコマンドを実行します。
Bash
```
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_で始まる必要があります。環境変数を設定するには、オペレーティングシステムのドキュメントを参照してください。たとえば、my_cluster_idという名前の変数に 1234-567890-abcde123 の値を指定し、my_notebook_pathという名前の変数に ./hello.py の値を指定するには、validate、 deploy、 runなどの bundle コマンドを呼び出す前に、次のコマンドを実行します。

LinuxまたはmacOSの場合：
Bash
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
Windowsの場合：
Bash
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
または、validate、 deploy、 runなどの bundle コマンドの一部として変数の値を指定します (Linux や macOS など)。
Bash
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
または、Windowsの場合：
Bash
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
バンドル設定ファイル内で変数の値を指定するには、次の形式に従って、targetsマッピング内のvariablesマッピングを使用します。
YAML
```
variables:
  <variable-name>: <value>
```
たとえば、 my_cluster_id と my_notebook_path という名前の変数の値を 2 つの別々のターゲットに設定するには、次のようにします。
YAML
```
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/bundle/<target>/variable-overrides.jsonファイル内の変数の値を、次の形式で指定します。
JSON
```
{
  "<variable-name>": "<variable-value>"
}
```
たとえば、dev ターゲットの変数 ( my_cluster_id と my_notebook_path という名前の変数の値を指定するには、ファイル .databricks/bundle/dev/variable-overrides.json を作成し、その内容を次のように設定します。
JSON
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
variable-overrides.jsonファイルで複素変数を定義することもできます。

注記

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

優先順位

Databricks CLI は、次の順序で変数の値を検索し、変数の値を見つけると停止します。

bundleコマンドの一部として指定された任意の--varオプション内。
BUNDLE_VAR_で始まる任意の環境変数セット内。
variables-overrides.jsonファイル内 (存在する場合)。
バンドル構成ファイル内のtargetsマッピングのうち、任意のvariablesマッピング内。
その変数の定義の任意の default 値 (バンドル設定ファイル内の最上位の variables マッピング)。

複素数変数を定義する

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

注記

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

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

YAML
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

次の例に示すように、 .databricks/bundle/<target>/variable-overrides.json ファイルで複素変数を定義することもできます。

JSON
{
  "my_cluster": {
    "spark_version": "13.2.x-scala2.11",
    "node_type_id": "Standard_DS3_v2",
    "num_workers": 2
  }
}

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

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

YAML
variables:
  <variable-name>:
    lookup:
      <object-type>: '<object-name>'

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

注記

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

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

YAML
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}

出力置換と変数値

置換と変数が正しく指定され、Databricks Asset Bundle によって解析されるようにするには、 databricks bundle validateを実行します。バンドルの検証を参照してください。バンドルをデプロイするときに使用される値を表示するには、 --output json オプションを使用します。

Bash
databricks bundle validate --output json

例えば、変数 my_cluster_id が定義され、ジョブ・タスクで使用されるバンドルの場合、次のようになります。

YAML
bundle:
  name: variables_bundle

variables:
  my_cluster_id:
    default: 1234-567890-abcde123

resources:
  jobs:
    variables_bundle_job:
      name: variables_bundle_job
      tasks:
        - task_key: notebook_task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ../src/notebook.ipynb

databricks bundle validateスキーマ出力は次のようになります。

JSON
{
  "bundle": {
    "..."
    "name": "variables_bundle",
    "target": "dev",
  "..."
  },
  "resources": {
    "jobs": {
      "variables_bundle_job": {
        "deployment": {
          "kind": "BUNDLE",
          "metadata_file_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/state/metadata.json"
        },
        "max_concurrent_runs": 4,
        "name": "[dev someone] variables_bundle_job",
        "tasks": [
          {
            "existing_cluster_id": "1234-567890-abcde123",
            "notebook_task": {
              "notebook_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/files/variables_bundle/src/notebook"
            },
            "task_key": "notebook_task"
          },
        ],
      "..."
      }
    }
  },
  "..."
  "variables": {
    "my_cluster_id": {
      "default": "1234-567890-abcde123",
      "value": "1234-567890-abcde123"
    }
  },
"..."
}

代替品​

カスタム変数​

変数の参照​

変数の値を設定する​

優先順位​

複素数変数を定義する​

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

出力置換と変数値​

代替品