Konfigurace sady prostředků Databricks

Tento článek popisuje syntaxi konfiguračních souborů sady prostředků Databricks, která definuje sady prostředků Databricks. Podívejte se , co jsou sady prostředků Databricks?

Konfigurační soubor sady musí být vyjádřen ve formátu YAML a musí obsahovat minimálně mapování balíčku nejvyšší úrovně. Každá sada musí obsahovat minimálně jeden (a pouze jeden) konfigurační soubor sady s názvem databricks.yml. Pokud existuje více konfiguračních souborů sady, musí na tyto soubory odkazovat databricks.yml soubor pomocí include mapování.

Další informace o YAML najdete v oficiální specifikaci a kurzu YAML.

Informace o vytváření a práci s konfiguračními soubory sady prostředků najdete ve vývoji sad prostředků Databricks.

Přehled

Tato část obsahuje vizuální znázornění schématu konfiguračního souboru sady. Podrobnosti najdete v tématu Mapování.

# 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
  cluster_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 or complex

# 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.
  schemas:
    <some-unique-programmatic-identifier-for-this-schema>:
      # See the Unity Catalog schema 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>"
  paths:
    - "<some-file-or-path-to-synchronize>"

# 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.
    cluster_id: string
    default: true | false
    mode: development
    presets:
      <preset>: <value>
    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říklady

Poznámka:

Příklady konfigurace, které demonstrují funkce sady prostředků a běžné případy použití sady prostředků, najdete v příkladech konfigurace sady a v úložišti příkladů sady prostředků na GitHubu.

Následující příklad konfigurace sady prostředků určuje místní soubor s názvem hello.py , který je ve stejném adresáři jako tento místní konfigurační soubor sady s názvem databricks.yml. Spustí tento poznámkový blok jako úlohu pomocí vzdáleného clusteru se zadaným ID clusteru. Adresa URL vzdáleného pracovního prostoru a přihlašovací údaje pro ověřování pracovního prostoru se čtou z místního konfiguračního profilu volajícího s názvem DEFAULT.

Databricks doporučuje, abyste místo mapování používali host mapování default všude, kde je to možné, protože díky tomu jsou konfigurační soubory sady přenosnější. host Nastavení mapování dává rozhraní příkazového řádku Databricks pokyn k vyhledání odpovídajícího profilu v .databrickscfg souboru a následné použití polí daného profilu k určení typu ověřování Databricks, který se má použít. Pokud v .databrickscfg souboru existuje více profilů s odpovídajícím host polem, musíte použít profile pokyn rozhraní příkazového řádku Databricks o tom, který konkrétní profil použít. Příklad najdete v prod cílové deklaraci dále v této části.

Tato technika umožňuje opakované použití a také přepsání definic a nastavení úloh v resources rámci bloku:

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

I když je následující konfigurační soubor sady funkčně ekvivalentní, není modularizovaný, což neumožňuje dobré opakované použití. Tato deklarace také připojí úlohu k úloze místo přepsání existující úlohy:

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

Následující příklad přidá cíl s názvemprod, který používá jinou adresu URL vzdáleného pracovního prostoru a přihlašovací údaje pro ověřování pracovního prostoru, které se čtou z odpovídající host položky souboru volajícího .databrickscfg se zadanou adresou URL pracovního prostoru. Tato úloha spouští stejný poznámkový blok, ale používá jiný vzdálený cluster se zadaným ID clusteru. Všimněte si, že mapování není nutné deklarovat notebook_task v rámci prod mapování, protože se vrátí zpět k použití notebook_task mapování v rámci mapování nejvyšší úrovně resources , pokud notebook_task mapování není explicitně přepsáno v rámci prod mapování.

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

Pokud chcete ověřit, nasadit a spustit tuto úlohu v rámci dev cíle:

# 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

Pokud chcete místo toho ověřit, nasadit a spustit tuto úlohu v prod rámci cíle:

# 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

Následuje předchozí příklad, ale rozdělte je na soubory komponent pro ještě větší modularizaci a lepší opakované použití v rámci více konfiguračních souborů sady. Tato technika umožňuje nejen opakovaně používat různé definice a nastavení, ale můžete také prohodit jakýkoli z těchto souborů s jinými soubory, které poskytují zcela jiné deklarace:

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

