Databricks-eszközcsomag konfigurációi

Ez a cikk a Databricks-eszközcsomag konfigurációs fájljainak szintaxisát ismerteti, amelyek a Databricks-eszközcsomagokat határozzák meg. Mik azok a Databricks-eszközcsomagok?

A csomagkonfigurációs fájlt YAML formátumban kell kifejezni, és legalább a legfelső szintű csomagleképezést kell tartalmaznia . Minden csomagnak legalább egy (és csak egy) nevű csomagkonfigurációs fájlt databricks.ymlkell tartalmaznia. Több csomagkonfigurációs fájl esetén a fájlnak hivatkoznia databricks.yml kell rájuk.

A YAML-ről további információt a YAML hivatalos specifikációjában és oktatóanyagában talál.

A csomagkonfigurációs fájlok létrehozásához és használatához tekintse meg a Databricks Asset Bundles fejlesztését.

• Áttekintés
• Példák
• Hozzárendelések
• Egyéni változók
• Helyettesítések

Áttekintés

Ez a szakasz vizuálisan ábrázolja a csomagkonfigurációs fájl sémáját. További részletekért lásd : Leképezések.

# These is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  compute_id: string
  git:
    origin_url: string
    branch: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string

# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

# These are any additional configuration files to include.
include:
  - "<some-file-or-path-glob-to-include>"
  - "<another-file-or-path-glob-to-include>"

# This is the identity to use to run the bundle
run_as:
  - user_name: <user-name>
  - service_principal_name: <service-principal-name>

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the Experiments API's create experiment request payload reference.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See the Jobs API's create job request payload reference.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the Models API's create model request payload reference.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the Delta Live Tables API's create pipeline request payload reference.

# These are any additional files or paths to include or exclude.
sync:
  include:
    - "<some-file-or-path-glob-to-include>"
    - "<another-file-or-path-glob-to-include>"
  exclude:
    - "<some-file-or-path-glob-to-exclude>"
    - "<another-file-or-path-glob-to-exclude>"

# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
  <some-unique-programmatic-identifier-for-this-target>:
    artifacts:
      # See the preceding "artifacts" syntax.
    bundle:
      # See the preceding "bundle" syntax.
    compute_id: string
    default: true | false
    mode: development
    resources:
      # See the preceding "resources" syntax.
    sync:
      # See the preceding "sync" syntax.
    variables:
      <preceding-unique-variable-name>: <non-default-value>
    workspace:
      # See the preceding "workspace" syntax.
    run_as:
      # See the preceding "run_as" syntax.

Példák

Az alábbi példa egy csomagkonfigurációs fájlra mutat. Ez a csomag egy olyan helyi fájl hello.py távoli üzembe helyezését határozza meg, amely ugyanabban a könyvtárban található, mint a helyi csomag konfigurációs fájlja.databricks.yml Ezt a jegyzetfüzetet feladatként futtatja a megadott fürtazonosítóval rendelkező távoli fürt használatával. A távoli munkaterület URL-címe és a munkaterület hitelesítési hitelesítő adatai a hívó helyi konfigurációs profiljából lesznek beolvasva DEFAULT.

Feljegyzés

A Databricks azt javasolja, hogy a host leképezés helyett default a leképezést használja, ahol csak lehetséges, mivel ez hordozhatóbbá teszi a csomagkonfigurációs fájlokat. A host leképezés beállítása arra utasítja a Databricks parancssori felületét, hogy keressen egy megfelelő profilt a .databrickscfg fájlban, majd a profil mezőivel állapítsa meg, hogy melyik Databricks-hitelesítési típust használja. Ha a fájlban több, egyező mezővel rendelkező host profil is található .databrickscfg , akkor a profile databricks parancssori felületének segítségével meg kell adnia, hogy melyik profilt szeretné használni. Például tekintse meg a prod céldeklarációt a szakasz későbbi részében.

Ez a technika lehetővé teszi a blokkon belüli feladatdefiníciók és beállítások újbóli felhasználását és felülbírálását resources :

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true

Bár a következő csomagkonfigurációs fájl funkcionálisan egyenértékű, nem modularizált, ami nem teszi lehetővé a jó újrafelhasználást. Ez a deklaráció egy feladatot is hozzáfűz a feladathoz a meglévő feladat felülbírálása helyett:

bundle:
  name: hello-bundle

targets:
  dev:
    default: true
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 1234-567890-abcde123
              notebook_task:
                notebook_path: ./hello.py

