Configuração do Databricks Asset Bundle

Este artigo descreve a sintaxe dos arquivos de configuração do Databricks Asset Bundle, que definem o Databricks Asset Bundles. Consulte O que são Databricks Asset Bundles?

Para criar e trabalhar com pacotes, consulte de desenvolvimento do Databricks Asset Bundles .

Descrição geral

Um arquivo de configuração de pacote deve ser expresso no formato YAML e deve conter, no mínimo, o mapeamento de pacote de nível superior. Cada pacote deve conter pelo menos um (e apenas um) arquivo de configuração de pacote chamado databricks.yml. Se houver vários arquivos de configuração de pacote, eles devem ser referenciados databricks.yml pelo arquivo usando o include mapeamento.

Para obter detalhes sobre cada mapeamento de nível superior, consulte Mapeamentos.

Para obter mais informações sobre o YAML, consulte a especificação oficial do YAML e o tutorial.

Especificação

O YAML a seguir fornece especificação de configuração para Databricks Asset Bundles.

# 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
  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:
  clusters:
    <some-unique-programmatic-identifier-for-this-cluster>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <some-unique-programmatic-identifier-for-this-dashboard>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See REST API create request payload reference for jobs.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the REST API create request payload reference for models.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the REST API create request payload reference for Delta Live Tables (pipelines).
  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.

Exemplos

Nota

Para obter exemplos de configuração que demonstram recursos de pacote e casos de uso comuns de pacote, consulte Exemplos de configuração de pacote e o repositório de exemplos de pacote no GitHub.

O exemplo de configuração de pacote a seguir especifica um arquivo local chamado hello.py que está no mesmo diretório que esse arquivo de configuração de pacote local chamado databricks.yml. Ele executa este bloco de anotações como um trabalho usando o cluster remoto com a ID de cluster especificada. A URL do espaço de trabalho remoto e as credenciais de autenticação do espaço de trabalho são lidas a partir do perfil de configuração local do chamador chamado DEFAULT.

O Databricks recomenda que você use o host mapeamento em vez do mapeamento sempre que possível, pois isso torna os arquivos de configuração do default pacote mais portáteis. A definição do host mapeamento instrui a CLI do Databricks a encontrar um perfil correspondente em seu .databrickscfg arquivo e, em seguida, usar os campos desse perfil para determinar qual tipo de autenticação do Databricks usar. Se existirem vários perfis com um campo correspondente host em seu .databrickscfg arquivo, você deverá usar o profile para instruir a CLI do Databricks sobre qual perfil específico usar. Para obter um exemplo, consulte a declaração de prod destino mais adiante nesta seção.

Essa técnica permite que você reutilize, bem como substitua as definições e configurações de trabalho dentro do resources bloco :

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

Embora o seguinte arquivo de configuração do pacote seja funcionalmente equivalente, ele não é modularizado, o que não permite uma boa reutilização. Além disso, esta declaração acrescenta uma tarefa ao trabalho, em vez de substituir o trabalho existente:

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

O exemplo a seguir adiciona um destino com o nome prod que usa uma URL de espaço de trabalho remoto diferente e credenciais de autenticação de espaço de trabalho, que são lidas da entrada correspondente .databrickscfg do arquivo do chamador host com a URL do espaço de trabalho especificado. Esse trabalho executa o mesmo bloco de anotações, mas usa um cluster remoto diferente com a ID de cluster especificada. Observe que você não precisa declarar o notebook_task mapeamento dentro do prod mapeamento, pois ele volta a usar o notebook_task mapeamento dentro do mapeamento de nível resources superior, se o notebook_task mapeamento não for explicitamente substituído dentro do prod mapeamento.

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

Para validar, implantar e executar esse trabalho no dev destino:

# 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

Para validar, implantar e executar esse trabalho no prod destino:

# 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

A seguir está o exemplo anterior, mas dividido em arquivos de componentes para ainda mais modularização e melhor reutilização em vários arquivos de configuração de pacote. Essa técnica permite que você não apenas reutilize várias definições e configurações, mas também pode trocar qualquer um desses arquivos por outros arquivos que fornecem declarações completamente diferentes:

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