Mapování

Následující části popisují syntaxi konfiguračního souboru sady pomocí mapování nejvyšší úrovně.

• ranec
• proměnné
• pracovní plocha
• permissions
• Artefakty
• include
• prostředky
• synchronizovat
• cíle

ranec

Konfigurační soubor sady musí obsahovat pouze jedno mapování nejvyšší úrovně bundle , které přidruží obsah sady a nastavení pracovního prostoru Azure Databricks.

Toto bundle mapování musí obsahovat name mapování, které určuje programový (nebo logický) název sady. Následující příklad deklaruje sadu s programovým (nebo logickým) názvem hello-bundle.

bundle:
  name: hello-bundle

Mapování bundle může být také podřízeným objektem jednoho nebo více cílů v mapování cílů nejvyšší úrovně. Každé z těchto podřízených bundle mapování určuje jakákoli jiná než výchozí přepsání na cílové úrovni. Hodnotu mapování name nejvyšší úrovně bundle však nelze přepsat na cílové úrovni.

cluster_id

Mapování bundle může mít podřízené cluster_id mapování. Toto mapování umožňuje zadat ID clusteru, které se má použít jako přepsání pro clustery definované jinde v konfiguračním souboru sady. Informace o tom, jak načíst ID clusteru, najdete v tématu Adresa URL a ID clusteru.

Přepsání cluster_id je určeno pro scénáře pouze pro vývoj a je podporován pouze pro cíl, který má mapování mode nastaveno na development. Další informace o mapování najdete v target tématu cíle.

compute_id

Poznámka:

Toto nastavení je zastaralé. Místo toho použijte cluster_id .

Mapování bundle může mít podřízené compute_id mapování. Toto mapování umožňuje zadat ID clusteru, které se má použít jako přepsání pro clustery definované jinde v konfiguračním souboru sady.

lotr

Můžete načíst a přepsat podrobnosti o správě verzí Gitu, které jsou přidružené k vaší sadě. To je užitečné pro přidávání poznámek k nasazeným prostředkům. Do popisu modelu strojového učení, který nasadíte, můžete například zahrnout původní adresu URL úložiště.

Pokaždé, když spustíte příkaz, bundle například validatenebo rundeploy , bundle naplní konfigurační strom příkazu následujícím výchozím nastavením:

• bundle.git.origin_url, který představuje počáteční adresu URL úložiště. Jedná se o stejnou hodnotu, jakou byste získali, pokud jste příkaz git config --get remote.origin.url spustili z klonovaného úložiště. Nahrazení můžete použít k odkazování na tuto hodnotu s konfiguračními soubory sady, jako ${bundle.git.origin_url}.
• bundle.git.branch, který představuje aktuální větev v rámci úložiště. Jedná se o stejnou hodnotu, jakou byste získali, pokud jste příkaz git branch --show-current spustili z klonovaného úložiště. Nahrazení můžete použít k odkazování na tuto hodnotu s konfiguračními soubory sady, jako ${bundle.git.branch}.
• bundle.git.commit, který představuje HEAD potvrzení v rámci úložiště. Jedná se o stejnou hodnotu, jakou byste získali, pokud jste příkaz git rev-parse HEAD spustili z klonovaného úložiště. Nahrazení můžete použít k odkazování na tuto hodnotu s konfiguračními soubory sady, jako ${bundle.git.commit}.

Pokud chcete načíst nebo přepsat nastavení Gitu, musí být vaše sada v adresáři přidruženém k úložišti Git, například v místním adresáři inicializovaném spuštěním git clone příkazu. Pokud adresář není přidružený k úložišti Git, jsou tato nastavení Gitu prázdná.

V případě potřeby můžete přepsat nastavení a branch nastavení origin_url v git rámci mapování nejvyšší úrovněbundle:

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

databricks_cli_version

Mapování bundle může obsahovat databricks_cli_version mapování, které omezuje verzi rozhraní příkazového řádku Databricks vyžadovanou sadou. To může zabránit problémům způsobeným použitím mapování, která nejsou podporována v určité verzi rozhraní příkazového řádku Databricks.

