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 os Databricks Asset Bundles?.

Para criar e trabalhar com pacotes, consulte Desenvolver pacotes de ativos Databricks.

databricks.yml

Um bundle deve conter um (e apenas um) arquivo de configuração nomeado databricks.yml na raiz da pasta do projeto do bundle. databricks.yml é o arquivo de configuração principal que define um pacote, mas pode fazer referência a include outros arquivos de configuração, como arquivos de configuração de recursos, no mapeamento. A configuração do pacote é expressa em YAML. Para obter mais informações sobre YAML, consulte a especificação oficial YAML.

O mais simples databricks.yml define o nome do bundle, que está dentro do mapeamento de nível superior necessário bundle, assim como uma implantação de destino.

bundle:
  name: my_bundle

targets:
  dev:
    default: true

Para obter detalhes sobre todos os mapeamentos de nível superior, consulte Mapeamentos.

Especificação

A especificação YAML a seguir fornece chaves de configuração de nível superior para Databricks Asset Bundles. Para referência de configuração, consulte Referência de configuração.

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

Exemplos

Esta seção contém alguns exemplos básicos para ajudá-lo a entender como os pacotes funcionam e como estruturar a configuração.

O exemplo de configuração de pacote a seguir especifica um arquivo local chamado hello.py que está no mesmo diretório que o arquivo databricks.ymlde configuração de pacote. Ele executa este notebook como um trabalho usando o cluster remoto com o ID de cluster especificado. 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.

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

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 notebook, mas usa um cluster remoto diferente com a ID do 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

Use os seguintes comandos de bundle para validar, desplegar e executar este trabalho no dev destino. Para obter detalhes sobre o ciclo de vida de um pacote, consulte Desenvolver pacotes de ativos 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

Para validar, implantar e executar este trabalho no prod alvo:

# 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

Para obter mais modularização e melhor reutilização de definições e configurações entre pacotes, divida a configuração do pacote em arquivos separados:

# 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

Mapeamentos

As seções a seguir descrevem os mapeamentos de nível superior de configuração do pacote. Para referência de configuração, consulte Referência de configuração.

• pacote
• run_as
• incluir
• scripts
• sincronização
• artefatos
• variáveis
• espaço de trabalho
• Permissões
• Recursos
• 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 alvos no mapeamento de alvos 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 mapeamento de nível superior bundle não pode ser alterado no nível de destino name.

ID de cluster

O bundle mapeamento pode conter 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 recurso de computação.

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

compute_id

O bundle mapeamento pode conter 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, o que é útil para propagar metadados de implantação que podem ser usados posteriormente para identificar recursos. Por exemplo, você pode rastrear a origem do repositório de um trabalho implantado pelo CI/CD.

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

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.

É possível substituir as configurações origin_url e branch no mapeamento principal de nível git dentro do seu mapeamento bundle, se necessário, da seguinte forma:

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

run_as

A run_as configuração especifica o user_name ou service_principal_name a ser usado para executar o pacote. Ele fornece a capacidade de separar a identidade usada para implantar um trabalho ou pipeline de pacote daquela usada para executá-lo.

Consulte Especificar uma identidade de execução para um workflow de Databricks Asset Bundles.

incluir

A matriz include especifica uma lista de padrões de caminho que contêm ficheiros de configuração a incluir no pacote. Esses padrões de caminho são relativos ao local do ficheiro de configuração do bundle no qual os padrões 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 include para especificar quaisquer arquivos de configuração a serem incluídos no pacote, além do próprio arquivo databricks.yml.

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'

roteiros

A configuração scripts especifica scripts que podem ser executados usando bundle run. Cada script nomeado no scripts mapeamento contém conteúdo com comandos. Por exemplo:

scripts:
  my_script:
    content: uv run pytest -m ${bundle.target}

Para obter mais informações, consulte Executar scripts.

sincronização

O sync mapeamento permite configurar quais ficheiros fazem parte das suas implementações de pacotes.

