Substitusi dan variabel dalam Bundel Aset Databricks

Artikel
02/08/2025

Bundel Aset Databricks mendukung substitusi dan variabel kustom, yang membuat file konfigurasi bundel Anda lebih modular dan dapat digunakan kembali. Kedua substitusi dan variabel kustom memungkinkan pengambilan nilai dinamis sehingga pengaturan dapat ditentukan pada saat bundel disebarkan dan dijalankan.

Tip

Anda juga dapat menggunakan referensi nilai dinamis untuk nilai parameter pekerjaan untuk meneruskan konteks tentang pekerjaan yang dijalankan ke tugas pekerjaan. Lihat Apa itu referensi nilai dinamis? dan Membuat parameter pekerjaan.

Substitusi

Anda dapat menggunakan substitusi untuk mengambil nilai dari pengaturan yang berubah berdasarkan konteks penyebaran dan pelaksanaan bundel.

Misalnya, saat menjalankan bundle validate --output json perintah, Anda mungkin melihat grafik seperti ini:

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

Substitusi dapat digunakan untuk merujuk ke nilai bidang bundel name, bundel target, dan bidang ruang kerja userName untuk membangun ruang kerja root_path dalam file konfigurasi bundel.

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

Anda juga dapat membuat substitusi untuk sumber daya bernama. Misalnya, untuk alur yang dikonfigurasi dengan nama my_pipeline, ${resources.pipelines.my_pipeline.target} adalah penggantian untuk nilai target my_pipeline.

Untuk menentukan substitusi yang valid, Anda dapat menggunakan hierarki skema yang didokumentasikan dalam referensi REST API atau output perintah bundle schema.

Berikut adalah beberapa substitusi yang umum digunakan:

${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}

Variabel kustom

Anda dapat menentukan variabel kustom sederhana dan kompleks dalam bundel Anda untuk mengaktifkan pengambilan nilai dinamis yang diperlukan untuk banyak skenario. Variabel kustom dideklarasikan dalam file konfigurasi bundel Anda dalam pemetaan variables atau dalam file variable-overrides.json. Untuk informasi tentang pemetaan variables, lihat variabel .

Contoh konfigurasi berikut mendefinisikan variabel my_cluster_id dan 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

Jika Anda tidak memberikan nilai default untuk variabel sebagai bagian dari deklarasi ini, Anda harus mengaturnya saat menjalankan perintah bundel, melalui variabel lingkungan, atau di tempat lain dalam file konfigurasi bundel Anda seperti yang dijelaskan dalam Mengatur nilai variabel.

Anda juga dapat menentukan dan mengatur nilai variabel dalam file .databricks/bundle/<target>/variable-overrides.json dalam proyek bundel, di mana <target> adalah target ruang kerja, seperti dev. Lihat Mengatur nilai variabel.

Referensi variabel

Untuk mereferensikan variabel kustom dalam konfigurasi bundel Anda, gunakan substitusi. Misalnya, untuk mereferensikan variabel my_cluster_id dan 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}

Mengatur nilai variabel

Jika Anda belum memberikan default nilai untuk variabel, atau jika Anda ingin mengganti default nilai untuk variabel untuk sementara, berikan nilai sementara baru variabel menggunakan salah satu pendekatan berikut:

Berikan nilai variabel sebagai bagian bundle dari perintah seperti validate, , deployatau run. Untuk melakukan ini, gunakan opsi --var="<key>=<value>", di mana <key> adalah nama variabel, dan <value> adalah nilai variabel. Misalnya, sebagai bagian bundle validate dari perintah, untuk memberikan nilai ke 1234-567890-abcde123 variabel bernama my_cluster_id, dan untuk memberikan nilai ./hello.py ke variabel bernama my_notebook_path, jalankan:
```
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"
```
Berikan nilai variabel dengan mengatur variabel lingkungan. Nama variabel lingkungan harus dimulai dengan BUNDLE_VAR_. Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda. Misalnya, untuk memberikan nilai 1234-567890-abcde123 ke variabel bernama my_cluster_id, dan untuk memberikan nilai ./hello.py ke variabel bernama my_notebook_path, jalankan perintah berikut sebelum Anda memanggil bundle perintah seperti validate, deploy, atau run:

Untuk Linux dan macOS:
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
Untuk Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
Atau, berikan nilai variabel sebagai bagian bundle dari perintah seperti validate, , deployatau run, misalnya untuk Linux dan macOS:
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
Atau untuk Windows:
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```
Berikan nilai variabel dalam file konfigurasi bundel Anda menggunakan pemetaan variables dalam pemetaan targets, dengan mengikuti format ini:
```
variables:
  <variable-name>: <value>
```
Misalnya, untuk mengatur nilai untuk variabel bernama my_cluster_id dan my_notebook_path untuk dua target terpisah:
```
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
```
Berikan nilai variabel dalam file .databricks/bundle/<target>/variable-overrides.json, menggunakan format berikut:
```
{
  "<variable-name>": "<variable-value>"
}
```
Misalnya, untuk memberikan nilai untuk variabel bernama my_cluster_id dan my_notebook_path untuk target dev, buat file .databricks/bundle/dev/variable-overrides.json dan atur kontennya ke:
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
Anda juga dapat menentukan variabel kompleks dalam file variable-overrides.json.

Catatan

Pendekatan apa pun yang Anda pilih untuk memberikan nilai variabel, gunakan pendekatan yang sama selama tahap penyebaran dan eksekusi. Jika tidak, Anda mungkin mendapatkan hasil yang tidak terduga antara waktu penyebaran dan pekerjaan atau operasi alur yang bergantung pada penyebaran tersebut.

Urutan prioritas

Databricks CLI mencari nilai untuk variabel dalam urutan berikut, berhenti saat menemukan nilai untuk variabel:

Dalam opsi apa pun --var yang ditentukan sebagai bagian bundle dari perintah.
Dalam variabel lingkungan apa pun yang dimulai dengan BUNDLE_VAR_.
Dalam file variables-overrides.json, jika ada.
Dalam pemetaan apa pun variables , di targets antara pemetaan dalam file konfigurasi bundel Anda.
Nilai apa pun default untuk definisi variabel tersebut, di antara pemetaan tingkat variables atas dalam file konfigurasi bundel Anda.

Menentukan variabel kompleks

Variabel kustom diasumsikan berjenis string kecuali Anda mendefinisikannya sebagai variabel kompleks. Untuk menentukan variabel kustom dengan jenis kompleks untuk bundel Anda dalam konfigurasi bundel Anda, atur type ke complex.

Catatan

Satu-satunya nilai yang type valid untuk pengaturan adalah complex. Selain itu, validasi bundel gagal jika type diatur ke complex dan default yang ditentukan untuk variabel adalah nilai tunggal.

Dalam contoh berikut, pengaturan kluster didefinisikan dalam variabel kompleks kustom bernama 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

Anda juga dapat menentukan variabel kompleks dalam file .databricks/bundles/<target>/variable-overrides.json, seperti yang ditunjukkan dalam contoh berikut:

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

Mengambil nilai ID objek

Untuk alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal, dan jenis objek warehouse, Anda dapat menentukan lookup untuk variabel kustom Anda untuk mengambil ID objek bernama menggunakan format ini:

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

Jika pencarian didefinisikan untuk variabel, ID objek dengan nama yang ditentukan digunakan sebagai nilai variabel. Ini memastikan ID objek yang diselesaikan dengan benar selalu digunakan untuk variabel.

Catatan

Kesalahan terjadi jika objek dengan nama yang ditentukan tidak ada, atau jika ada lebih dari satu objek dengan nama yang ditentukan.

Misalnya, dalam konfigurasi berikut, ${var.my_cluster_id} akan digantikan oleh ID kluster bersama 12.2.

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}

Bagikan melalui

Substitusi dan variabel dalam Bundel Aset Databricks

Substitusi

Variabel kustom

Referensi variabel

Mengatur nilai variabel

Urutan prioritas

Menentukan variabel kompleks

Mengambil nilai ID objek

Saran dan Komentar

Sumber Daya Tambahan: