Bildirim temelli Otomasyon Paketlerindeki değişimler ve değişkenler

Bildirim temelli Otomasyon Paketleri (eski adıyla Databricks Varlık Paketleri), değişimleri ve özel değişkenleri destekler ve bu da paket yapılandırma dosyalarınızı daha modüler ve yeniden kullanılabilir hale getirir. Hem değiştirmeler hem de özel değişkenler, değerlerin dinamik olarak alınmasını sağlar, böylece ayarlar paket dağıtıldığında ve çalıştırıldığında belirlenebilir.

İpucu

Ayrıca, bir iş çalıştırması hakkındaki bağlamı iş görevlerine geçirmek için iş parametresi değerleri için dinamik değer başvuruları da kullanabilirsiniz. Bakınız Dinamik değer başvurusu nedir? ve İşleri parametreleştirme.

Değişimler

Değişimleri, paket dağıtımının bağlamı temelinde değişebilecek ayarların değerlerini almak ve çalıştırmak için kullanabilirsiniz. Örneğin, paket yapılandırma dosyasında çalışma alanını name oluşturmak için pakettarget, paket userNameve çalışma alanı root_path alanlarının değerlerine başvurmak için alt bileşenler kullanılabilir:

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Eğer someone@example.com bu paketi dağıtsaydı, kök yoluna /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev dağıtılacaktı.

Adlandırılmış kaynaklar için yedekler de oluşturabilirsiniz. Örneğin, aşağıdaki işlem hattı tanımı için işlem hattının hedefinin değeri için kullanabilirsiniz ${resources.pipelines.my_pipeline.target} :

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

Geçerli değiştirmeleri belirlemek için paket yapılandırma başvurusunu, kaynak yapılandırma başvurusunu veya REST API başvurusunda belgelenen ilgili nesnelerin şema hiyerarşisini veya komutun çıkışını bundle schema kullanın.

İpucu

Kaynaklar için kullanılabilen değiştirmelerin tam listesi için bkz. Databricks CLI GitHub deposu out.fields.txt

Yaygın olarak kullanılan bazı değiştirmeler şunlardır:

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

Özel değişkenler

Birçok senaryo için gereken değerlerin dinamik olarak alınmasını sağlamak için paketinizde hem basit hem de karmaşık özel değişkenler tanımlayabilirsiniz. Özel değişkenler, paket yapılandırma dosyalarınızda variables eşlemesinde veya variable-overrides.json dosyasında bildirilir. variables eşlemesi hakkında bilgi için bkz. değişkenleri.

Aşağıdaki örnek yapılandırma, my_cluster_id ve my_notebook_path değişkenlerini tanımlar.

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

Bu bildirimin bir parçası olarak bir değişken için değer default sağlamazsanız paket komutlarını yürütürken, bir ortam değişkeni aracılığıyla, paket yapılandırma dosyalarınızın içinde başka bir yerde veya .databricks/bundle/<target>/variable-overrides.json paket projesindeki dosyada bunu ayarlamanız gerekir. Bkz. Değişkenin değerini ayarlama.

Bir değişkene referans verin

Paket yapılandırmanızda özel bir değişkene başvurmak için değişken değiştirmesini${var.<variable_name>}kullanın. Örneğin, aşağıdaki yapılandırma my_cluster_id ve my_notebook_path değişkenlerine başvurur.

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}

Değişkenin değerini ayarlama

Bir değişken için değer default ayarlamadıysanız veya bir değişkenin default değerini geçici olarak geçersiz kılmak istiyorsanız, aşağıdaki yaklaşımlardan birini kullanarak değişkenin yeni geçici değerini sağlayın.

Not

Paket değişkenleri dağıtım zamanı değişkenleridir. Paketi dağıttığınızda bunlar yorumlanır. Örneğin, bir işi çalıştırdığınızda, daha önce dağıtılan bir işi ve bu dağıtım için yapılandırılmış değişkenleri çalıştırır, bu nedenle işin çalıştırılması için değişkenler için farklı değerler geçirmek geçerli olmaz. Bunun yerine, iş parametrelerini kullanarak değerleri bir iş çalıştırmasına iletin. Bkz İş parametrelerini geçirme.

  • Değişkenin değerini bundle, validate veya deploy gibi bir komutun parçası olarak run ile sağlayın. Bunu yapmak için, --var="<key>=<value>" seçeneğini, <key> değişkenin adı ve <value> değişkenin değeri olarak kullanın. Örneğin, bundle validate komutunun bir parçası olarak, 1234-567890-abcde123 adlı değişkene my_cluster_id değerini ve ./hello.py adlı değişkene my_notebook_path değerini sağlamak için komutunu çalıştırın.

    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"

  • Ortam değişkeni ayarlayarak değişkenin değerini sağlayın. Ortam değişkeninin adı ile BUNDLE_VAR_başlamalıdır. Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın. Örneğin, 1234-567890-abcde123 değerini my_cluster_id adlı değişkene ve ./hello.py değerini my_notebook_path adlı değişkene sağlamak için, bundle gibi bir validate, deploy veya run komutunu çağırmadan önce aşağıdaki komutu çalıştırın:

    Linux ve macOS için:

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

    Windows için:

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

    Veya değişkenin değerini, bundle komutunun bir parçası olarak validate, deploy veya run gibi sağlayın; örneğin, Linux ve macOS için:

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

    Veya Windows için:

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

  • Paket yapılandırma dosyalarınızda, variables eşlemesi içerisindeki targets eşlemesini kullanarak değişkenin değerini aşağıdaki biçimde sağlayın:

    variables:
  <variable-name>: <value>

    Örneğin, iki ayrı hedef için my_cluster_id ve my_notebook_path adlı değişkenlerin değerlerini ayarlamak için:

    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

  • Aşağıdaki biçimi kullanarak değişkenin .databricks/bundle/<target>/variable-overrides.json değerini dosya içinde sağlayın:

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

    Örneğin, geliştirme hedefi için my_cluster_id ve my_notebook_path adlı değişkenlere değer sağlamak için bir dosya .databricks/bundle/dev/variable-overrides.json oluşturun ve içeriğini şu şekilde ayarlayın:

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

    Karmaşık değişkenleri variable-overrides.json dosyasında da tanımlayabilirsiniz.

Not

Sağladığınız değişken değerleri için hangi yaklaşımı seçerseniz seçin, dağıtım ve çalıştırma aşamalarında aynı yöntemi kullanın. Aksi takdirde, bir dağıtımın zamanı ile mevcut dağıtımı temel alan bir iş veya işlem hattı çalıştırması arasında beklenmeyen sonuçlar alabilirsiniz.

Öncelik sırası

Databricks CLI, değişkenlerin değerlerini aşağıdaki sırayla arar ve bir değişken için değer bulduğunda durduruluyor:

  1. Komutta belirtilen seçeneklerden herhangi biri içinde --varbundle.
  2. ile BUNDLE_VAR_başlayan tüm ortam değişkenleri kümesi içinde.
  3. varsa, variable-overrides.json dosyasının içinde.
  4. Paket yapılandırma dosyalarınızın içindeki variables eşlemelerinden herhangi birinin içinde, targets eşlemeleri arasında.
  5. Paket yapılandırma dosyalarınızdaki en üst düzey default eşlemeler arasında bu değişkenin tanımı için herhangi bir variables değer.

Karmaşık değişken tanımlama

Özel değişkenin, karmaşık bir değişken olarak tanımlamadığınız sürece dize türünde olduğu varsayılır. Paket yapılandırmanızda paketinize yönelik karmaşık bir türe sahip özel bir değişken tanımlamak için typecomplexolarak ayarlayın.

Not

Ayar için type tek geçerli değer olur complex. Şayet typecomplex olarak ayarlanmışsa ve değişken için tanımlanan default tek bir değer ise, paket doğrulaması başarısız olur.

Aşağıdaki örnekte, küme ayarları adlı my_clusterözel bir karmaşık değişken içinde tanımlanır:

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

Aşağıdaki örnekte gösterildiği gibi .databricks/bundle/<target>/variable-overrides.json dosyasında da karmaşık bir değişken tanımlayabilirsiniz:

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

Nesnenin kimlik değerini alma

alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal, ve warehouse nesne türleri için, adlandırılmış bir nesnenin kimliğini almak için özel değişkeniniz için lookup şu biçimi kullanarak tanımlayabilirsiniz:

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

Bir değişken için arama tanımlanmışsa, değişkenin değeri olarak belirtilen ada sahip nesnenin kimliği kullanılır. Bu, değişken için nesnenin doğru çözümlenmiş kimliğinin her zaman kullanılmasını sağlar.

Not

Belirtilen ada sahip bir nesne yoksa veya belirtilen ada sahip birden fazla nesne varsa hata oluşur.

Örneğin, aşağıdaki yapılandırmada, ${var.my_cluster_id} 12.2 paylaşılan kümesinin kimliğiyle değiştirilecektir.

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}

Çıkış değiştirme ve değişken değerleri

Değiştirmelerinizin ve değişkenlerinizin Bildirim temelli Otomasyon Paketleri tarafından doğru şekilde belirtildiğinden ve ayrıştırıldığından emin olmak için komutunu çalıştırın databricks bundle validate. Bkz. databricks paketi doğrulama. Paket dağıtırken kullanılacak değerleri görüntülemek için şu --output json seçeneği kullanın:

databricks bundle validate --output json

Örneğin, bir iş görevinde tanımlanan ve kullanılan değişkene my_cluster_id sahip bir paket için:

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

Şema çıktısı databricks bundle validate aşağıdaki gibi olacaktır:

{
  "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