Helyettesítések és változók a Databricks-eszközcsomagokban

A Databricks Asset Bundles támogatja a helyettesítéseket és az egyéni változókat, amelyek modulárisabbá és újrafelhasználhatóbbá teszik a csomagkonfigurációs fájlokat. A helyettesítések és az egyéni változók egyaránt lehetővé teszik az értékek dinamikus lekérését, hogy a beállítások meghatározhatók legyenek a csomag üzembe helyezésekor és futtatásakor.

Helyettesítések

A helyettesítésekkel lekérheti a csomag üzembe helyezésének és futtatásának kontextusa alapján változó beállítások értékeit.

A parancs futtatásakor bundle validate --output json például egy ilyen gráf jelenhet meg:

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

Az aldokumentumok a köteg name, a köteg targetés a munkaterület userName mezőinek értékeire hivatkozva hozhatják létre a munkaterületet root_path a csomagkonfigurációs fájlban:

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

A névvel ellátott erőforrásokhoz helyettesítőket is létrehozhat. A névvel my_pipeline${resources.pipelines.my_pipeline.target} konfigurált folyamat esetében például a célérték helyettesítésemy_pipeline.

Az érvényes helyettesítések meghatározásához használhatja a REST API-referenciában vagy a

Íme néhány gyakran használt helyettesítés:

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

Egyéni változók

A csomagban egyszerű és összetett egyéni változókat is meghatározhat, így számos forgatókönyvhöz szükséges értékek dinamikus lekérését teheti lehetővé. Az egyéni változók deklarálva vannak a csomagkonfigurációs fájlokban a variables leképezésben vagy egy variable-overrides.json fájlban. A variables leképezésről további információért lásd a változókat.

A következő példakonfiguráció határozza meg a változókat my_cluster_id és my_notebook_patha következőket:

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

Ha a deklaráció részeként nem ad meg default értéket egy változóhoz, akkor azt csomagparancsok végrehajtásakor, környezeti változón vagy a csomagkonfigurációs fájlok más részein kell beállítania a változó értékének beállítása című cikkben leírtak szerint.

A kötegprojekt .databricks/bundle/<target>/variable-overrides.json fájljában is definiálhat és állíthat be változóértékeket, ahol <target> a munkaterület célja, például dev. Lásd: Változó értékének beállítása.

Hivatkozás egy változóra

Ha egyéni változóra szeretne hivatkozni a csomagkonfigurációban, használja a változó helyettesítését${var.<variable_name>}. Például a változókra my_cluster_id való hivatkozáshoz és my_notebook_patha következőhöz:

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}

Változó értékének beállítása

Ha nem adott meg default értéket egy változóhoz, vagy ha ideiglenesen felül szeretné bírálni default egy változó értékét, adja meg a változó új ideiglenes értékét az alábbi módszerek egyikével:

• Adja meg a változó értékét egy bundle parancs részeként, például validate: , deployvagy run. Ehhez használja azt a lehetőséget --var="<key>=<value>", amely <key> a változó neve, és <value> a változó értéke. Ha például a bundle validate parancs részeként meg szeretné adni a névvel ellátott 1234-567890-abcde123változó értékétmy_cluster_id, és meg szeretné adni a névvel ellátott ./hello.pyváltozó értékétmy_notebook_path, futtassa a következőt:

  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"
  

• Adja meg a változó értékét egy környezeti változó beállításával. A környezeti változó nevének a következővel BUNDLE_VAR_kell kezdődnie: . A környezeti változók beállításához tekintse meg az operációs rendszer dokumentációját. Ha például meg szeretné adni a névvel ellátott változó értékét1234-567890-abcde123, és meg szeretné adni a névvel ellátott my_cluster_idváltozó értékét./hello.py, futtassa a következő parancsot, mielőtt meghívna egy my_notebook_path parancsot, példáulbundle: validatedeployrun

  Linux és macOS esetén:

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

  Windows esetén:

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

  Vagy adja meg a változó értékét egy bundle parancs részeként, például validatedeployLinux és runmacOS esetén:

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

  Vagy Windows esetén:

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

• Adja meg a változó értékét a csomagkonfigurációs fájlokban a targets leképezésen belüli variables leképezéssel, az alábbi formátum szerint:

  variables:
    <variable-name>: <value>
  

  Ha például a my_cluster_id nevű változók értékeit szeretné beállítani, és my_notebook_path két különálló célhoz:

  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
  

• Adja meg a változó értékét a .databricks/bundle/<target>/variable-overrides.json fájlban a következő formátumban:

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

  Ha például a fejlesztési célhoz my_cluster_id és my_notebook_path nevű változók értékeit szeretné megadni, hozzon létre egy fájl .databricks/bundle/dev/variable-overrides.json, és állítsa a tartalmát a következőre:

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

  A variable-overrides.json fájlban összetett változókat is definiálhat.

Elsőbbségi sorrend

A Databricks parancssori felület a változók értékeit a következő sorrendben keresi meg, és leáll, amikor egy változó értékét keresi:

1. A parancs részeként --var megadott beállításokon bundle belül.
2. Minden olyan környezeti változókészleten belül, amely a következővel BUNDLE_VAR_kezdődik: .
3. A variables-overrides.json fájlon belül, ha létezik.
4. A csomagkonfigurációs fájlokban lévő variables leképezéseken belül minden targets leképezésen belül.
5. A változó definíciójának bármilyen default értéke a csomagkonfigurációs fájlok legfelső szintű variables leképezései között.

Összetett változó definiálása

Az egyéni változók sztring típusúak, kivéve, ha összetett változóként definiálják. Ha összetett típusú egyéni változót szeretne definiálni a csomagkonfigurációban, állítsa typecomplex.

Az alábbi példában a fürtbeállítások egy egyéni, összetett változóban vannak definiálva 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

A .databricks/bundles/<target>/variable-overrides.json fájlban is definiálhat egy összetett változót, ahogyan az a következő példában látható:

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

Objektum azonosítóértékének lekérése

A alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principalés warehouse objektumtípusok esetében definiálhat egy lookup az egyéni változóhoz egy elnevezett objektum azonosítójának lekéréséhez az alábbi formátumban:

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

Ha egy változóhoz keresési érték van definiálva, a rendszer a megadott névvel rendelkező objektum azonosítóját használja a változó értékeként. Ez biztosítja, hogy az objektum helyes feloldott azonosítója mindig a változóhoz legyen használva.

Az alábbi konfigurációban ${var.my_cluster_id} például a 12.2 megosztott fürt azonosítója lesz lecserélve.

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}