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?

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 mais informações sobre o YAML, consulte a especificação oficial do YAML e o tutorial.

Para criar e trabalhar com arquivos de configuração de pacote, consulte Desenvolvimento de pacotes de ativos Databricks.

Descrição geral

Esta seção fornece uma representação visual do esquema do arquivo de configuração do pacote. Para obter detalhes, consulte Mapeamentos.

# 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:
  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 host do arquivo do chamador .databrickscfg 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 name mapeamento de nível bundle 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 -p ao --profile 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 (&&).

Para obter mais informações, incluindo um pacote de exemplo que usa artifactso , consulte Desenvolver um arquivo de roda Python usando Databricks Asset Bundles.

Gorjeta

Você pode definir, combinar e substituir as configurações de artefatos em bundles usando as técnicas descritas em Definir configurações de artefato dinamicamente em 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 resources mapeamento pode aparecer como um mapeamento de nível superior ou pode ser filho de um ou mais dos destinos no mapeamento de destinos de nível superior 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.

A tabela a seguir lista os tipos de recursos suportados para pacotes e links para a documentação sobre suas cargas úteis correspondentes.

Tipo de recurso	Mapeamentos de recursos
aglomeração	Mapeamentos de cluster: POST /api/2.1/clusters/create
Painel de instrumentos	Mapeamentos de painel: POST /api/2.0/lakeview/dashboards
experimentação	Mapeamentos de experimentos: POST /api/2.0/mlflow/experiments/create
emprego	Mapeamentos de trabalho: POST /api/2.1/jobs/create Para obter informações adicionais, consulte Tipos de tarefas de trabalho e substituir novas configurações de cluster de trabalho.
gasoduto	Mapeamentos de pipeline: POST /api/2.0/pipelines
modelo	Mapeamentos de modelo: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint	Modelo servindo mapeamentos de ponto final: POST /api/2.0/serving-endpoints
registered_model (Catálogo Unity)	Mapeamentos de modelo do Unity Catalog: POST /api/2.1/unity-catalog/models
esquema (Catálogo Unity)	Mapeamentos de esquema do Unity Catalog: POST /api/2.1/unity-catalog/schemas

Todos os caminhos para pastas e arquivos referenciados por declarações de recursos são relativos ao local do arquivo de configuração do pacote no qual esses caminhos são especificados.

cluster

O recurso de cluster permite criar clusters para todos os fins. O exemplo a seguir cria um cluster chamado my_cluster e o define como o cluster a ser usado para executar o bloco de anotações em 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"

Dashboard

O recurso de painel permite que você gerencie painéis de IA/BI em um pacote. Para obter informações sobre painéis de IA/BI, consulte Painéis.

O exemplo a seguir inclui e implanta o painel de exemplo NYC Taxi Trip Analysis no espaço de trabalho Databricks.

resources:
  dashboards:
    nyc_taxi_trip_analysis:
      display_name: "NYC Taxi Trip Analysis"
      file_path: ../src/nyc_taxi_trip_analysis.lvdash.json
      warehouse_id: ${var.warehouse_id}

Se você usar a interface do usuário para modificar o painel, as modificações feitas por meio da interface do usuário não serão aplicadas ao arquivo JSON do painel no pacote local, a menos que você o atualize explicitamente usando bundle generate. Você pode usar a --watch opção para pesquisar continuamente e recuperar alterações no painel. Consulte Gerar um arquivo de configuração de pacote.

Além disso, se você tentar implantar um pacote que contenha um arquivo JSON de painel diferente daquele no espaço de trabalho remoto, ocorrerá um erro. Para forçar a implantação e substituir o painel no espaço de trabalho remoto pelo local, use a --force opção. Consulte Implantar um pacote.

tarefa

O exemplo a seguir declara um trabalho com a chave de recurso de hello-job:

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

gasoduto

O exemplo a seguir declara um pipeline com a chave de recurso de hello-pipeline:

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

esquema

O tipo de recurso de esquema permite definir esquemas do Catálogo Unity para tabelas e outros ativos em seus fluxos de trabalho e pipelines criados como parte de um pacote. Um esquema, diferente de outros tipos de recursos, tem as seguintes limitações:

• O proprietário de um recurso de esquema é sempre o usuário de implantação e não pode ser alterado. Se run_as for especificado no pacote, ele será ignorado pelas operações no esquema.
• Somente os campos suportados pela API de criação do objeto Schemas correspondente estão disponíveis para o schema recurso. Por exemplo, não é suportado, enable_predictive_optimization pois só está disponível na API de atualização.

O exemplo a seguir declara um pipeline com a chave my_pipeline de recurso que cria um esquema Unity Catalog com a chave my_schema como destino:

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.

Um mapeamento de concessões de nível superior não é suportado pelo Databricks Asset Bundles, portanto, se você quiser definir concessões para um esquema, defina as concessões para o esquema dentro do schemas mapeamento:

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"

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 include exclude 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 superior, artefatos e mapeamentos de recursos são usadas se não forem especificadas em um targets mapeamento, mas quaisquer configurações conflitantes são substituídas pelas configurações dentro de um destino.

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.