Condividi tramite

Sostituzioni e variabili personalizzate nei bundle di asset di Databricks

  • Articolo

I bundle di asset di Databricks supportano sostituzioni e variabili personalizzate, che rendono i file di configurazione del bundle più modulari e riutilizzabili. Sia le sostituzioni che le variabili personalizzate consentono il recupero dinamico dei valori in modo che le impostazioni possano essere determinate al momento dell’implementazione e dell'esecuzione di un bundle.

Suggerimento

È anche possibile usare riferimenti a valori dinamici per i valori dei parametri del processo per passare il contesto relativo a un'esecuzione del processo alle attività del processo. Vedere Configurare i parametri del task e Che cos'è un valore dinamico di riferimento?

Sostituzioni

È possibile usare le sostituzioni per recuperare i valori delle impostazioni che cambiano in base al contesto dell’implementazione e dell'esecuzione del bundle.

Ad esempio, quando si esegue il comandobundle validate --output json, è possibile che venga visualizzato un grafico simile al seguente:

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

Le sostituzioni possono essere usate per fare riferimento ai valori dei campi bundle name, bundle target e dell'area di lavoro userName per costruire l'area di lavoro root_path nel file di configurazione del bundle:

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

È anche possibile creare sostituzioni per le risorse denominate. Ad esempio, per la pipeline configurata con il nome my_pipeline, ${resources.pipelines.my_pipeline.target} è la sostituzione del valore della destinazione di my_pipeline.

Per determinare le sostituzioni valide, è possibile usare la gerarchia dello schema documentata nel riferimento all'API REST o nell'output del comando bundle schema.

Di seguito sono riportati alcune sostituzioni di uso comune:

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

Variabili personalizzate

Nel bundle è possibile definire variabili personalizzate semplici e complesse per abilitare il recupero dinamico dei valori necessari per molti scenari. Le variabili personalizzate vengono indicate nei file di configurazione del bundle nell’ambito del mapping variables. Si veda Variabili.

La seguente configurazione di esempio definisce le variabili my_cluster_id e 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

Se non si specifica un valore default per una variabile come parte di questa dichiarazione, è necessario impostarlo durante l'esecuzione di comandi bundle, tramite una variabile di ambiente o altrove all'interno dei file di configurazione del bundle, come descritto in Impostare il valore di una variabile.

Per fare riferimento a una variabile personalizzata all'interno della configurazione del bundle, usare la sostituzione della variabile ${var.<variable_name>}. Ad esempio, per fare riferimento alle variabili my_cluster_id e 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}

Impostare un valore della variabile

Se non è stato specificato un valore defaultper una variabile o se si desidera eseguire temporaneamente l'override del valore default per una variabile, specificare il nuovo valore temporaneo della variabile usando uno degli approcci seguenti:

  • Specificare il valore della variabile come parte di un comando bundle, ad esempio validate, deploy o run. A tale scopo, usare l'opzione --var="<key>=<value>", dove <key> è il nome della variabile e <value> è il valore della variabile. Ad esempio, come parte del comando bundle validate, per fornire il valore di 1234-567890-abcde123 alla variabile denominata my_cluster_id e per fornire il valore di ./hello.py alla variabile denominata my_notebook_path, eseguire:

    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"

  • Specificare il valore della variabile impostando una variabile di ambiente. I nomi delle variabili di ambiente devono iniziare con BUNDLE_VAR_. Per impostare le variabili di ambiente, si veda la documentazione relativa al sistema operativo Windows utilizzato. Ad esempio, per fornire il valore di 1234-567890-abcde123 alla variabile denominata my_cluster_id e il valore di ./hello.py alla variabile denominata my_notebook_path, eseguire il seguente comando prima di attivare un comando bundle, come validate, deploy oppure run:

    Per Linux e macOS:

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

    Per Windows:

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

    In alternativa, specificare il valore della variabile come parte di un comandobundle, ad esempio validate, deploy o run, per Linux e macOS:

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

    Oppure per Windows:

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

  • Specificare il valore della variabile all'interno dei file di configurazione del bundle. A tale scopo, usare un mapping variables all'interno del mappingtargets, seguendo questo formato:

    variables:
  <variable-name>: <value>

    Ad esempio, per fornire valori per le variabili denominate my_cluster_id e my_notebook_path per due destinazioni separate:

    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

Nota

Indipendentemente da quale sia l’approccio scelto per fornire valori di variabile, usare lo stesso approccio sia durante le fasi di distribuzione che in quelle di esecuzione. In caso contrario, è possibile ottenere risultati imprevisti tra il tempo di una distribuzione e un processo o un'esecuzione della pipeline basata su tale distribuzione esistente.

Negli esempi precedenti, l'interfaccia della riga di comando di Databricks cerca i valori per le variabili my_cluster_id e my_notebook_path nell'ordine seguente, arrestandosi quando trova un valore per ogni variabile corrispondente, ignorando eventuali altre posizioni per tale variabile:

  1. All'interno di qualsiasi opzione --var specificata come parte del comando bundle.
  2. All'interno di tutte le variabili di ambiente impostate che iniziano con BUNDLE_VAR_.
  3. All'interno di qualsiasi mapping variables, tra i mapping targets all'interno dei file di configurazione del bundle.
  4. Qualsiasi valore default per la definizione di tale variabile, tra i mapping variables di primo livello all'interno dei file di configurazione del bundle.

Definire una variabile complessa

Si presuppone che una variabile personalizzata sia di tipo stringa, a meno che non venga definita come variabile complessa. Per definire una variabile personalizzata con un tipo complesso per il bundle, impostare type su complex nella configurazione del bundle.

Nota

L'unico valore valido per l'impostazione type è complex. Inoltre, la convalida del bundle ha esito negativo se type è impostata su complex e l'oggetto default definito per la variabile è un singolo valore.

Nell'esempio seguente le impostazioni del cluster vengono definite all'interno di una variabile complessa personalizzata denominata 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

Recuperare il valore ID di un oggetto

Per i tipi di oggetto alert, cluster_policy, cluster, dashboard, instance_pool, job metastore, pipeline, query, service_principal e warehouse, è possibile definire un oggetto lookup per la variabile personalizzata per recuperare l'ID di un oggetto denominato usando questo formato:

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

Se viene definita una ricerca per una variabile, l'ID dell'oggetto con il nome specificato viene usato come valore della variabile. In questo modo, l'ID risolto corretto dell'oggetto viene sempre usato per la variabile.

Nota

Si verifica un errore se un oggetto con il nome specificato non esiste o se è presente più di un oggetto con il nome specificato.

Nella configurazione seguente, ad esempio, ${var.my_cluster_id} verrà sostituito dall'ID del cluster condiviso 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}