Mapeamentos

As seções a seguir descrevem a sintaxe do arquivo de configuração do pacote, por mapeamento de nível superior.

• pacote
• variáveis
• espaço de trabalho
• permissions (permissões)
• artefatos
• incluem
• Recursos
• sincronização
• Objetivos

pacote

Um arquivo de configuração de pacote deve conter apenas um mapeamento de nível bundle superior que associe o conteúdo do pacote e as configurações do espaço de trabalho do Azure Databricks.

Esse bundle mapeamento deve conter um name mapeamento que especifique um nome programático (ou lógico) para o pacote. O exemplo a seguir declara um pacote com o nome hello-bundleprogramático (ou lógico) .

bundle:
  name: hello-bundle

Um bundle mapeamento também pode ser filho de um ou mais dos destinos no mapeamento de destinos de nível superior. Cada um desses mapeamentos filho bundle especifica quaisquer substituições não padrão no nível de destino. No entanto, o valor do bundle mapeamento de nível name superior não pode ser substituído no nível de destino.

cluster_id

O bundle mapeamento pode ter um mapeamento filho cluster_id . Esse mapeamento permite especificar a ID de um cluster a ser usada como uma substituição para clusters definidos em outro lugar no arquivo de configuração do pacote. Para obter informações sobre como recuperar a ID de um cluster, consulte URL e ID do cluster.

A cluster_id substituição destina-se a cenários somente de desenvolvimento e só é suportada para o destino que tem seu mode mapeamento definido como development. Para obter mais informações sobre o target mapeamento, consulte destinos.

compute_id

Nota

Essa configuração foi preterida. Use cluster_id em vez disso.

O bundle mapeamento pode ter um mapeamento filho compute_id . Esse mapeamento permite especificar a ID de um cluster a ser usada como uma substituição para clusters definidos em outro lugar no arquivo de configuração do pacote.

Git

Você pode recuperar e substituir os detalhes do controle de versão do Git associados ao seu pacote. Isso é útil para anotar os recursos implantados. Por exemplo, talvez você queira incluir a URL de origem do repositório na descrição de um modelo de aprendizado de máquina implantado.

Sempre que você executa um bundle comando como validate, deploy ou run, o bundle comando preenche a árvore de configuração do comando com as seguintes configurações padrão:

• bundle.git.origin_url, que representa o URL de origem do repositório. Este é o mesmo valor que você obteria se executasse o comando git config --get remote.origin.url do seu repositório clonado. Você pode usar substituições para fazer referência a esse valor com seus arquivos de configuração de pacote, como ${bundle.git.origin_url}.
• bundle.git.branch, que representa a ramificação atual dentro do repo. Este é o mesmo valor que você obteria se executasse o comando git branch --show-current do seu repositório clonado. Você pode usar substituições para fazer referência a esse valor com seus arquivos de configuração de pacote, como ${bundle.git.branch}.
• bundle.git.commit, que representa o HEAD compromisso dentro do repo. Este é o mesmo valor que você obteria se executasse o comando git rev-parse HEAD do seu repositório clonado. Você pode usar substituições para fazer referência a esse valor com seus arquivos de configuração de pacote, como ${bundle.git.commit}.

Para recuperar ou substituir as configurações do Git, seu pacote deve estar dentro de um diretório associado a um repositório Git, por exemplo, um diretório local que é inicializado executando o git clone comando. Se o diretório não estiver associado a um repositório Git, essas configurações do Git estarão vazias.

Você pode substituir as origin_url configurações e branch dentro do git mapeamento do seu mapeamento de nível bundle superior, se necessário, da seguinte maneira:

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

databricks_cli_version

O bundle mapeamento pode conter um databricks_cli_version mapeamento que restringe a versão da CLI do Databricks exigida pelo pacote. Isso pode evitar problemas causados pelo uso de mapeamentos que não são suportados em uma determinada versão da CLI do Databricks.

