Substytucje i zmienne w pakietach zasobów Databricks

Pakiety zasobów Databricks obsługują substytucje i zmienne niestandardowe, co sprawia, że konfiguracja pakietów jest bardziej modułowa i wielokrotnego użytku. Zarówno podstawianie, jak i zmienne niestandardowe umożliwiają dynamiczne pobieranie wartości, dzięki czemu ustawienia można określić w momencie wdrażania i uruchamiania pakietu.

Zastępstwa

Można użyć podstawień, aby pobrać wartości ustawień, które mogą ulec zmianie na podstawie kontekstu wdrożenia pakietu i uruchomienia. Na przykład substytucje mogą służyć do odwoływania się do wartości pól pakietu name, pakietu target, i obszaru roboczego userName w celu skonstruowania obszaru roboczego root_path w pliku konfiguracji pakietu.

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Jeśli someone@example.com wdrożyłby ten pakiet, zostałby wdrożony w ścieżce głównej /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev.

Można również tworzyć zamienniki dla nazwanych zasobów. Na przykład dla następującej definicji potoku należy użyć ${resources.pipelines.my_pipeline.target} dla wartości docelowej potoku.

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

Aby określić właściwe zamienniki, użyj odwołania do konfiguracji pakietu, odwołania do konfiguracji zasobów lub hierarchii schematu odpowiednich obiektów udokumentowanych w odwołaniach do API REST lub wyniku polecenia bundle schema.

Oto niektóre często używane zamienniki:

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

Zmienne niestandardowe

W pakiecie można zdefiniować zarówno proste, jak i złożone zmienne niestandardowe, aby umożliwić dynamiczne pobieranie wartości wymaganych w wielu scenariuszach. Zmienne własne są deklarowane w plikach konfiguracji pakietu w ramach mapowania variables lub w pliku variable-overrides.json. Aby uzyskać informacje na temat mapowania variables, zobacz zmienne .

Poniższa przykładowa konfiguracja definiuje zmienne my_cluster_id i 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

Jeśli nie podasz default wartości zmiennej w ramach tej deklaracji, musisz ustawić ją podczas wykonywania poleceń pakietu, za pomocą zmiennej środowiskowej, gdzie indziej w plikach konfiguracji pakietu lub w .databricks/bundle/<target>/variable-overrides.json pliku w projekcie pakietu. Zobacz Ustawianie wartości zmiennej.

Referencja do zmiennej

Aby odwołać się do zmiennej niestandardowej w ramach konfiguracji pakietu, użyj zmiennej substitution${var.<variable_name>}. Na przykład następująca konfiguracja odwołuje się do zmiennych my_cluster_id i 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}

Ustawianie wartości zmiennej

Jeśli nie ustawiono default wartości dla zmiennej lub jeśli chcesz tymczasowo zastąpić default wartość zmiennej, podaj nową wartość tymczasową zmiennej przy użyciu jednej z poniższych metod.

• Podaj wartość zmiennej w ramach bundle polecenia, takiego jak validate, deploylub run. W tym celu użyj opcji --var="<key>=<value>", gdzie <key> jest nazwą zmiennej i <value> jest wartością zmiennej. Na przykład w ramach polecenia bundle validate, aby przypisać wartość 1234-567890-abcde123 do zmiennej o nazwie my_cluster_id, a wartość ./hello.py do zmiennej o nazwie my_notebook_path, uruchom:

  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"
  

• Podaj wartość zmiennej, ustawiając zmienną środowiskową. Nazwa zmiennej środowiskowej musi zaczynać się od BUNDLE_VAR_. Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego. Aby na przykład podać wartość 1234-567890-abcde123 do zmiennej o nazwie my_cluster_id, i podać wartość ./hello.py do zmiennej o nazwie my_notebook_path, uruchom następujące polecenie przed wywołaniem polecenia bundle, takiego jak validate, deploy lub run.

  W przypadku systemów Linux i macOS:

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

  Dla systemu Windows:

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

  Możesz też podać wartość zmiennej w ramach bundle polecenia, takiego jak validate, deploylub run, na przykład dla systemów Linux i macOS:

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

  Lub dla systemu Windows:

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

• Podaj wartość zmiennej w plikach konfiguracji pakietu, korzystając z mapowania variables w ramach mapowania targets, zgodnie z tym formatem.

  variables:
    <variable-name>: <value>
  

  Aby na przykład ustawić wartości zmiennych o nazwie my_cluster_id i my_notebook_path dla dwóch oddzielnych obiektów docelowych:

  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
  

• Podaj wartość zmiennej w .databricks/bundle/<target>/variable-overrides.json pliku przy użyciu następującego formatu:

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

  Aby na przykład podać wartości zmiennych o nazwie my_cluster_id i my_notebook_path dla obiektu docelowego dewelopera, utwórz plik .databricks/bundle/dev/variable-overrides.json i ustaw jego zawartość na:

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

  Można również zdefiniować złożone zmienne w pliku variable-overrides.json.

Kolejność pierwszeństwa

Interfejs wiersza polecenia usługi Databricks wyszukuje wartości zmiennych w następującej kolejności, zatrzymując się po znalezieniu wartości zmiennej:

1. W ramach dowolnych --var opcji określonych jako część bundle polecenia.
2. W dowolnym zestawie zmiennych środowiskowych rozpoczynających się od BUNDLE_VAR_.
3. W pliku variables-overrides.json, jeśli istnieje.
4. W ramach jakiegokolwiek variables mapowania, wśród targets mapowań w plikach konfiguracji pakietu.
5. Dowolna default wartość definicji tej zmiennej wśród mapowań najwyższego poziomu variables w plikach konfiguracji pakietu.

Definiowanie zmiennej złożonej

Przyjmuje się, że zmienna niestandardowa jest ciągiem typu, chyba że zostanie zdefiniowana jako zmienna zespolona. Aby zdefiniować zmienną niestandardową o złożonym typie dla swojego pakietu w konfiguracji pakietu, ustaw type na complex.

W poniższym przykładzie ustawienia klastra są definiowane w niestandardowej zmiennej złożonej o nazwie 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

Można również zdefiniować zmienną złożoną w pliku .databricks/bundle/<target>/variable-overrides.json, jak pokazano w poniższym przykładzie:

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

Pobieranie wartości identyfikatora obiektu

Dla typów obiektów alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal i warehouse można zdefiniować lookup dla zmiennej niestandardowej, aby pobrać identyfikator nazwanego obiektu przy użyciu tego formatu.

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

Jeśli wyszukiwanie jest zdefiniowane dla zmiennej, identyfikator obiektu o określonej nazwie jest używany jako wartość zmiennej. Gwarantuje to, że prawidłowy rozpoznany identyfikator obiektu jest zawsze używany dla zmiennej.

Na przykład w poniższej konfiguracji ${var.my_cluster_id} zostanie zastąpiony identyfikatorem klastra 12.2 shared.

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}

Podstawianie danych wyjściowych i wartości zmiennych

Aby upewnić się, że substytucje i zmienne są poprawnie określone i przeanalizowane przez opakowania zasobów usługi Databricks, uruchom polecenie databricks bundle validate. Zobacz sprawdzanie poprawności pakietu usługi databricks. Aby wyświetlić wartości, które będą używane podczas wdrażania pakietu, użyj --output json opcji:

databricks bundle validate --output json

Na przykład w przypadku pakietu ze zmienną my_cluster_id zdefiniowaną i użytą w zadaniu:

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

Dane databricks bundle validate wyjściowe schematu będą następujące:

{
  "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"
    }
  },
"..."
}