Verze rozhraní příkazového řádku Databricks odpovídá sémantické sémantické správě verzí a databricks_cli_version mapování podporuje zadávání omezení verzí. Pokud aktuální databricks --version hodnota není v mezích zadaných v mapování sady databricks_cli_version , dojde k chybě při databricks bundle validate spuštění v sadě. Následující příklady ukazují některé běžné syntaxe omezení verzí:

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

proměnné

Soubor nastavení sad může obsahovat jedno mapování nejvyšší úrovně variables , kde jsou definovány vlastní proměnné. Pro každou proměnnou nastavte volitelný popis, výchozí hodnotu, bez ohledu na to, jestli je vlastní proměnná komplexním typem, nebo vyhledáním načtěte hodnotu ID pomocí následujícího formátu:

variables:
  <variable-name>:
    description: <variable-description>
    default: <optional-default-value>
    type: <optional-type-value> # "complex" is the only valid value
    lookup:
      <optional-object-type>: <optional-object-name>

Poznámka:

Proměnné se předpokládají jako typ string, pokud type nejsou nastaveny na complexhodnotu . Viz Definice komplexní proměnné.

Pokud chcete odkazovat na vlastní proměnnou v rámci konfigurace sady, použijte náhradu ${var.<variable_name>}.

Další informace o vlastních proměnných a nahrazování najdete v tématu Nahrazení a proměnné v sadě prostředků Databricks.

pracovní plocha

Konfigurační soubor sady může obsahovat pouze jedno mapování nejvyšší úrovně workspace , které určuje všechna výchozí nastavení pracovního prostoru Azure Databricks, která se mají použít.

root_path

Toto workspace mapování může obsahovat root_path mapování určující ne výchozí kořenovou cestu, která se má použít v rámci pracovního prostoru pro nasazení i spuštění pracovního postupu, například:

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

Ve výchozím nastavení používá rozhraní root_path příkazového /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}řádku Databricks výchozí cestu , která používá náhrady.

artifact_path

Toto workspace mapování může také obsahovat artifact_path mapování, které určuje cestu artefaktu, která není výchozí, která se má použít v rámci pracovního prostoru pro nasazení i spuštění pracovního postupu, například:

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

Ve výchozím nastavení používá rozhraní artifact_path příkazového ${workspace.root}/artifactsřádku Databricks výchozí cestu , která používá náhrady.

Poznámka:

Mapování artifact_path nepodporuje cesty systému souborů Databricks (DBFS).

file_path

Toto workspace mapování může také obsahovat file_path mapování určující cestu k souboru, která není výchozí, která se má použít v rámci pracovního prostoru pro nasazení i spuštění pracovního postupu, například:

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

Ve výchozím nastavení používá rozhraní file_path příkazového ${workspace.root}/filesřádku Databricks výchozí cestu , která používá náhrady.

state_path

Mapování state_path se ve výchozím nastavení nastaví na výchozí cestu ${workspace.root}/state a představuje cestu v rámci pracovního prostoru pro uložení informací o stavu Terraformu o nasazeních.

Mapování jiných pracovních prostorů

Mapování workspace může také obsahovat následující volitelná mapování, která určují mechanismus ověřování Azure Databricks, který se má použít. Pokud nejsou v rámci tohoto workspace mapování zadány, musí být zadány v workspace mapování jako podřízené z jednoho nebo více cílů v mapování cílů nejvyšší úrovně.

Důležité

Pro následující workspace mapování pro ověřování Azure Databricks musíte pevně zakódovat hodnoty kódu. Pomocí syntaxe například nemůžete zadat vlastní proměnné pro hodnoty ${var.*} těchto mapování.