A versão da CLI do Databricks está em conformidade com o controle de versão semântico e o mapeamento suporta a databricks_cli_version especificação de restrições de versão. Se o valor atual databricks --version não estiver dentro dos limites especificados no mapeamento do databricks_cli_version pacote, ocorrerá um erro quando databricks bundle validate for executado no pacote. Os exemplos a seguir demonstram algumas sintaxe de restrição de versão comum:

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

variáveis

O arquivo de configurações de pacotes pode conter um mapeamento de nível variables superior onde as variáveis personalizadas são definidas. Para cada variável, defina uma descrição opcional, um valor padrão, se a variável personalizada é um tipo complexo, ou uma pesquisa para recuperar um valor de ID, usando o seguinte formato:

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>

Nota

As variáveis são assumidas como sendo do tipo string, a menos que type seja definido como complex. Consulte Definir uma variável complexa.

Para fazer referência a uma variável personalizada dentro da configuração do pacote, use a substituição ${var.<variable_name>}.

Para obter mais informações sobre variáveis personalizadas e substituições, consulte Substituições e variáveis em Databricks Asset Bundles.

espaço de trabalho

O arquivo de configuração do pacote pode conter apenas um mapeamento de nível workspace superior para especificar quaisquer configurações não padrão do espaço de trabalho do Azure Databricks a serem usadas.

Importante

Os caminhos válidos do espaço de trabalho Databricks começam com um ou /Workspace/Volumes. Os caminhos de espaço de trabalho personalizados são automaticamente prefixados com /Workspace, portanto, se você usar qualquer substituição de caminho de espaço de trabalho em seu caminho personalizado, como ${workspace.file_path}, não precisará anexar /Workspace o caminho.

root_path

Esse workspace mapeamento pode conter um root_path mapeamento para especificar um caminho raiz não padrão a ser usado no espaço de trabalho para implantações e execuções de fluxo de trabalho, por exemplo:

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

Por padrão, para root_path o Databricks CLI usa o caminho padrão de /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, que usa substituições.

artifact_path

Esse workspace mapeamento também pode conter um artifact_path mapeamento para especificar um caminho de artefato não padrão a ser usado no espaço de trabalho para implantações e execuções de fluxo de trabalho, por exemplo:

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

Por padrão, para artifact_path o Databricks CLI usa o caminho padrão de ${workspace.root}/artifacts, que usa substituições.

Nota

O artifact_path mapeamento não suporta caminhos do sistema de arquivos Databricks (DBFS).

file_path

Esse workspace mapeamento também pode conter um file_path mapeamento para especificar um caminho de arquivo não padrão a ser usado no espaço de trabalho para implantações e execuções de fluxo de trabalho, por exemplo:

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

Por padrão, para file_path o Databricks CLI usa o caminho padrão de ${workspace.root}/files, que usa substituições.

state_path

O state_path mapeamento assume como padrão o caminho padrão e representa o caminho dentro do espaço de trabalho para armazenar informações de estado do ${workspace.root}/state Terraform sobre implantações.

Outros mapeamentos de espaço de trabalho

O workspace mapeamento também pode conter os seguintes mapeamentos opcionais para especificar o mecanismo de autenticação do Azure Databricks a ser usado. Se eles não forem especificados nesse workspace mapeamento, eles deverão ser especificados em um workspace mapeamento como filho de um ou mais dos destinos no mapeamento de destinos de nível superior.

Importante

Você deve codificar valores para os mapeamentos a seguir workspace para autenticação do Azure Databricks. Por exemplo, não é possível especificar variáveis personalizadas para os valores desses mapeamentos usando a ${var.*} sintaxe.