Az alábbiakban az előző modularizált példát követjük, de a programozott (vagy logikai) névvel prod rendelkező cél hozzáadásával, amely egy másik távoli munkaterületi URL-címet és munkaterület-hitelesítési hitelesítő adatokat használ, amelyeket a hívó fájljának .databrickscfg a megadott munkaterület URL-címével egyező host bejegyzéséből olvas be. Ez a feladat ugyanazt a jegyzetfüzetet futtatja, de egy másik távoli fürtöt használ a megadott fürtazonosítóval. Figyelje meg, hogy nem kell deklarálnia a notebook_task megfeleltetést a prod leképezésen belül, mivel az visszaesik a notebook_task legfelső szintű resources leképezésen belüli leképezés használatára, ha a notebook_task megfeleltetés nincs explicit módon felülírva a prod leképezésen belül.

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

A feladat célon belüli dev érvényesítéséhez, üzembe helyezéséhez és futtatásához futtassa a következő parancsokat:

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job

A feladat célon belüli prod érvényesítéséhez, üzembe helyezéséhez és futtatásához futtassa a következő parancsokat:

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job

Az alábbi példa az előző, de felosztott összetevő fájlok még több modularizálás és jobb újrafelhasználása több csomag konfigurációs fájlok. Ez a technika lehetővé teszi, hogy ne csak a különböző definíciókat és beállításokat használja újra, hanem az ilyen fájlokat más fájlokkal is felcserélheti, amelyek teljesen eltérő deklarációkat biztosítanak:

databricks.yml:

bundle:
  name: hello-bundle

include:
  - "bundle*.yml"

bundle.resources.yml:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

bundle.targets.yml:

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

További példákért tekintse meg a GitHub csomagpéldáinak adattárát.

Hozzárendelések

A következő szakaszok a csomagkonfigurációs fájl szintaxisát írják le legfelső szintű leképezéssel.

• csomag
• Változók
• Munkaterület
• permissions
• Leletek
• tartalmaz
• Erőforrások
• szinkronizál
• Célok

csomag

A csomagkonfigurációs fájlnak csak egy legfelső szintű bundle leképezést kell tartalmaznia, amely a csomag tartalmát és az Azure Databricks-munkaterület beállításait társítja.

Ennek a bundle leképezésnek tartalmaznia kell egy leképezést name , amely a köteg programozott (vagy logikai) nevét adja meg. Az alábbi példa egy programozott (vagy logikai) névvel hello-bundlerendelkező csomagot deklarál.

bundle:
  name: hello-bundle

A bundle leképezés a legfelső szintű célok leképezésében szereplő egy vagy több cél gyermekének is lehet. Ezek a gyermekleképezések bundle minden nem alapértelmezett felülbírálást meghatároznak a célszinten. A legfelső szintű bundle leképezés name értéke azonban nem bírálható felül a célszinten.

compute_id

A bundle leképezés gyermekleképezéssel compute_id is rendelkezhet. Ez a leképezés lehetővé teszi egy fürt azonosítójának megadását felülbírálásként a csomagkonfigurációs fájlban máshol definiált összes fürt esetében. Ez a felülbírálás csak fejlesztésre szánt forgatókönyvekhez készült, az éles környezet előtt. A compute_id leképezés csak azokhoz a célhoz működik, amelyeknek a leképezése mode a következőre developmentvan állítva. A leképezésről további információt a compute_id célleképezésben talál.

Git

Lekérheti és felülbírálhatja a csomaghoz társított Git-verziókövetési adatokat. Ez hasznos az üzembe helyezett erőforrások megjegyzéséhez. Előfordulhat például, hogy a telepített gépi tanulási modell leírásába bele szeretné foglalni az adattár forrás URL-címét.

Amikor olyan parancsot bundle futtat, mint validatepéldául az , deploy vagy run, a bundle parancs feltölti a parancs konfigurációs fáját az alábbi alapértelmezett beállításokkal:

• bundle.git.origin_url, amely az adattár forrás URL-címét jelöli. Ez ugyanaz az érték, amelyet akkor kapna, ha a klónozott adattárból futtatná a parancsot git config --get remote.origin.url . A helyettesítések használatával hivatkozhat erre az értékre a csomagkonfigurációs fájlokkal, például${bundle.git.origin_url}.
• bundle.git.branch, amely az adattár aktuális ágát jelöli. Ez ugyanaz az érték, amelyet akkor kapna, ha a klónozott adattárból futtatná a parancsot git branch --show-current . A helyettesítések használatával hivatkozhat erre az értékre a csomagkonfigurációs fájlokkal, például${bundle.git.branch}.
• bundle.git.commit, amely az HEAD adattárban lévő véglegesítést jelöli. Ez ugyanaz az érték, amelyet akkor kapna, ha a klónozott adattárból futtatná a parancsot git rev-parse HEAD . A helyettesítések használatával hivatkozhat erre az értékre a csomagkonfigurációs fájlokkal, például${bundle.git.commit}.