• Mapování profile (nebo --profile -p možnosti při spuštění sady prostředků ověřte, nasaďte, spusťte a zničíte příkazy pomocí Rozhraní příkazového řádku Databricks) určuje název konfiguračního profilu, který se má použít s tímto pracovním prostorem pro ověřování Azure Databricks. Tento konfigurační profil se mapuje na profil, který jste vytvořili při nastavování rozhraní příkazového řádku Databricks.

  Poznámka:

  Databricks doporučuje, abyste místo mapování použili host mapování (nebo --profile možnosti nebo -p možnosti při spuštění balíčku ověření, nasazení, spuštění a zničení příkazů pomocí Rozhraní příkazového řádku Databricks), profile protože díky tomu jsou konfigurační soubory sady přenosnější. host Nastavení mapování dává rozhraní příkazového řádku Databricks pokyn k vyhledání odpovídajícího profilu v .databrickscfg souboru a následné použití polí daného profilu k určení typu ověřování Databricks, který se má použít. Pokud v .databrickscfg souboru existuje více profilů s odpovídajícím host polem, musíte použít profile mapování (nebo --profile -p možnosti příkazového řádku) a instruovat rozhraní příkazového řádku Databricks o tom, který profil použít. Příklad najdete v prod cílové deklaraci v příkladech.

• Mapování host určuje adresu URL vašeho pracovního prostoru Azure Databricks. Viz adresa URL pro jednotlivé pracovní prostory.

• Pro ověřování M2M (machine-to-machine) OAuth se používá mapování client_id . Alternativně můžete tuto hodnotu nastavit v místní proměnné DATABRICKS_CLIENT_IDprostředí . Nebo můžete vytvořit konfigurační profil s client_id hodnotou a pak zadat název profilu pomocí profile mapování (nebo pomocí --profile možností -p při spuštění balíčku ověření, nasazení, spuštění a zničení příkazů pomocí Rozhraní příkazového řádku Databricks). Viz Ověření přístupu k Azure Databricks pomocí instančního objektu pomocí OAuth (OAuth M2M).

  Poznámka:

  V konfiguračním souboru sady nemůžete zadat hodnotu tajného klíče Azure Databricks OAuth. Místo toho nastavte místní proměnnou DATABRICKS_CLIENT_SECRETprostředí . Nebo můžete přidat client_secret hodnotu do konfiguračního profilu a pak zadat název profilu pomocí profile mapování (nebo pomocí --profile nebo -p možností při spuštění sady ověření, nasazení, spuštění a zničení příkazů pomocí Rozhraní příkazového řádku Databricks).

• Pro ověřování Azure CLI se používá mapování azure_workspace_resource_id . Alternativně můžete tuto hodnotu nastavit v místní proměnné DATABRICKS_AZURE_RESOURCE_IDprostředí . Nebo můžete vytvořit konfigurační profil s azure_workspace_resource_id hodnotou a pak zadat název profilu pomocí profile mapování (nebo pomocí --profile možností -p při spuštění balíčku ověření, nasazení, spuštění a zničení příkazů pomocí Rozhraní příkazového řádku Databricks). Viz ověřování Azure CLI.

• Pro ověřování tajných kódů klienta Azure s instančními objekty azure_workspace_resource_idazure_tenant_idse používají mapování a azure_client_id používají se. Alternativně můžete tyto hodnoty nastavit v místních proměnných DATABRICKS_AZURE_RESOURCE_IDprostředí , ARM_TENANT_IDa ARM_CLIENT_IDv uvedeném pořadí. Nebo můžete vytvořit konfigurační profil s azure_workspace_resource_idhodnotou , azure_tenant_ida azure_client_id hodnoty a pak zadat název profilu s profile mapováním (nebo pomocí --profile nebo -p možností při spuštění sady ověření, nasazení, spuštění a zničení příkazů pomocí Rozhraní příkazového řádku Databricks). Viz ověřování instančního objektu MS Entra.

  Poznámka:

  V konfiguračním souboru sady nelze zadat hodnotu tajného klíče klienta Azure. Místo toho nastavte místní proměnnou ARM_CLIENT_SECRETprostředí . Nebo můžete přidat azure_client_secret hodnotu do konfiguračního profilu a pak zadat název profilu pomocí profile mapování (nebo pomocí --profile nebo -p možností při spuštění sady ověření, nasazení, spuštění a zničení příkazů pomocí Rozhraní příkazového řádku Databricks).