• O profile mapeamento (ou as opções ou --profile ao -p executar os comandos de validação, implantação, execução e destruição do pacote com a CLI do Databricks) especifica o nome de um perfil de configuração a ser usado com esse espaço de trabalho para autenticação do Azure Databricks. Esse perfil de configuração é mapeado para aquele que você criou quando configurou a CLI do Databricks.

  Nota

  O Databricks recomenda que você use o host mapeamento (ou as --profile opções ou -p ao executar os comandos de validação, implantação, execução e destruição do pacote com a CLI do Databricks) em vez do mapeamento, pois isso torna os arquivos de configuração do profile pacote mais portáteis. A definição do host mapeamento instrui a CLI do Databricks a encontrar um perfil correspondente em seu .databrickscfg arquivo e, em seguida, usar os campos desse perfil para determinar qual tipo de autenticação do Databricks usar. Se existirem vários perfis com um campo correspondente host em seu .databrickscfg arquivo, você deverá usar o profile mapeamento (ou as opções de --profile-p linha de comando) para instruir a CLI do Databricks sobre qual perfil usar. Para obter um exemplo, consulte a prod declaração de destino nos exemplos.

• O host mapeamento especifica a URL para seu espaço de trabalho do Azure Databricks. Consulte URL por espaço de trabalho.

• Para autenticação OAuth máquina-a-máquina (M2M), o mapeamento client_id é usado. Como alternativa, você pode definir esse valor na variável DATABRICKS_CLIENT_IDde ambiente local . Ou você pode criar um perfil de configuração com o client_id valor e, em seguida, especificar o nome do perfil com o profile mapeamento (ou usando as --profile opções ou -p ao executar o bundle validar, implantar, executar e destruir comandos com a CLI do Databricks). Consulte Autenticar o acesso ao Azure Databricks com uma entidade de serviço usando OAuth (OAuth M2M).

  Nota

  Não é possível especificar um valor secreto OAuth do Azure Databricks no arquivo de configuração do pacote. Em vez disso, defina a variável DATABRICKS_CLIENT_SECRETde ambiente local . Ou você pode adicionar o client_secret valor a um perfil de configuração e, em seguida, especificar o nome do perfil com o profile mapeamento (ou usando as --profile opções ou -p ao executar o pacote validar, implantar, executar e destruir comandos com a CLI do Databricks).

• Para a autenticação da CLI do Azure, o mapeamento azure_workspace_resource_id é usado. Como alternativa, você pode definir esse valor na variável DATABRICKS_AZURE_RESOURCE_IDde ambiente local . Ou você pode criar um perfil de configuração com o azure_workspace_resource_id valor e, em seguida, especificar o nome do perfil com o profile mapeamento (ou usando as --profile opções ou -p ao executar o bundle validar, implantar, executar e destruir comandos com a CLI do Databricks). Consulte Autenticação da CLI do Azure.

• Para a autenticação de segredo do cliente do Azure com entidades de serviço, os mapeamentos azure_workspace_resource_id, azure_tenant_ide azure_client_id são usados. Como alternativa, você pode definir esses valores nas variáveis DATABRICKS_AZURE_RESOURCE_IDde ambiente local , ARM_TENANT_ID, e ARM_CLIENT_ID, respectivamente. Ou você pode criar um perfil de configuração com os azure_workspace_resource_idvalores , azure_tenant_ide e azure_client_id , em seguida, especificar o nome do perfil com o profile mapeamento (ou usando as --profile opções ou -p ao executar o bundle validar, implantar, executar e destruir comandos com a CLI do Databricks). Consulte Autenticação da entidade de serviço do MS Entra.

  Nota

  Não é possível especificar um valor de segredo do cliente do Azure no arquivo de configuração do pacote. Em vez disso, defina a variável ARM_CLIENT_SECRETde ambiente local . Ou você pode adicionar o azure_client_secret valor a um perfil de configuração e, em seguida, especificar o nome do perfil com o profile mapeamento (ou usando as --profile opções ou -p ao executar o pacote validar, implantar, executar e destruir comandos com a CLI do Databricks).

