Bagikan melalui

Substitusi dan variabel dalam Bundel Aset Databricks

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.

Petunjuk

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.

Penggantian

Anda dapat menggunakan substitusi untuk mengambil nilai pengaturan yang dapat berubah berdasarkan konteks penyebaran dan pelaksanaan bundel. Misalnya, substitusi dapat digunakan untuk merujuk ke nilai bidang bundel name, bundel target, dan ruang kerja userName untuk membangun ruang kerja root_path dalam file konfigurasi bundel.

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Jika someone@example.com disebarkan, bundel ini akan disebarkan ke jalur akar /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev.

Anda juga dapat membuat substitusi untuk sumber daya bernama. Misalnya, untuk definisi alur berikut, Anda dapat menggunakan ${resources.pipelines.my_pipeline.target} untuk nilai target alur:

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

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

Untuk menentukan substitusi yang valid, gunakan referensi konfigurasi bundel, referensi konfigurasi sumber daya atau hierarki skema objek terkait yang didokumentasikan dalam referensi REST API, atau output bundle schema perintah.

Petunjuk

Untuk daftar lengkap substitusi yang tersedia untuk sumber daya, lihat Repositori GitHub Databricks CLI out.fields.txt

Berikut adalah beberapa substitusi yang umum digunakan:

  • ${bundle.name}
  • ${bundle.target} # Use this substitution instead of ${bundle.environment}
  • ${workspace.host}
  • ${workspace.current_user.domain_friendly_name}
  • ${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 default nilai untuk variabel sebagai bagian dari deklarasi ini, Anda harus mengaturnya saat menjalankan perintah bundel, melalui variabel lingkungan, di tempat lain dalam file konfigurasi bundel Anda, atau dalam .databricks/bundle/<target>/variable-overrides.json file dalam proyek bundel. Lihat Mengatur nilai variabel.

Referensi variabel

Untuk mereferensikan variabel kustom dalam konfigurasi bundel Anda, gunakan variabel substitusi${var.<variable_name>}. Misalnya, konfigurasi berikut 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 menetapkan 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.

Catatan

Variabel bundel adalah variabel waktu penyebaran. Mereka ditafsirkan saat Anda menyebarkan bundel. Misalnya, ketika Anda menjalankan suatu pekerjaan, Anda menjalankan pekerjaan yang sebelumnya telah disebarkan beserta variabel yang sudah dikonfigurasi untuk penyebaran tersebut, sehingga memberikan nilai yang berbeda untuk variabel saat menjalankan pekerjaan tidak akan mengubah hasilnya. Sebagai gantinya, teruskan nilai ke pekerjaan yang dijalankan menggunakan parameter pekerjaan. Lihat Meneruskan parameter pekerjaan.

  • 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> merupakan nilai variabel. Misalnya, sebagai bagian dari perintah bundle validate, untuk memberikan nilai 1234-567890-abcde123 kepada variabel bernama my_cluster_id, dan untuk memberikan nilai ./hello.py kepada 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 dengan menggunakan pemetaan variables di dalam pemetaan targets, sesuai dengan format berikut:

    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 .databricks/bundle/<target>/variable-overrides.json file, 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:

  1. Dalam opsi apa pun --var yang ditentukan sebagai bagian bundle dari perintah.
  2. Dalam variabel lingkungan apa pun yang dimulai dengan BUNDLE_VAR_.
  3. Dalam file variables-overrides.json, jika ada.
  4. Dalam pemetaan apa pun variables , di targets antara pemetaan dalam file konfigurasi bundel Anda.
  5. 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

Nilai satu-satunya yang valid untuk pengaturan adalah type. 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/bundle/<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

alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal, dan warehouse adalah jenis objek untuk mana 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}

Substitusi output dan nilai variabel

Untuk memastikan substitusi dan variabel Anda ditentukan dengan benar dan diurai oleh Bundel Aset Databricks, jalankan databricks bundle validate. Lihat databricks bundle validate. Untuk melihat nilai yang akan digunakan saat Anda menyebarkan bundel, gunakan --output json opsi :

databricks bundle validate --output json

Misalnya, untuk bundel dengan variabel my_cluster_id yang ditentukan dan digunakan dalam tugas pekerjaan:

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

Output dari skema databricks bundle validate adalah sebagai berikut:

{
  "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"
    }
  },
"..."
}
  • Last updated on