• Pro ověřování spravovaných identit Azure se používají mapování azure_use_msiazure_client_ida azure_workspace_resource_id používají se. Alternativně můžete tyto hodnoty nastavit v místních proměnných ARM_USE_MSIprostředí , ARM_CLIENT_IDa DATABRICKS_AZURE_RESOURCE_IDv uvedeném pořadí. Nebo můžete vytvořit konfigurační profil s azure_use_msihodnotou , azure_client_ida azure_workspace_resource_id hodnoty a pak zadat název profilu s profile mapováním (nebo pomocí --profile nebo -p možností při spuštění sady ověření, nasazení, spuštění a zničení příkazů pomocí Rozhraní příkazového řádku Databricks). Viz ověřování spravovaných identit Azure.

• Mapování azure_environment určuje typ prostředí Azure (například Public, UsGov, Čína a Německo) pro konkrétní sadu koncových bodů rozhraní API. Výchozí hodnota je PUBLIC. Alternativně můžete tuto hodnotu nastavit v místní proměnné ARM_ENVIRONMENTprostředí . Nebo můžete přidat azure_environment hodnotu do konfiguračního profilu a pak zadat název profilu pomocí profile mapování (nebo pomocí --profile nebo -p možností při spuštění sady ověření, nasazení, spuštění a zničení příkazů pomocí Rozhraní příkazového řádku Databricks).

• Mapování azure_login_app_id není funkční a je vyhrazené pro interní použití.

• Mapování auth_type určuje typ ověřování Azure Databricks, který se má použít, zejména v případech, kdy rozhraní příkazového řádku Databricks odvodí neočekávaný typ ověřování. Podívejte se na přístup k ověřování k prostředkům Azure Databricks.

dovolení

Mapování nejvyšší úrovně permissions určuje jednu nebo více úrovní oprávnění, které se mají použít pro všechny prostředky definované v sadě. Pokud chcete u konkrétního prostředku použít oprávnění, přečtěte si téma Definovat oprávnění pro konkrétní prostředek.

Povolené úrovně oprávnění nejvyšší úrovně jsou CAN_VIEW, CAN_MANAGEa CAN_RUN.

Následující příklad v konfiguračním souboru sady definuje úrovně oprávnění pro uživatele, skupinu a instanční objekt, které se použijí pro všechny úlohy, kanály, experimenty a modely definované v resources sadě:

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

Artefakty

Mapování nejvyšší úrovně artifacts určuje jeden nebo více artefaktů, které se automaticky sestavují během nasazení sady prostředků a lze je použít později při spuštění sady. Každý podřízený artefakt podporuje následující mapování:

• type je povinné. Chcete-li před nasazením sestavit soubor kola Pythonu, musí být toto mapování nastaveno na whl.
• path je volitelná relativní cesta z umístění konfiguračního souboru sady do umístění souboru kola Pythonu setup.py . Pokud path není zahrnutý, rozhraní příkazového řádku Databricks se pokusí najít soubor setup.py kola Pythonu v kořenovém adresáři sady.
• files je volitelné mapování, které zahrnuje podřízené source mapování, které můžete použít k určení jiných než výchozích umístění, která mají být zahrnuta pro složité pokyny k sestavení. Umístění se zadají jako relativní cesty z umístění konfiguračního souboru sady.
• build je volitelná sada nenástavbových příkazů sestavení, které chcete spustit místně před nasazením. V případě sestavení kol Pythonu rozhraní příkazového řádku Databricks předpokládá, že dokáže najít místní instalaci balíčku Pythonu wheel ke spuštění sestavení a při každém nasazení sady sada spustí příkaz python setup.py bdist_wheel ve výchozím nastavení. Pokud chcete zadat více příkazů sestavení, oddělte každý příkaz dvojitým ampersandem (&&) znaky.

Další informace, včetně ukázkové sady, která se používá artifacts, najdete v tématu Vývoj souboru kola Pythonu pomocí sad prostředků Databricks.

Tip

Nastavení artefaktů v balíčcích můžete definovat, kombinovat a přepsat pomocí technik popsaných v nastavení artefaktů dynamicky v sadách prostředků Databricks.

zahrnovat

Pole include určuje seznam cest globů, které obsahují konfigurační soubory, které se mají zahrnout do sady. Tyto globy cesty jsou relativní vzhledem k umístění konfiguračního souboru sady, ve kterém jsou zadány globy cesty.