• Para autenticação de identidades gerenciadas do Azure, os mapeamentos azure_use_msi, azure_client_ide azure_workspace_resource_id são usados. Como alternativa, você pode definir esses valores nas variáveis ARM_USE_MSIde ambiente local , ARM_CLIENT_ID, e DATABRICKS_AZURE_RESOURCE_ID, respectivamente. Ou você pode criar um perfil de configuração com os azure_use_msivalores , azure_client_ide e azure_workspace_resource_id , em seguida, especificar o nome do perfil com o profile mapeamento (ou usando as --profile opções ou -p ao executar o bundle validar, implantar, executar e destruir comandos com a CLI do Databricks). Consulte Autenticação de identidades gerenciadas do Azure.

• O azure_environment mapeamento especifica o tipo de ambiente do Azure (como Público, UsGov, China e Alemanha) para um conjunto específico de pontos de extremidade de API. O valor predefinido é PUBLIC. Como alternativa, você pode definir esse valor na variável ARM_ENVIRONMENTde ambiente local . Ou você pode adicionar o azure_environment valor a um perfil de configuração e, em seguida, especificar o nome do perfil com o profile mapeamento (ou usando as --profile opções ou -p ao executar o pacote validar, implantar, executar e destruir comandos com a CLI do Databricks).

• O azure_login_app_id mapeamento não está operacional e está reservado para uso interno.

• O auth_type mapeamento especifica o tipo de autenticação do Azure Databricks a ser usado, especialmente nos casos em que a CLI do Databricks infere um tipo de autenticação inesperado. Consulte Autenticar acesso aos recursos do Azure Databricks.

Permissões

O mapeamento de nível permissions superior especifica um ou mais níveis de permissão a serem aplicados a todos os recursos definidos no pacote. Se quiser aplicar permissões a um recurso específico, consulte Definir permissões para um recurso específico.

Os níveis de permissão de nível superior permitidos são CAN_VIEW, CAN_MANAGEe CAN_RUN.

O exemplo a seguir em um arquivo de configuração de pacote define níveis de permissão para um usuário, grupo e entidade de serviço, que são aplicados a todos os trabalhos, pipelines, experimentos e modelos definidos no resources pacote:

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

artefatos

O mapeamento de nível artifacts superior especifica um ou mais artefatos que são criados automaticamente durante implantações de pacote e podem ser usados posteriormente em execuções de pacote. Cada artefato filho suporta os seguintes mapeamentos:

• type é obrigatório. Para construir um arquivo de roda Python antes da implantação, esse mapeamento deve ser definido como whl.
• path é um caminho relativo opcional do local do arquivo de configuração do pacote para o local do arquivo de roda do Python setup.py . Se path não estiver incluída, a CLI do Databricks tentará encontrar o arquivo do arquivo setup.py de roda Python na raiz do pacote.
• files é um mapeamento opcional que inclui um mapeamento filho source , que você pode usar para especificar locais não padrão a serem incluídos para instruções de compilação complexas. Os locais são especificados como caminhos relativos a partir do local do arquivo de configuração do pacote.
• build é um conjunto opcional de comandos de compilação não padrão que você deseja executar localmente antes da implantação. Para compilações de roda Python, a CLI do Databricks assume que pode encontrar uma instalação local do pacote Python wheel para executar compilações e executa o comando python setup.py bdist_wheel por padrão durante cada implantação de pacote. Para especificar vários comandos build, separe cada comando com caracteres duplos e (&&).

O exemplo de configuração a seguir cria uma roda usando Poetry:

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

Para obter um pacote de exemplo completo que usa artifacts, consulte Desenvolver um arquivo de roda Python usando Databricks Asset Bundles.

Gorjeta

Você pode definir, combinar e substituir as configurações de artefactos em pacotes de acordo com o descrito em Definir configurações de artefactos nos Databricks Asset Bundles.

incluem

A include matriz especifica uma lista de globs de caminho que contêm arquivos de configuração a serem incluídos no pacote. Esses globs de caminho são relativos ao local do arquivo de configuração do pacote no qual os globs de caminho são especificados.

A CLI do Databricks não inclui nenhum arquivo de configuração por padrão no pacote. Você deve usar a matriz para especificar todos e include quaisquer arquivos de configuração a serem incluídos no pacote, além do databricks.yml próprio arquivo.