incluir e excluir

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

• A partir de qualquer lista de globs de ficheiro e de caminho num ficheiro .gitignore na raiz do pacote, o mapeamento include pode conter uma lista de globs de ficheiro, globs de caminho ou ambos, relativos à raiz do pacote, para inclusão explícita.
• Com base em qualquer lista de padrões de pesquisa de ficheiros e caminhos num ficheiro .gitignore na raiz do pacote, além da lista de padrões de pesquisa de ficheiros e caminhos no mapeamento include, o mapeamento exclude pode conter uma lista de padrões de pesquisa de ficheiros, padrões de pesquisa de caminhos ou ambos, relativamente à 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 para padrões de arquivo e caminho include e exclude segue a sintaxe padrão .gitignore. Consulte Formato de padrões gitignore.

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

.databricks
my_package/dist

E o arquivo de configuração do conjunto 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 alvo específico. Qualquer sync mapeamento declarado num destino é combinado com qualquer declaração de mapeamento ao nível sync superior. Por exemplo, continuando com o exemplo anterior, o mapeamento a seguir include no nível targets mescla com o include mapeamento no mapeamento de nível superior sync.

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 conjunto, o caminho raiz será determinado dinamicamente para assegurar que a estrutura das pastas permaneça intacta. Por exemplo, se a pasta raiz do bundle for nomeada my_bundle, então esta configuração sincroniza a pasta databricks.yml localizada um nível acima da pasta raiz do bundle e a própria pasta 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/
    ...

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 subartefato suporta os seguintes mapeamentos:

• type é necessário para construções de roda Python. Para criar um arquivo de roda Python antes de implantar, defina isso como whl. Para criar outros artefatos, essa configuração não precisa ser especificada.
• path é um caminho opcional. Os caminhos são relativos ao local do arquivo de configuração do pacote. Para compilações de roda Python, é o caminho para o arquivo de roda Python setup.py . Se path não estiver incluído, a CLI do Databricks tentará encontrar o ficheiro de roda Python setup.py na raiz do pacote.
• files é um mapeamento opcional que inclui um mapeamento filho source, que pode ser utilizado para especificar os artefatos construídos. Os caminhos são relativos ao 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 as compilações de Python wheel, a CLI do Databricks assume que pode encontrar uma instalação local do pacote Python wheel para executar as compilações e executa o comando python setup.py bdist_wheel por padrão durante cada implementação de bundle. Especifique vários comandos de compilação em linhas separadas.
• dynamic_version Permite que os pacotes atualizem a versão WHEEL com base no carimbo de data/hora do arquivo WHEEL. O novo código pode ser implantado sem a necessidade de atualizar a versão no setup.py ou pyproject.toml. Essa configuração só é válida quando type definida como whl.

O exemplo de configuração a seguir executa testes e cria uma roda. Para obter um tutorial completo do pacote que usa artifacts para construir uma roda, consulte Criar um arquivo de roda Python usando Databricks Asset Bundles.

artifacts:
  default:
    type: whl
    build: |-
      # run tests
      python -m pytest tests/ -v

      # build the actual artifact
      python setup.py bdist_wheel

    path: .

Para obter um exemplo de configuração que cria um JAR e o carrega no Unity Catalog, consulte Bundle que carrega um arquivo JAR no Unity Catalog.

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>

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.

caminho_raiz

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.

caminho_do_artefato

Esse workspace mapeamento pode também conter um artifact_path mapeamento para especificar um caminho de artefato não padrão a ser utilizado no espaço de trabalho, tanto para implementações quanto para 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.

caminho_do_ficheiro

Este workspace mapeamento também pode conter um file_path mapeamento para especificar um caminho de ficheiro não padrão a ser utilizado dentro do espaço de trabalho para desdobramentos 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.

caminho_do_estado