Rozhraní příkazového řádku Databricks ve výchozím nastavení neobsahuje žádné konfigurační soubory v rámci sady. Pole musíte použít include k určení všech konfiguračních souborů, které se mají zahrnout do sady, kromě samotného databricks.yml souboru.

Toto include pole se může zobrazit pouze jako mapování nejvyšší úrovně.

Následující příklad konfigurace obsahuje tři konfigurační soubory. Tyto soubory jsou ve stejné složce jako konfigurační soubor sady:

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

Následující příklad konfigurace zahrnuje všechny soubory s názvy souborů, které začínají bundle a končí na .yml. Tyto soubory jsou ve stejné složce jako konfigurační soubor sady:

include:
  - "bundle*.yml"

prostředky

Mapování resources určuje informace o prostředcích Azure Databricks používaných sadou prostředků.

Toto resources mapování se může zobrazit jako mapování nejvyšší úrovně nebo může být podřízeným objektem jednoho nebo více cílů v mapování cílů nejvyšší úrovně a zahrnuje nula nebo jeden z podporovaných typů prostředků. Každé mapování typu prostředku zahrnuje jednu nebo více jednotlivých deklarací prostředků, které musí mít jedinečný název. Tyto deklarace jednotlivých prostředků k definování prostředku používají datovou část požadavku odpovídajícího objektu create, vyjádřenou v YAML. Podporované vlastnosti prostředku jsou odpovídající podporovaná pole objektu.

Datové části žádosti o vytvoření operace jsou zdokumentované v referenčních informacích k rozhraní REST API Databricks a databricks bundle schema příkaz vypíše všechna podporovaná schémata objektů. Příkaz navíc vrátí upozornění, databricks bundle validate pokud se v konfiguračních souborech sady nacházejí neznámé vlastnosti prostředků.

Následující tabulka uvádí podporované typy prostředků pro sady prostředků a odkazy na dokumentaci odpovídajících datových částí.

Typ prostředku	Mapování prostředků
svazky	Mapování clusterů: POST /api/2.1/jobs/create
práce	Mapování úloh: POST /api/2.1/jobs/create Další informace najdete v tématu Typy úloh úloh a přepsání nastavení nového clusteru úloh.
potrubí	Mapování kanálů: POST /api/2.0/pipelines/create
experiment	Mapování experimentů: POST /api/2.0/mlflow/experiments/create
model	Mapování modelů: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint	Mapování koncových bodů obsluhy modelu: POST /api/2.0/serving-endpoints/create
registered_model (katalog Unity)	Mapování modelů katalogu Unity: POST /api/2.1/unity-catalog/models/create
schema (Katalog Unity)	Mapování schématu katalogu Unity: POST /api/2.1/unity-catalog/schemas/create

Všechny cesty ke složkám a souborům odkazovaným deklaracemi prostředků jsou relativní vzhledem k umístění konfiguračního souboru sady, ve kterém jsou tyto cesty zadány.

svazky

Prostředek clusters umožňuje vytvářet clustery pro všechny účely. Následující příklad vytvoří cluster s názvem my_cluster a nastaví ho jako cluster, který se použije ke spuštění poznámkového bloku v my_job:

bundle:
  name: clusters

resources:
  clusters:
    my_cluster:
      num_workers: 2
      node_type_id: "i3.xlarge"
      autoscale:
        min_workers: 2
        max_workers: 7
      spark_version: "13.3.x-scala2.12"
      spark_conf:
        "spark.executor.memory": "2g"

  jobs:
    my_job:
      tasks:
        - task_key: test_task
          existing_cluster_id: ${resources.clusters.my_cluster.id}
          notebook_task:
            notebook_path: "./src/my_notebook.py"

úloha

Následující příklad deklaruje úlohu s klíčem hello-jobprostředku :

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

potrubí

Následující příklad deklaruje kanál s klíčem hello-pipelineprostředku :

resources:
  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

schema

Typ schema prostředku umožňuje definovat schémata katalogu Unity pro tabulky a další prostředky v pracovních postupech a kanálech vytvořených jako součást sady prostředků. Schéma, které se liší od jiných typů prostředků, má následující omezení:

• Vlastník prostředku schématu je vždy uživatelem nasazení a nelze ho změnit. Pokud run_as je v sadě zadán, operace ve schématu budou ignorovány.
• Pro prostředek jsou k dispozici pouze pole podporovaná odpovídajícím rozhraním API pro schema vytvoření objektu schémat. Například se nepodporuje, enable_predictive_optimization protože je k dispozici pouze v rozhraní API aktualizace.

Následující příklad deklaruje kanál s klíčem my_pipeline prostředku, který vytvoří schéma katalogu Unity s klíčem my_schema jako cílem:

resources:
  pipelines:
    my_pipeline:
      name: test-pipeline-{{.unique_id}}
      libraries:
        - notebook:
            path: ./nb.sql
      development: true
      catalog: main
      target: ${resources.schemas.my_schema.id}

  schemas:
    my_schema:
      name: test-schema-{{.unique_id}}
      catalog_name: main
      comment: This schema was created by DABs.

Sady prostředků Databricks nepodporují mapování grantů nejvyšší úrovně, takže pokud chcete nastavit granty pro schéma, definujte granty schématu schemas v rámci mapování:

schemas:
    my_schema:
      name: test-schema
      grants:
        - principal: users
          privileges:
            - CAN_MANAGE
        - principal: my_team
          privileges:
            - CAN_READ
      catalog_name: main
      comment: "my schema with grants"

synchronizovat

Mapování sync umožňuje nakonfigurovat, které soubory jsou součástí nasazení sady prostředků.

zahrnutí a vyloučení

Mapování include a exclude mapování v rámci sync mapování určuje seznam souborů nebo složek, které se mají zahrnout do nebo vyloučit z nasazení sady, v závislosti na následujících pravidlech:

• Na základě libovolného seznamu souborů a globů cest v souboru v .gitignore kořenovém adresáři include sady může mapování obsahovat seznam globů souborů, cest globů nebo obojího vzhledem ke kořenovému adresáři sady, aby bylo možné explicitně zahrnout.
• Na základě libovolného seznamu globů souborů a cest v souboru v .gitignore kořenovém adresáři sady a seznamu zástupných znaků souboru a cesty v include mapování exclude může mapování obsahovat seznam globů souborů, globů cest nebo obojího vzhledem ke kořenovému adresáři sady, aby bylo možné explicitně vyloučit.

Všechny cesty k zadaným souborům a složkám jsou relativní vzhledem k umístění konfiguračního souboru sady, ve kterém jsou zadané.

Syntaxe vzorů include souborů a exclude cest se řídí standardní .gitignore syntaxí vzorů. Viz formát vzoru Gitignore.

Pokud například následující .gitignore soubor obsahuje následující položky:

.databricks
my_package/dist

Konfigurační soubor sady obsahuje následující include mapování:

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

Všechny soubory ve my_package/dist složce s příponou *.whl souboru jsou zahrnuty. Žádné jiné soubory ve my_package/dist složce nejsou zahrnuty.

Pokud však konfigurační soubor sady obsahuje také následující exclude mapování:

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

Všechny soubory ve my_package/dist složce s příponou *.whlsouboru s výjimkou souboru s názvem delete-me.whl, jsou zahrnuty. Všechny ostatní soubory ve složce se také nezahrnou my_package/dist .

Mapování sync lze také deklarovat v targets mapování pro konkrétní cíl. Jakékoli sync mapování deklarované v cíli se sloučí s deklaracemi mapování nejvyšší úrovně sync . Například pokračování v předchozím příkladu následující include mapování na targets úrovni se sloučí s include mapováním v mapování nejvyšší úrovně sync :

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

stezky

Mapování sync může obsahovat paths mapování, které určuje místní cesty k synchronizaci s pracovním prostorem. Mapování paths umožňuje sdílet společné soubory napříč sadami a je možné je použít k synchronizaci souborů umístěných mimo kořen sady. (Kořen sady je umístění souboru databricks.yml.) To je užitečné zejména v případě, že máte jedno úložiště, které hostuje více sad a chcete sdílet knihovny, soubory kódu nebo konfiguraci.