Essa include matriz pode aparecer apenas como um mapeamento de nível superior.

O exemplo de configuração a seguir inclui três arquivos de configuração. Esses arquivos estão na mesma pasta que o arquivo de configuração do pacote:

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

O exemplo de configuração a seguir inclui todos os arquivos com nomes de arquivo que começam com bundle e terminam com .yml. Esses arquivos estão na mesma pasta que o arquivo de configuração do pacote:

include:
  - "bundle*.yml"

Recursos

O resources mapeamento especifica informações sobre os recursos do Azure Databricks usados pelo pacote.

Esse mapeamento de resources pode aparecer como um mapeamento de nível superior, ou pode ser filho de um ou mais dos destinos presentes no mapeamento de nível superior de destinos , e inclui zero ou um dos tipos de recursos suportados. Cada mapeamento de tipo de recurso inclui uma ou mais declarações de recursos individuais, que devem ter um nome exclusivo. Essas declarações de recurso individuais usam a carga útil de solicitação da operação create do objeto correspondente, expressa em YAML, para definir o recurso. As propriedades suportadas para um recurso são os campos suportados do objeto correspondente.

As cargas úteis de solicitação de operação de criação são documentadas na Referência da API REST do Databricks e o databricks bundle schema comando gera a saída de todos os esquemas de objeto suportados. Além disso, o databricks bundle validate comando retorna avisos se propriedades de recursos desconhecidas forem encontradas nos arquivos de configuração do pacote.

O exemplo de configuração a seguir define um recurso de trabalho:

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

Para obter mais informações sobre recursos suportados em bundles, bem como configurações e exemplos comuns, consulte Recursos do Databricks Asset Bundles e Exemplos de Configuração do Bundle.

sincronização

O sync mapeamento permite configurar quais arquivos fazem parte de suas implantações de pacote.

incluir e excluir

Os include mapeamentos e exclude dentro do sync mapeamento especificam uma lista de arquivos ou pastas a serem incluídos ou excluídos de implantações de pacote, dependendo das seguintes regras:

• Com base em qualquer lista de globs de arquivo e caminho em um .gitignore arquivo na raiz do pacote, o include mapeamento pode conter uma lista de globs de arquivo, globs de caminho ou ambos, relativos à raiz do pacote, para incluir explicitamente.
• Com base em qualquer lista de globs de arquivo e caminho em um .gitignore arquivo na raiz do pacote, além da lista de globs de arquivo e caminho no include mapeamento, o exclude mapeamento pode conter uma lista de globs de arquivo, globs de caminho ou ambos, em relação à raiz do pacote, para excluir explicitamente.

Todos os caminhos para arquivos e pastas especificados são relativos ao local do arquivo de configuração do pacote no qual eles são especificados.

A sintaxe e includeexclude os padrões de arquivo e caminho seguem a sintaxe padrão padrão .gitignore . Consulte Formato de padrão gitignore.

Por exemplo, se o seguinte .gitignore ficheiro contiver as seguintes entradas:

.databricks
my_package/dist

E o arquivo de configuração do pacote contém o seguinte include mapeamento:

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

Em seguida, todos os arquivos na my_package/dist pasta com uma extensão de arquivo de *.whl estão incluídos. Quaisquer outros arquivos na my_package/dist pasta não estão incluídos.

No entanto, se o arquivo de configuração do pacote também contiver o seguinte exclude mapeamento:

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

Em seguida, todos os arquivos na my_package/dist pasta com uma extensão de arquivo de *.whl, exceto o arquivo chamado delete-me.whl, são incluídos. Quaisquer outros arquivos na my_package/dist pasta também não estão incluídos.

O sync mapeamento também pode ser declarado no targets mapeamento para um destino específico. Qualquer sync mapeamento declarado em um destino é mesclado com qualquer declaração de mapeamento de nível sync superior. Por exemplo, continuando com o exemplo anterior, o mapeamento a seguir include no nível mescla targets com o include mapeamento no mapeamento de nível sync superior:

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

Caminhos

