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 マッピング内または variable-overrides.json ファイルで宣言されます。 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値を指定しない場合は、「変数の値を設定する」で説明されているように、バンドルコマンドを実行するときに、環境変数を通じて、またはバンドル構成ファイル内の他の場所で、値を設定する必要があります。

また、バンドルプロジェクトの .databricks/bundle/<target>/variable-overrides.json ファイルで変数値を定義および設定することもできます。ここで、 <target> はワークスペースのターゲット ( devなど) です。 変数の値の設定を参照してください。

変数の参照

バンドル設定内でカスタム変数を参照するには、変数置換${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>

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

    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ファイル内の変数の値を、次の形式で指定します。

    {
  "<variable-name>": "<variable-value>"
}

    たとえば、dev ターゲットの 変数 ( my_cluster_id と my_notebook_path という名前の変数の値を指定するには、ファイル .databricks/bundle/dev/variable-overrides.json を作成し、その内容を次のように設定します。

    {
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}

    variable-overrides.jsonファイルで複素変数を定義することもできます。

注：

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

優先順位

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

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

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

  3. variables-overrides.jsonファイル内 (存在する場合)。

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

  5. バンドル構成ファイル内の最上位の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

次の例に示すように、 .databricks/bundles/<target>/variable-overrides.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 を取得できます。

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}