Zadané cesty musí být relativní vzhledem k souborům a adresářům ukotveným ve složce, ve které paths je nastavené mapování. Pokud jedna nebo více hodnot cesty prochází adresářem do nadřazeného adresáře kořenového adresáře sady, je kořenová cesta dynamicky určena, aby se zajistilo, že struktura složek zůstane nedotčená. Pokud je například kořenová složka sady pojmenovaná my_bundle , pak tato konfigurace synchronizuje databricks.yml common složku umístěnou o jednu úroveň nad kořenem sady a samotným kořenem sady:

sync:
  paths:
    - ../common
    - .

Nasazení této sady má za následek následující strukturu složek v pracovním prostoru:

common/
  common_file.txt
my_bundle/
  databricks.yml
  src/
    ...

cíle

Mapování targets určuje jeden nebo více kontextů, ve kterých se mají spouštět pracovní postupy Azure Databricks. Každý cíl je jedinečná kolekce artefaktů, nastavení pracovního prostoru Azure Databricks a podrobnosti o úloze nebo kanálu Azure Databricks.

Mapování targets se skládá z jednoho nebo více cílových mapování, které musí mít jedinečný programový (nebo logický) název.

Toto targets mapování je volitelné, ale důrazně doporučujeme. Pokud je zadaný, může se zobrazit pouze jako mapování nejvyšší úrovně.

Nastavení v pracovním prostoru nejvyšší úrovně, artefaktech a mapování prostředků se použijí, pokud nejsou zadány v targets mapování, ale všechna konfliktní nastavení se přepíše nastavením v rámci cíle.

Cíl může také přepsat hodnoty všech proměnných nejvyšší úrovně.

default

Chcete-li zadat cílové výchozí nastavení pro příkazy sady, nastavte default mapování na true. Tento cíl dev má například výchozí cíl:

targets:
  dev:
    default: true

Pokud není nakonfigurovaný výchozí cíl nebo pokud chcete ověřit, nasadit a spustit úlohy nebo kanály v rámci konkrétního cíle, použijte -t možnost příkazů sady.

Následující příkazy ověřují, nasazují a spouštějí my_job v rámci dev cílů prod :

databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job

databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod my_job

Následující příklad deklaruje dva cíle. První cíl má název dev a je výchozím cílem, který se použije v případě, že pro příkazy sady není zadaný žádný cíl. Druhý cíl má název prod a používá se pouze v případě, že je tento cíl zadán pro příkazy sady.

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

režim a přednastavení

Pro usnadnění snadného vývoje a osvědčených postupů CI/CD poskytuje sady prostředků Databricks režimy nasazení pro cíle, které nastavují výchozí chování pro předprodukční a produkční pracovní postupy. Některé chování je také možné konfigurovat. Podrobnosti najdete v tématu Režimy nasazení sady prostředků Databricks.

Tip

Pokud chcete nastavit identity spuštění pro sady, můžete pro každý cíl zadat run_as identitu spuštění, jak je popsáno v části Určení identity spuštění pro pracovní postup Sady prostředků Databricks.

Chcete-li určit, že cíl je považován za cíl vývoje, přidejte mode mapování nastavené na development. Chcete-li určit, že cíl je považován za produkční cíl, přidejte mode mapování nastavené na production. Tento název cíle prod se například považuje za produkční cíl:

targets:
  prod:
    mode: production

Některá chování můžete přizpůsobit pomocí presets mapování. Seznam dostupných předvoleb najdete v tématu Vlastní předvolby. Následující příklad ukazuje přizpůsobený produkční cíl, který předpony a značky všechny produkční prostředky:

targets:
  prod:
    mode: production
    presets:
      name_prefix: "production_"  # prefix all resource names with production_
      tags:
        prod: true

Pokud jsou obě mode a presets jsou nastavené, přednastavení přepíší výchozí chování režimu. Nastavení jednotlivých prostředků přepíší přednastavení. Pokud je například plán nastavený na UNPAUSED, ale předvolba trigger_pause_status je nastavená na PAUSED, plán se neprůhledně zruší.