Ersättningar och variabler i Databricks-tillgångspaket

Databricks Asset Bundles stöder ersättningar och anpassade variabler, vilket gör paketkonfigurationsfilerna mer modulära och återanvändbara. Både substitutioner och anpassade variabler möjliggör dynamisk hämtning av värden så att inställningarna kan fastställas när ett paket distribueras och körs.

Substitutioner

Du kan använda ersättningar för att hämta värden för inställningar som ändras baserat på kontexten för paketdistributionen och körningen.

När du till exempel kör bundle validate --output json kommandot kan du se ett diagram som liknar detta:

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

Undertabeller kan användas för att referera till värdena för fälten bundle name, bundle targetoch workspace userName för att konstruera arbetsytan root_path i paketkonfigurationsfilen:

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

Du kan också skapa ersättningar för namngivna resurser. Till exempel för pipelinen som konfigurerats med namnet my_pipeline, ${resources.pipelines.my_pipeline.target} är ersättningen för värdet för målet my_pipelineför .

För att fastställa giltiga ersättningar kan du använda schemahierarkin som beskrivs i REST API-referensen eller utdata från bundle schema kommandot.

Här är några vanliga ersättningar:

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

Anpassade variabler

Du kan definiera både enkla och komplexa anpassade variabler i ditt paket för att aktivera dynamisk hämtning av värden som behövs för många scenarier. Anpassade variabler deklareras i paketkonfigurationsfilerna i mappningen variables . Se variabler.

Följande exempelkonfiguration definierar variablerna my_cluster_id och 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

Om du inte anger ett default värde för en variabel som en del av den här deklarationen måste du ange det när du kör paketkommandon, via en miljövariabel eller någon annanstans i paketkonfigurationsfilerna enligt beskrivningen i Ange en variabels värde.

Om du vill referera till en anpassad variabel i paketkonfigurationen använder du variabelersättningen ${var.<variable_name>}. Om du till exempel vill referera till variablerna my_cluster_id och 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}

Ange en variabels värde

Om du inte har angett något default värde för en variabel, eller om du tillfälligt vill åsidosätta default värdet för en variabel, anger du variabelns nya temporära värde med någon av följande metoder:

• Ange variabelns värde som en del av ett bundle kommando, till exempel validate, deployeller run. Om du vill göra detta använder du alternativet --var="<key>=<value>", där <key> är variabelns namn och <value> är variabelns värde. Som en del av bundle validate kommandot kan du till exempel ange värdet 1234-567890-abcde123 för variabeln med namnet my_cluster_idoch ange värdet ./hello.py för variabeln med namnet my_notebook_path, kör:

  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"
  

• Ange variabelns värde genom att ange en miljövariabel. Miljövariabelns namn måste börja med BUNDLE_VAR_. Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet. Om du till exempel vill ange värdet 1234-567890-abcde123 för variabeln med namnet my_cluster_idoch ange värdet ./hello.py för variabeln med namnet my_notebook_pathkör du följande kommando innan du anropar ett bundle kommando som validate, deployeller run:

  För Linux och macOS:

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

  För Windows:

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

  Eller ange variabelns värde som en del av ett bundle kommando som validate, deployeller run, till exempel för Linux och macOS:

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

  Eller för Windows:

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

• Ange variabelns värde i paketkonfigurationsfilerna. Det gör du genom att använda en variables mappning i mappningen targets enligt det här formatet:

  variables:
    <variable-name>: <value>
  

  Om du till exempel vill ange värden för variablerna med namnet my_cluster_id och my_notebook_path för två separata mål:

  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
  

I föregående exempel letar Databricks CLI efter värden för variablerna my_cluster_id och my_notebook_path i följande ordning stoppar du när det hittar ett värde för varje matchande variabel och hoppar över andra platser för variabeln:

1. Inom alla --var alternativ som anges som en del av bundle kommandot.
2. I alla miljövariabler som börjar med BUNDLE_VAR_.
3. I alla variables mappningar, bland mappningarna targets i paketkonfigurationsfilerna.
4. Valfritt default värde för variabelns definition, bland de översta mappningarna variables i paketkonfigurationsfilerna.

Definiera en komplex variabel

En anpassad variabel antas vara av typen sträng om du inte definierar den som en komplex variabel. Om du vill definiera en anpassad variabel med en komplex typ för ditt paket anger du type till complex i paketkonfigurationen.

I följande exempel definieras klusterinställningar i en anpassad komplex variabel med namnet 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

Hämta ett objekts ID-värde

För objekttyperna alert, cluster_policy, cluster, instance_pooldashboard, job, metastore, pipeline, service_principalqueryoch warehouse kan du definiera en lookup för din anpassade variabel för att hämta ett namngivet objekts ID med det här formatet:

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

Om en sökning har definierats för en variabel används ID:t för objektet med det angivna namnet som värdet för variabeln. Detta säkerställer att rätt löst ID för objektet alltid används för variabeln.

I följande konfiguration ${var.my_cluster_id} ersätts till exempel med ID:t för det delade klustret 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}