Megosztás:

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.

Tipp.

A feladatparaméterek értékeihez dinamikus értékhivatkozásokkal is átadhatja a feladatfuttatások kontextusát a feladattevékenységek számára. Lásd: Mi az a dinamikus értékhivatkozás? és a feladatok paraméterezése.

Helyettesítések

A helyettesítések használatával lekérheti azoknak a beállításoknak az értékeit, amelyek a csomag üzembe helyezésének és futtatásának kontextusa alapján változhatnak. A helyettesítésekkel például hivatkozhat a köteg name, a köteg target és a munkaterület userName mezőinek értékeire a csomagkonfigurációs fájlban lévő root_path munkaterület összeállításához.

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Ha someone@example.com üzembe helyezte ezt a csomagot, az a gyökérútvonalon /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/devlesz üzembe helyezve.

A névvel ellátott erőforrásokhoz helyettesítőket is létrehozhat. Például a következő folyamatdefinícióhoz használhatja ${resources.pipelines.my_pipeline.target} a folyamat célértékét:

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

Az érvényes helyettesítések meghatározásához használja a csomagkonfigurációs referenciát, az erőforráskonfigurációs hivatkozást vagy a REST API-referenciaban dokumentált megfelelő objektumok sémahierarchiáját vagy a bundle schema parancs kimenetét.

Tipp.

Az erőforrásokhoz elérhető helyettesítések teljes listáját lásd: Databricks CLI GitHub-adattár out.fields.txt

Í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.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}

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 a csomagparancsok végrehajtásakor, egy környezeti változón keresztül, a csomagkonfigurációs fájlok más részén vagy a .databricks/bundle/<target>/variable-overrides.json csomagprojekt fájljában kell beállítania. 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>}. A következő konfiguráció például a my_cluster_id és my_notebook_path változókra hivatkozik:

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 állított be 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.

Megjegyzés

A kötegváltozók üzembehelyezés idejére vonatkozó változók. Ezeket a csomag üzembe helyezésekor értelmezi a rendszer. Ha például egy feladatot futtat, az egy korábban üzembe helyezett feladatot és az üzembe helyezéshez konfigurált változókat futtat, így a feladat futtatásához különböző értékek átadása nem lesz érvényes. Ehelyett adjon át értékeket egy feladat futtatásához a feladat paraméterek segítségével. Lásd : Feladatparaméterek átadása.

  • 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 variables és targets leképezés használatával, 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.

Megjegyzés

Bármelyik módszert is választja a változó értékek megadásához, használja ugyanazt a megközelítést az üzembe helyezési és a futtatási szakaszokban is. Ellenkező esetben előfordulhat, hogy váratlan eredményeket kap az üzembe helyezés időpontja és a meglévő üzembe helyezésen alapuló feladat vagy folyamatfuttatás között.

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 variable-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

Egy egyéni változót alapértelmezetten sztring típusúnak tekintenek, hacsak nem határozza meg összetett változóként. Ha összetett típusú egyéni változót szeretne definiálni a csomagkonfigurációban, állítsa typecomplex.

Megjegyzés

A type beállítás számára egyetlen érvényes érték a complex. Emellett a köteg érvényesítése meghiúsul, ha type be van állítva complex , és a default változóhoz definiált érték egyetlen érték.

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/bundle/<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ípusokhoz megadhat egy egyéni lookup változót az elnevezett objektum azonosítójának lekéréséhez, ebben a 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.

Megjegyzés

Hiba akkor fordul elő, ha a megadott névvel rendelkező objektum nem létezik, vagy ha egynél több objektum van a megadott névvel.

Az alábbi konfigurációban például a ${var.my_cluster_id} a 12.2 megosztott fürt azonosítójával 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}

Kimeneti helyettesítés és változóértékek

Annak érdekében, hogy a helyettesítések és változók helyesen legyenek megadva és elemezve legyenek a Databricks-eszközcsomagok által, futtassa a következőt databricks bundle validate: . Lásd : databricks-csomag ellenőrzése. A csomag üzembe helyezésekor használt értékek megtekintéséhez használja a --output json következő lehetőséget:

databricks bundle validate --output json

Például egy feladatfeladatban definiált és használt változót my_cluster_id tartalmazó csomag esetén:

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

A databricks bundle validate séma kimenete a következő:

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