Configurazione del bundle di asset di Databricks

Questo articolo descrive la sintassi per i file di configurazione del bundle di asset di Databricks, che definiscono i bundle di asset di Databricks. Consulta Che cosa sono i pacchetti di risorse di Databricks?.

Per creare e usare bundle, vedere Sviluppare bundle di asset di Databricks.

Per informazioni di riferimento sulla configurazione del bundle, vedere Informazioni di riferimento sulla configurazione.

databricks.yml

Un bundle deve contenere un file di configurazione (e solo uno) denominato databricks.yml nella radice della cartella del progetto bundle. databricks.yml è il file di configurazione principale che definisce un bundle, ma può fare riferimento ad altri file di configurazione, ad esempio i file di configurazione delle include risorse, nel mapping. La configurazione del bundle è espressa in YAML. Per altre informazioni su YAML, vedere la specifica YAML ufficiale.

Il più semplice databricks.yml definisce il nome del bundle, ovvero un mapping di primo livello obbligatorio e una distribuzione di destinazione.

bundle:
  name: my_bundle

targets:
  dev:
    default: true

Per informazioni dettagliate su tutti i mapping di primo livello, vedere Informazioni di riferimento sulla configurazione.

Suggerimento

Il supporto python per i bundle di asset di Databricks consente di definire le risorse in Python. Vedere Configurazione del bundle in Python.

Specificazione

La specifica YAML seguente fornisce chiavi di configurazione di primo livello per i bundle di asset di Databricks. Per informazioni di riferimento sulla configurazione, vedere Informazioni di riferimento sulla configurazione.

# This 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
  deployment: Map
  git:
    origin_url: string
    branch: string

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

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

# These are any scripts that can be run.
scripts:
  <some-unique-script-name>:
    content: string

# 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 default artifact settings if not otherwise overridden in
# the targets top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    dynamic_version: boolean
    executable: string
    files:
      - source: string
    path: string
    type: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string or complex
    lookup: Map
    type: string # The only valid value is "complex" if the variable is a complex variable, otherwise do not define this key.

# These are the default workspace settings if not otherwise overridden in
# the 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. 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
  resource_path: string
  root_path: string
  state_path: string

# These are the permissions to apply to resources 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 resource settings if not otherwise overridden in
# the targets top-level mapping.
resources:
  apps:
    <unique-app-name>:
      # See the REST API create request payload reference for apps.
  clusters:
    <unique-cluster-name>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <unique-dashboard-name>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <unique-experiment-name>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <unique-job-name>:
      # See REST API create request payload reference for jobs.
  model_serving_endpoint:
    <unique-model-serving-endpoint-name>:
    # See the model serving endpoint request payload reference.
  models:
    <unique-model-name>:
      # See the REST API create request payload reference for models (legacy).
  pipelines:
    <unique-pipeline-name>:
      # See the REST API create request payload reference for :re[LDP] (pipelines).
  quality_monitors:
    <unique-quality-monitor-name>:
    # See the quality monitor request payload reference.
  registered_models:
    <unique-registered-model-name>:
    # See the registered model request payload reference.
  schemas:
    <unique-schema-name>:
      # See the Unity Catalog schema request payload reference.
  secret_scopes:
    <unique-secret-scope-name>:
      # See the secret scope request payload reference.
  volumes:
    <unique-volume-name>:
    # See the Unity Catalog volume request payload reference.

# 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.
    default: boolean
    git: Map
    mode: string
    permissions:
      # See the preceding "permissions" syntax.
    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.

Esempi:

Questa sezione contiene alcuni esempi di base che consentono di comprendere il funzionamento dei bundle e come strutturare la configurazione.

Nota

Per esempi di configurazione che illustrano le funzionalità del bundle e i casi d'uso comuni del bundle, vedere Esempi di configurazione del bundle e il repository di esempi di bundle in GitHub.

La configurazione del bundle di esempio seguente specifica un file locale denominato hello.py che si trova nella stessa directory del file databricks.ymldi configurazione del bundle . Esegue questo notebook come attività utilizzando il cluster remoto con l'ID cluster assegnato. L'URL dell'area di lavoro remota e le credenziali di autenticazione dell'area di lavoro vengono lette dal profilo di configurazione locale del chiamante denominato DEFAULT.

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

Nell'esempio seguente viene aggiunta una destinazione con il nome prod che usa un URL dell'area di lavoro remota e credenziali di autenticazione dell'area di lavoro diverse, che vengono lette dalla voce corrispondente del file del .databrickscfghost chiamante con l'URL dell'area di lavoro specificato. Questo processo esegue lo stesso notebook, ma usa un cluster remoto diverso con l'ID cluster specificato.

Nota

Databricks consiglia di usare il mapping host invece del mapping default laddove possibile, in quanto rende i file di configurazione del bundle più portabili. L'impostazione del host mapping indica all'interfaccia della riga di comando di Databricks di trovare un profilo corrispondente nel .databrickscfg file e quindi usare i campi del profilo per determinare il tipo di autenticazione di Databricks da usare. Se esistono più profili con un campo corrispondente host , è necessario usare l'opzione --profile nei comandi bundle per specificare un profilo da usare.

Si noti che non è necessario dichiarare il mapping notebook_taskall'interno del mapping prod, perché esegue il fallback per usare il mapping notebook_task all'interno del mapping di primo livello resources, se il mapping notebook_task non viene sottoposto esplicitamente a override all'interno del mapping prod.

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

Usare i comandi bundle seguenti per convalidare, distribuire ed eseguire questo processo all'interno della dev destinazione. Per informazioni dettagliate sul ciclo di vita di un bundle, vedere Sviluppo dei Bundle di Asset di Databricks.

# 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

Per convalidare, distribuire ed eseguire questo processo all'interno della destinazione prod invece:

# 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

Per una maggiore modularizzazione e un migliore riutilizzo delle definizioni e delle impostazioni tra bundle, suddividere la configurazione del bundle in file separati:

# databricks.yml

bundle:
  name: hello-bundle

include:
  - '*.yml'

# hello-job.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

# 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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-02-14