A Git-beállítások lekéréséhez vagy felülbírálásához a csomagnak egy Git-adattárhoz társított könyvtárban kell lennie, például egy helyi könyvtárban, amelyet a git clone parancs futtatásával inicializál. Ha a könyvtár nincs Git-adattárhoz társítva, ezek a Git-beállítások üresek.

Szükség esetén felülbírálhatja a origin_urlbranchgit legfelső szintű bundle leképezés leképezésén belüli beállításokat, az alábbiak szerint:

bundle:
  git:
    origin_url: <some-non-default-origin-url>
    branch: <some-non-current-branch-name>

databricks_cli_version

A bundle leképezés tartalmazhat olyan leképezést databricks_cli_version , amely korlátozza a csomag által igényelt Databricks CLI-verziót. Ez megakadályozhatja a Databricks parancssori felület egy bizonyos verziójában nem támogatott leképezések használatával kapcsolatos problémákat.

A Databricks CLI verziója megfelel a szemantikai verziószámozásnak, és a leképezés támogatja a databricks_cli_version verziókorlátozások megadását. Ha az aktuális databricks --version érték nem a köteg databricks_cli_version leképezésében megadott korlátokon belül van, hiba történik a kötegen történő végrehajtáskor databricks bundle validate . Az alábbi példák néhány gyakori verziókorlátozási szintaxist mutatnak be:

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.0" # require Databricks CLI 0.218.0

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.*" # allow all patch versions of Databricks CLI 0.218

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0" # allow any version of Databricks CLI 0.218.0 or higher

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0, <= 1.0.0" # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive

Változók

A kötegek beállításfájlja egy legfelső szintű variables leképezést tartalmazhat a használandó változóbeállítások megadásához. Lásd: Egyéni változók.

Munkaterület

A csomagkonfigurációs fájl csak egy legfelső szintű workspace leképezést tartalmazhat a nem alapértelmezett Azure Databricks-munkaterületi beállítások megadásához.

Ez a workspace megfeleltetés tartalmazhat egy olyan leképezést root_path , amely egy nem alapértelmezett gyökérelérési útvonalat határoz meg, amelyet a munkaterületen az üzembe helyezésekhez és a munkafolyamat-futtatásokhoz is használni kell, például:

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

Alapértelmezés szerint root_path a Databricks PARANCSSOR az alapértelmezett elérési utat /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}használja, amely helyettesítéseket használ.

Ez a workspace leképezés olyan leképezést artifact_path is tartalmazhat, amely egy nem alapértelmezett összetevő elérési útját adja meg, amelyet a munkaterületen az üzembe helyezésekhez és a munkafolyamat-futtatásokhoz is használni kell, például:

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

Alapértelmezés szerint artifact_path a Databricks PARANCSSOR az alapértelmezett elérési utat ${workspace.root}/artifactshasználja, amely helyettesítéseket használ.

.. megjegyzés:: A artifact_path leképezés nem támogatja a Databricks Fájlrendszer (DBFS) elérési útját.

Ez a workspace megfeleltetés olyan leképezést file_path is tartalmazhat, amely egy nem alapértelmezett fájlelérési útvonalat határoz meg, amelyet a munkaterületen az üzembe helyezésekhez és a munkafolyamat-futtatásokhoz is használni kell, például:

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

Alapértelmezés szerint file_path a Databricks PARANCSSOR az alapértelmezett elérési utat ${workspace.root}/fileshasználja, amely helyettesítéseket használ.

A state_path leképezés alapértelmezés szerint a munkaterület alapértelmezett elérési útjának ${workspace.root}/state felel meg, és a munkaterületen belül a Terraform állapotinformációinak tárolására szolgál az üzemelő példányokról.

A workspace leképezés a következő választható leképezéseket is tartalmazhat a használni kívánt Azure Databricks hitelesítési mechanizmus megadásához. Ha nincsenek megadva ezen workspace a leképezésen belül, a leképezésben workspace meg kell adni őket a legfelső szintű célok leképezésének egy vagy több példányának gyermekeként.

Fontos

Az Azure Databricks-hitelesítéshez az alábbi workspace leképezésekhez szigorú kódértékeket kell megadnia. Például nem adhat meg egyéni változókat a leképezések értékeihez a ${var.*} szintaxis használatával.