O sync mapeamento pode conter um paths mapeamento que especifica caminhos locais para sincronizar com o espaço de trabalho. O paths mapeamento permite que você compartilhe arquivos comuns entre pacotes e pode ser usado para sincronizar arquivos localizados fora da raiz do pacote. (A raiz do pacote é o local do arquivo databricks.yml.) Isso é especialmente útil quando você tem um único repositório que hospeda vários pacotes e deseja compartilhar bibliotecas, arquivos de código ou configuração.

Os caminhos especificados devem ser relativos a arquivos e diretórios ancorados na pasta onde o paths mapeamento está definido. Se um ou mais valores de caminho atravessarem o diretório até um ancestral da raiz do pacote, o caminho raiz será determinado dinamicamente para garantir que a estrutura da pasta permaneça intacta. Por exemplo, se a pasta raiz do bundle for nomeada my_bundle , essa configuração sincronizará databricks.yml a common pasta localizada um nível acima da raiz do bundle e a própria raiz do bundle:

sync:
  paths:
    - ../common
    - .

Uma implantação desse pacote resulta na seguinte estrutura de pastas no espaço de trabalho:

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

Objetivos

O targets mapeamento especifica um ou mais contextos nos quais executar fluxos de trabalho do Azure Databricks. Cada destino é uma coleção exclusiva de artefatos, configurações de espaço de trabalho do Azure Databricks e detalhes do trabalho ou pipeline do Azure Databricks.

O targets mapeamento consiste em um ou mais mapeamentos de destino, cada um com um nome programático (ou lógico) exclusivo.

Este targets mapeamento é opcional, mas altamente recomendado. Se for especificado, ele pode aparecer apenas como um mapeamento de nível superior.

As configurações no espaço de trabalho de nível targets

Um destino também pode substituir os valores de quaisquer variáveis de nível superior.

default

Para especificar um padrão de destino para comandos de pacote, defina o default mapeamento como true. Por exemplo, esse destino chamado dev é o destino padrão:

targets:
  dev:
    default: true

Se um destino padrão não estiver configurado ou se você quiser validar, implantar e executar trabalhos ou pipelines em um destino específico, use a -t opção dos comandos bundle.

Os comandos a seguir validam, implantam e executam my_job dentro dos dev e prod destinos:

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

O exemplo a seguir declara dois destinos. O primeiro destino tem o nome dev e é o destino padrão usado quando nenhum destino é especificado para comandos de pacote. O segundo destino tem o nome prod e é usado somente quando esse destino é especificado para comandos bundle.

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

modo e predefinições

Para facilitar o desenvolvimento fácil e as práticas recomendadas de CI/CD, o Databricks Asset Bundles fornece modos de implantação para destinos que definem comportamentos padrão para fluxos de trabalho de pré-produção e produção. Alguns comportamentos também são configuráveis. Para obter detalhes, consulte Modos de implantação do Databricks Asset Bundle.

Gorjeta

Para definir identidades de execução para pacotes, você pode especificar run_as para cada destino, conforme descrito em Especificar uma identidade de execução para um fluxo de trabalho Databricks Asset Bundles.

Para especificar que um destino é tratado como um destino de desenvolvimento, adicione o mode conjunto de mapeamento a development. Para especificar que um destino é tratado como um destino de produção, adicione o conjunto de mode mapeamentos a production. Por exemplo, esse destino nomeado prod é tratado como um destino de produção:

targets:
  prod:
    mode: production

Você pode personalizar alguns dos comportamentos usando o presets mapeamento. Para obter uma lista de predefinições disponíveis, consulte Predefinições personalizadas. O exemplo a seguir mostra um destino de produção personalizado que prefixa e marca todos os recursos de produção:

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

Se ambos mode estiverem presets definidos, as predefinições substituem o comportamento do modo padrão. As configurações de recursos individuais substituem as predefinições. Por exemplo, se uma agenda estiver definida como UNPAUSED, mas a trigger_pause_status predefinição estiver definida como PAUSED, a agenda não será pausada.