O mapeamento state_path tem como valor padrão o caminho padrão de ${workspace.root}/state e representa o caminho dentro do seu espaço de trabalho para armazenar informações de estado do Terraform relativas a 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 neste workspace mapeamento, deverão ser especificados num workspace mapeamento como filho de um ou mais dos alvos no mapeamento de alvos de nível superior.

• O mapeamento profile, (ou as opções --profile ou -p ao executar os comandos validate, deploy, run, e destroy com a CLI do Databricks) especifica o nome de um perfil de configuração para utilizar com este espaço de trabalho para autenticação no Azure Databricks. Este perfil de configuração corresponde ao que criou ao configurar a CLI do Databricks.

  Nota

  A Databricks recomenda que utilize o mapeamento host (ou as opções --profile ou -p ao executar os comandos validate, deploy, run e destroy com o Databricks CLI) em vez do mapeamento profile, pois isso torna os arquivos de configuração do pacote mais portáteis. A definição do host mapeamento instrui a CLI do Databricks a encontrar um perfil correspondente no seu .databrickscfg arquivo e, em seguida, utilizar os campos desse perfil para determinar o tipo de autenticação do Databricks que deve ser usado. Se existirem vários perfis com um campo correspondente host no seu ficheiro .databrickscfg, deve utilizar o mapeamento profile (ou as opções de linha de comando --profile ou -p) 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 a URL por área 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 pode criar um perfil de configuração com o valor client_id e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usando as opções --profile ou -p ao executar os comandos validar, implantar, executar e destruir do bundle com a CLI do Databricks). Consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.

  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 . Pode-se adicionar o valor client_secret a um perfil de configuração e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usando as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com o Databricks CLI).

• 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 pode criar um perfil de configuração com o valor azure_workspace_resource_id e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usando as opções --profile ou -p ao executar os comandos validar, implantar, executar e destruir do bundle com a CLI do Databricks). Consulte Autenticar com a 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. Pode-se criar um perfil de configuração com os azure_workspace_resource_id, azure_tenant_id e azure_client_id valores, em seguida, especificar o nome do perfil com o profile mapeamento (ou usando as --profile ou -p opções ao executar os comandos validate, deploy, run, e destroy do bundle com a Databricks CLI). Consulte princípios de serviço Autenticar com Microsoft 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 . Pode-se adicionar o valor azure_client_secret a um perfil de configuração e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usando as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com o Databricks CLI).

• 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. Pode-se criar um perfil de configuração com os azure_use_msi, azure_client_id e azure_workspace_resource_id valores, em seguida, especificar o nome do perfil com o profile mapeamento (ou usando as --profile ou -p opções ao executar os comandos validate, deploy, run, e destroy do bundle com a Databricks CLI). Consulte Autenticar com 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 . Pode-se adicionar o valor azure_environment a um perfil de configuração e, em seguida, especificar o nome do perfil com o mapeamento profile (ou usando as opções --profile ou -p ao executar os comandos validar pacote, implantar, executar e destruir com o Databricks CLI).

• O azure_login_app_id mapeamento é não 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 Autorizar 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 recursos 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

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 payloads de solicitação de operação de criação estão documentadas na Referência da API REST do Databricks, e o comando databricks bundle schema gera todos os esquemas de objetos 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.

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 alvo, e cada um deve ter 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, mapeamentos de artefactos e recursos são utilizadas se não forem especificadas num mapeamento, mas quaisquer configurações conflitantes são substituídas pelas configurações dentro de um alvo.

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

predefinição

Para especificar um padrão de destino para comandos de agrupamento, defina o mapeamento de default para 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 caso deseje validar, desdobrar e executar trabalhos ou pipelines num destino específico, utilize a opção -t dos comandos bundle.

Comandos a seguir validam, implantam e executam my_job nos alvos dev e prod:

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

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

O seguinte exemplo declara dois alvos. 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.

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, defina o mapeamento mode para 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 tanto mode quanto presets estiverem 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.