• A profile leképezés (vagy a --profile-p köteg futtatásakor a csomag ellenőrzése, üzembe helyezése, futtatása és megsemmisítése a Databricks parancssori felülettel) megadja a munkaterülethez az Azure Databricks-hitelesítéshez használandó konfigurációs profil nevét. Ez a konfigurációs profil megfelel a Databricks parancssori felület beállításakor létrehozott profilnak.

  Feljegyzés

  A Databricks azt javasolja, hogy a leképezés helyett a leképezés helyett profile a host leképezést (vagy -p a --profile csomag ellenőrzése, üzembe helyezése, futtatása és megsemmisítése parancsok futtatásakor a beállításokat vagy beállításokat) használja, mivel ez hordozhatóbbá teszi a csomagkonfigurációs fájlokat. A host leképezés beállítása arra utasítja a Databricks parancssori felületét, hogy keressen egy megfelelő profilt a .databrickscfg fájlban, majd a profil mezőivel állapítsa meg, hogy melyik Databricks-hitelesítési típust használja. Ha a fájlban több, egyező mezővel rendelkező host profil található.databrickscfg, akkor a profile leképezéssel (vagy -p a --profile parancssori beállításokkal) meg kell adnia a Databricks parancssori felületének, hogy melyik profilt használja. Példaként tekintse meg a prod példában szereplő céldeklarációt.

• A host leképezés megadja az Azure Databricks-munkaterület URL-címét. Lásd a munkaterületenkénti URL-címet.

• Az OAuth machine-to-machine (M2M) hitelesítéshez a leképezést client_id használja a rendszer. Másik lehetőségként beállíthatja ezt az értéket a helyi környezeti változóban DATABRICKS_CLIENT_ID. Létrehozhat egy konfigurációs profilt az client_id értékkel, majd megadhatja a profil nevét a profile leképezéssel (vagy a --profile csomag ellenőrzése, üzembe helyezése, futtatása és megsemmisítése parancsok a Databricks parancssori felülettel való futtatásakor vagy -p a beállítások használatával). Lásd: OAuth machine-to-machine (M2M) hitelesítés.

  Feljegyzés

  A csomagkonfigurációs fájlban nem adhat meg Azure Databricks OAuth titkos értéket. Ehelyett állítsa be a helyi környezeti változót DATABRICKS_CLIENT_SECRET. Vagy hozzáadhatja az client_secret értéket egy konfigurációs profilhoz, majd megadhatja a profil nevét a profile leképezéssel (vagy a --profile csomag ellenőrzése, üzembe helyezése, futtatása és megsemmisítése parancsok a Databricks parancssori felülettel való futtatásakor vagy -p a beállítások használatával).

• Az Azure CLI-hitelesítéshez a leképezést azure_workspace_resource_id használja a rendszer. Másik lehetőségként beállíthatja ezt az értéket a helyi környezeti változóban DATABRICKS_AZURE_RESOURCE_ID. Létrehozhat egy konfigurációs profilt az azure_workspace_resource_id értékkel, majd megadhatja a profil nevét a profile leképezéssel (vagy a --profile csomag ellenőrzése, üzembe helyezése, futtatása és megsemmisítése parancsok a Databricks parancssori felülettel való futtatásakor vagy -p a beállítások használatával). Lásd: Azure CLI-hitelesítés.

• Az Azure-ügyfél titkos hitelesítése szolgáltatásnevek használatával, a leképezések azure_workspace_resource_idazure_tenant_idés azure_client_id a használatuk. Másik lehetőségként beállíthatja ezeket az értékeket a helyi környezeti változókban, illetve ARM_CLIENT_IDa helyi környezeti változókbanDATABRICKS_AZURE_RESOURCE_IDARM_TENANT_ID. Vagy létrehozhat egy konfigurációs profilt a azure_workspace_resource_id, azure_tenant_idés azure_client_id az értékekkel, majd megadhatja a profil nevét a profile leképezéssel (vagy a --profile csomag ellenőrzése, üzembe helyezése, futtatása és megsemmisítése parancsok a Databricks parancssori felülettel való futtatásakor vagy -p a beállítások használatával). Lásd: Microsoft Entra ID szolgáltatásnév-hitelesítés.

  Feljegyzés

  A csomagkonfigurációs fájlban nem adhat meg Azure-ügyfél titkos kódértéket. Ehelyett állítsa be a helyi környezeti változót ARM_CLIENT_SECRET. Vagy hozzáadhatja az azure_client_secret értéket egy konfigurációs profilhoz, majd megadhatja a profil nevét a profile leképezéssel (vagy a --profile csomag ellenőrzése, üzembe helyezése, futtatása és megsemmisítése parancsok a Databricks parancssori felülettel való futtatásakor vagy -p a beállítások használatával).

• Az Azure-beli felügyelt identitások hitelesítése esetén a leképezések azure_use_msiazure_client_idés azure_workspace_resource_id a használatuk. Másik lehetőségként beállíthatja ezeket az értékeket a helyi környezeti változókban, illetve DATABRICKS_AZURE_RESOURCE_IDa helyi környezeti változókbanARM_USE_MSIARM_CLIENT_ID. Vagy létrehozhat egy konfigurációs profilt a azure_use_msi, azure_client_idés azure_workspace_resource_id az értékekkel, majd megadhatja a profil nevét a profile leképezéssel (vagy a --profile csomag ellenőrzése, üzembe helyezése, futtatása és megsemmisítése parancsok a Databricks parancssori felülettel való futtatásakor vagy -p a beállítások használatával). Tekintse meg az Azure által felügyelt identitások hitelesítését.

• A azure_environment leképezés meghatározza az Azure-környezet típusát (például Nyilvános, UsGov, Kína és Németország) egy adott API-végpontkészlethez. Az alapértelmezett érték PUBLIC. Másik lehetőségként beállíthatja ezt az értéket a helyi környezeti változóban ARM_ENVIRONMENT. Vagy hozzáadhatja az azure_environment értéket egy konfigurációs profilhoz, majd megadhatja a profil nevét a profile leképezéssel (vagy a --profile csomag ellenőrzése, üzembe helyezése, futtatása és megsemmisítése parancsok a Databricks parancssori felülettel való futtatásakor vagy -p a beállítások használatával).

• A azure_login_app_id leképezés nem működik, és belső használatra van fenntartva.

• A auth_type leképezés meghatározza a használni kívánt Azure Databricks-hitelesítési típust, különösen olyan esetekben, amikor a Databricks PARANCSSOR váratlan hitelesítési típusra következtet. Lásd a Hitelesítés típusa mezőt.

Engedélyek

A legfelső szintű permissions leképezés egy vagy több engedélyszintet határoz meg, amelyek a csomagban definiált összes erőforrásra alkalmazhatók. Ha engedélyeket szeretne alkalmazni egy adott erőforrásra, tekintse meg az adott erőforrás engedélyeinek definiálása című témakört.

Az engedélyezett legfelső szintű engedélyszintek a következőkCAN_VIEW: és CAN_MANAGECAN_RUN.

A csomagkonfigurációs fájlban található alábbi példa egy felhasználó, csoport és szolgáltatásnév engedélyszintjeit határozza meg, amelyek a csomagban resources meghatározott összes feladatra, folyamatra, kísérletre és modellre vonatkoznak:

permissions:
  - level: CAN_VIEW
    group_name: test-group
  - level: CAN_MANAGE
    user_name: someone@example.com
  - level: CAN_RUN
    service_principal_name: 123456-abcdef

Leletek

A legfelső szintű artifacts leképezés egy vagy több olyan összetevőt határoz meg, amely automatikusan létrejön a csomagtelepítések során, és később használható a csomagfuttatásokban. Minden gyermekösszetevő a következő leképezéseket támogatja:

• A type használata kötelező. Ha üzembe helyezés előtt Python-kerekes fájlt szeretne létrehozni, ezt a leképezést a következőre whlkell állítani: .
• path nem kötelező relatív elérési út a csomagkonfigurációs fájl helyétől a Python-kerékfájl fájljának helyéhez setup.py . Ha path nem szerepel a fájlban, a Databricks parancssori felület megkísérli megtalálni a Python-kerekes fájl fájlját setup.py a csomag gyökérkönyvtárában.
• files Egy nem kötelező leképezés, amely tartalmaz egy gyermekleképezést source , amellyel megadhat nem alapértelmezett helyeket az összetett buildelési utasításokhoz. A helyek relatív elérési utakként vannak megadva a csomagkonfigurációs fájl helyéről.
• build nem alapértelmezett buildparancsok nem kötelező készlete, amelyeket helyileg szeretne futtatni az üzembe helyezés előtt. A Python-kerekes buildek esetében a Databricks CLI feltételezi, hogy megtalálja a Python-csomag wheel helyi telepítését a buildek futtatásához, és alapértelmezés szerint futtatja a parancsot python setup.py bdist_wheel az egyes csomagtelepítések során. Több buildparancs megadásához különítse el az egyes parancsokat dupla és (&&) karakterekkel.

További információkért, beleértve a használt artifactsmintacsomagot is, olvassa el a Python-kerékfájl fejlesztése a Databricks Asset Bundles használatával című témakört.

Tipp.

A csomagokban lévő összetevők beállításait a Databricks-eszközcsomagok összetevő-beállításainak dinamikus definiálása című témakörben ismertetett technikákkal határozhatja meg, egyesítheti és felülbírálhatja.

tartalmaz

A include tömb megadja azoknak az elérési utaknak a listáját, amelyek konfigurációs fájlokat tartalmaznak a csomagban. Ezek az elérésiút-globok annak a csomagkonfigurációs fájlnak a helyéhez vannak viszonyítva, amelyben az elérési út globok meg vannak adva.

A Databricks parancssori felület alapértelmezés szerint nem tartalmaz konfigurációs fájlokat a csomagon belül. A tömb használatával include meg kell adnia a csomagon belül belefoglalandó összes konfigurációs fájlt, kivéve magát a databricks.yml fájlt.

Ez a include tömb csak legfelső szintű leképezésként jelenhet meg.

A csomagkonfigurációs fájl alábbi példája a három megadott konfigurációs fájlt tartalmazza. Ezek a fájlok ugyanabban a könyvtárban találhatók, mint a csomagkonfigurációs fájl:

include:
  - "bundle.artifacts.yml"
  - "bundle.resources.yml"
  - "bundle.targets.yml"

Az alábbi példa egy csomagkonfigurációs fájlban tartalmazza az összes fájlnevet tartalmazó fájlt, amely a következővel bundle kezdődik és végződik .yml. Ezek a fájlok ugyanabban a könyvtárban találhatók, mint a csomagkonfigurációs fájl:

include:
  - "bundle*.yml"

Erőforrások

A resources leképezés a csomag által használt Azure Databricks-erőforrásokra vonatkozó információkat adja meg.

Ez a resources leképezés legfelső szintű leképezésként jelenhet meg, vagy a legfelső szintű célok leképezésének egy vagy több példányának gyermeke lehet, és nulla vagy egy támogatott erőforrástípust tartalmaz. Minden erőforrástípus-megfeleltetés egy vagy több egyedi erőforrás-deklarációt tartalmaz, amelyeknek egyedi névvel kell rendelkezniük. Ezek az egyéni erőforrás-deklarációk a megfelelő objektum létrehozási műveletének yaML-ben kifejezett hasznos adatait használják az erőforrás meghatározásához. Az erőforrás támogatott tulajdonságai a megfelelő objektum által támogatott mezők.

A műveletkérelem hasznos adatainak létrehozását a Databricks REST API-referencia dokumentálja, a parancs pedig az databricks bundle schema összes támogatott objektumsémát kimeneteli. Ezenkívül a databricks bundle validate parancs figyelmeztetéseket ad vissza, ha ismeretlen erőforrás-tulajdonságok találhatók a csomagkonfigurációs fájlokban.

Az alábbi táblázat a csomagok támogatott erőforrástípusait és a kapcsolódó hasznos adatok dokumentációjára mutató hivatkozásokat sorolja fel.

Erőforrás típusa	Erőforrás-leképezések
jobs	Feladatleképezések: POST /api/2.1/jobs/create További információkért tekintse meg a feladatfeladatok típusait és az új feladatfürt-beállítások felülbírálását.
pipelines	Folyamatleképezések: POST /api/2.0/pipelines
experiments	Kísérletleképezések: POST /api/2.0/mlflow/experiments/create
models	Modellleképezések: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoints	Végpontleképezéseket kiszolgáló modell: POST /api/2.0/serving-endpoints
registered_models (Unity Catalog)	Unity Catalog-modellleképezések: POST /api/2.1/unity-catalog/models

Az erőforrás-deklarációk által hivatkozott mappák és fájlok összes elérési útja annak a csomagkonfigurációs fájlnak a helyéhez képest van, amelyben ezek az elérési utak meg vannak adva.

Az alábbi példa egy feladatot deklarál az erőforráskulcsával hello-job és egy olyan folyamatot, amelynek az erőforráskulcsa a következő hello-pipeline:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      clusters:
        - label: default
          num_workers: 1
      development: true
      continuous: false
      channel: CURRENT
      edition: CORE
      photon: false
      libraries:
        - notebook:
            path: ./pipeline.py

szinkronizál

A sync tömb megadja azoknak a fájl- vagy elérésiút-csoportoknak a listáját, amelyek a csomagtelepítéseken belül szerepeljenek, vagy kizárhatók a csomagtelepítésekből, az alábbi szabályoktól függően:

• A köteg gyökérkönyvtárában található .gitignore fájlok és elérési utak összes listája alapján a include leképezés a fájlgyökeréhez képest tartalmazhat fájlgyökereket, elérési utakat vagy mindkettőt a csomag gyökérkönyvtárához képest, hogy explicit módon szerepeljen bennük.
• A leképezés a köteg gyökérkönyvtárában lévő fájlban található .gitignore fájl- és elérésiút-globok listája, valamint a leképezésben exclude található include fájl- és elérésiút-globok listája alapján a leképezés a fájlgyökeréhez képest tartalmazhat fájlgyökereket, elérési utakat vagy mindkettőt, hogy explicit módon kizárja őket.

A megadott mappák és fájlok összes elérési útja annak a csomagkonfigurációs fájlnak a helyéhez képest van, amelyben ezek az elérési utak meg vannak adva.

A fájl- és exclude elérésiút-minták szintaxisa include a szokásos .gitignore mintaszintaxisokat követi. Lásd a gitignore mintaformátumát.

Ha például a következő .gitignore fájl a következő bejegyzéseket tartalmazza:

.databricks
my_package/dist

A csomagkonfigurációs fájl pedig a következő include leképezést tartalmazza:

sync:
  include:
    - my_package/dist/*.whl

Ezután a mappa összes fájljának my_package/dist fájlkiterjesztése *.whl megjelenik. A mappában lévő my_package/dist többi fájl nem szerepel a fájlban.

Ha azonban a csomagkonfigurációs fájl a következő exclude leképezést is tartalmazza:

sync:
  include:
    - my_package/dist/*.whl
  exclude:
    - my_package/dist/delete-me.whl

Ezután a mappában lévő my_package/dist összes fájl, amelynek fájlkiterjesztése *.whl– a névvel ellátott delete-me.whlfájl kivételével – szerepel a fájlban. A mappában lévő my_package/dist többi fájl sem szerepel a fájlban.

A sync tömb deklarálható egy adott cél leképezésében targets is. A sync célban deklarált tömbök minden legfelső szintű sync tömbdeklarációval egyesülnek. Az előző példával folytatva például a szint alábbi include leképezése targets egyesül a include legfelső szintű sync tömb leképezésével:

targets:
  dev:
    sync:
      include:
        - my_package/dist/delete-me.whl

Futtatáskor databricks bundle validate --output jsonaz eredményként kapott gráf releváns része a következő:

"sync": {
  "include": [
    "my_package/dist/*.whl",
    "my_package/dist/delete-me.whl"
  ],
  "exclude": [
    "my_package/dist/delete-me.whl"
  ]
}

Célok

A targets leképezés egy vagy több környezetet határoz meg az Azure Databricks-munkafolyamatok futtatásához. Mindegyik cél az összetevők, az Azure Databricks-munkaterület beállításai és az Azure Databricks-feladatok vagy folyamatok részleteinek egyedi gyűjteménye.

Ez targets a leképezés nem kötelező, de erősen ajánlott. Ha meg van adva, csak legfelső szintű leképezésként jelenhet meg. Ha a targets megfeleltetés nincs megadva, a rendszer mindig a legfelső szintű munkaterület, összetevők és erőforrás-leképezések beállításait használja.

A targets leképezés egy vagy több célleképezésből áll, amelyeknek egyedi programozott (vagy logikai) névvel kell rendelkezniük.

Ha a célleképezés nem ad meg workspace, artifactsvagy resources gyermekleképezéseket, akkor a cél a felső szintű workspaceartifactsbeállításokat és resources a leképezéseket használja.

Ha a célleképezés egy workspace, artifactsvagy resources leképezést határoz meg, és egy legfelső szintű workspace, artifactsvagy resources leképezés is létezik, akkor az ütköző beállításokat felülbírálta a célon belüli beállítások.

A célértékek felülbírálhatják a legfelső szintű változók értékeit is.

Ha meg szeretné adni, hogy a cél legyen az alapértelmezett, hacsak nincs más megadva, adja hozzá a default leképezést, és állítsa a következőre true: . Ez a névvel ellátott dev cél például az alapértelmezett cél:

targets:
  dev:
    default: true

Ha meg szeretné adni, hogy egy cél fejlesztési célként legyen kezelve, adja hozzá a mode leképezést, és állítsa a következőre development: . Ha meg szeretné adni, hogy egy cél éles célként legyen kezelve, adja hozzá a mode leképezést, és állítsa a következőre production: . Ez a névvel ellátott prod cél például éles célként van kezelve:

targets:
  prod:
    mode: production

A beállítás mode a megfelelő alapértelmezett viselkedések gyűjteményét biztosítja az éles üzem előtti és az éles munkafolyamatokhoz. További információ: Databricks Asset Bundle üzembe helyezési módok. Emellett megadhatja run_as az egyes célokat a Databricks-eszközcsomagok munkafolyamat futtatási identitásának megadása című cikkben leírtak szerint.

Az alábbi példa két célt deklarál. Az első célnak programozott (vagy logikai) neve dev van, és ez az alapértelmezett cél. A második célnak programozott (vagy logikai) neve prod van, és nem az alapértelmezett cél. Ez a második cél egy hitelesítéshez elnevezett PROD Azure Databricks-kapcsolatprofilt használ:

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>

A célon belüli dev feladatok vagy folyamatok ellenőrzéséhez, üzembe helyezéséhez és futtatásához futtassa a következő parancsokat:

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run <job-or-pipeline-programmatic-name>

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev <job-or-pipeline-programmatic-name>

A feladat célon belüli prod érvényesítéséhez, üzembe helyezéséhez és futtatásához futtassa a következő parancsokat:

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod <job-or-pipeline-programmatic-name>

Egyéni változók

Egyéni változókkal modulárisabbá és újrafelhasználhatóbbá teheti a csomagkonfigurációs fájlokat. Deklarálhat például egy változót, amely egy meglévő fürt azonosítóját jelöli, majd módosítani szeretné a változó értékét különböző fürtazonosítókra, mert a különböző munkafolyamatok több célon belül futnak anélkül, hogy módosítanák a csomagkonfigurációs fájlok eredeti kódját.

A leképezésen belül deklarálhat egy vagy több változót a variables csomagkonfigurációs fájlokban. Minden változóhoz megadhat egy opcionális leírást, alapértelmezett értéket vagy keresési beállítást egy azonosító értékének lekéréséhez, az alábbi formátumot követve:

variables:
  <variable-name>:
    description: <optional-description>
    default: <optional-default-value>
    lookup:
      <optional-object-type>: <optional-object-name>

Például deklarálhat egy olyan változótmy_cluster_id, amelynek az alapértelmezett értéke 1234-567890-abcde123, és egy változó neve a következő alapértelmezett értékkel ./hello.pyvan elnevezvemy_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

Ha a deklaráció részeként nem ad default meg értéket egy változóhoz, akkor az értéket később, a parancssorban, egy környezeti változón vagy a csomagkonfigurációs fájlok más részén kell megadnia. Ezeket a megközelítéseket a szakasz későbbi részében ismertetjük.

Feljegyzé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.

Ha a csomagkonfigurációs fájlokban lévő egyéni változókra szeretne hivatkozni, használjon helyettesítéseket. Változók esetén használja a formátumot ${var.<variable_name>}. Például a névvel ellátott my_cluster_idmy_notebook_pathváltozókra való hivatkozáshoz:

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 my_cluster_idváltozó értékét1234-567890-abcde123, és meg szeretné adni a névvel ellátott my_notebook_pathváltozó értékét./hello.py, 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_notebook_pathváltozó értékét./hello.py, futtassa a következő parancsot, mielőtt meghívna egy bundle parancsot, példáulvalidate: deployrunmy_cluster_id

  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. Ehhez használjon egy leképezést variables a leképezésen belül, a targets következő formátumban:

  variables:
    <variable-name>: <value>
  

  Például az elnevezett my_cluster_id változók és my_notebook_path két különálló cél értékeinek megadása:

  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
  

Az előző példákban a Databricks parancssori felület a változók my_cluster_id értékeit keresi, és my_notebook_path az alábbi sorrendben leáll, amikor az egyes egyező változókhoz tartozó értéket talál, kihagyva a változó többi helyét:

1. A parancs részeként bundle megadott beállításokon --var belül.
2. Minden olyan környezeti változókészleten belül, amely a következővel BUNDLE_VAR_kezdődik: .
3. A csomagkonfigurációs fájlokban lévő targets leképezéseken belül minden variables leképezésen belül.
4. 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.

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

A alert, cluster_policy, cluster, dashboard, instance_pooljob, metastore, pipeline, queryservice_principalés warehouse objektumtípusokhoz definiálhat egy lookup egyéni változót az 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.

Feljegyzé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 ${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}

Helyettesítések

A helyettesítésekkel modulárisabbá és újrafelhasználhatóbbá teheti a csomagkonfigurációs fájlokat.

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: A feladat feladatfeladatokba való futtatásával kapcsolatos kontextus átadása.

A parancs futtatásakor bundle validate --output json például egy ilyen gráf jelenhet meg (a három pont a kihagyott tartalmat jelzi a rövidség kedvéért):

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

Az előző példában hivatkozhat a csomagkonfigurációs fájlban lévő értékre someone@example.com a helyettesítéssel ${workspace.current_user.userName}.

Hasonlóképpen, a következő helyettesítések:

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

Egy csomagkonfigurációs fájlban, például a következőben (a három pont a kihagyott tartalmat jelzi a rövidség kedvéért):

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

A parancs futtatásakor bundle validate --output json a következő gráfra lesz feloldva (a három pont a kihagyott tartalmat jelzi a rövidség kedvéért):

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "profile": "DEFAULT",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "root": "/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev",
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

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 parancs kimenetében dokumentált sémahierarchiátbundle schema.

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