Configurações 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.

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
• Exemplos
• Mapeamentos
• Variáveis personalizadas
• Substituições

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.

# These is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  compute_id: string
  git:
    origin_url: string
    branch: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string or complex

# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

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

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

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the Experiments API's create experiment request payload reference.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See the Jobs API's create job request payload reference.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the Models API's create model request payload reference.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the Delta Live Tables API's create pipeline request payload reference.

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

# 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.
    compute_id: string
    default: true | false
    mode: development
    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

A seguir está um exemplo de arquivo de configuração de pacote. Este pacote especifica a implantação remota de um arquivo local chamado hello.py que está no mesmo diretório que esse arquivo de configuração do 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.

Nota

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

A seguir está o exemplo modularizado anterior, mas com a adição de um destino com o nome prod programático (ou lógico) 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, execute os seguintes comandos:

# 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, execute os seguintes comandos:

# 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

Para obter mais exemplos, consulte o repositório de exemplos de pacote no GitHub.

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.

compute_id

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 todo e qualquer cluster definido em outro lugar no arquivo de configuração do pacote. Essa substituição destina-se a cenários somente de desenvolvimento antes da produção. O compute_id mapeamento funciona apenas para o destino que tem seu mode mapeamento definido como development. Para obter mais informações sobre o compute_id mapeamento, consulte o mapeamento de destinos .

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 para especificar as configurações de variáveis a serem usadas. Consulte Variáveis personalizadas.

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.

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: /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 /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, que usa substituições.

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: /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).

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: /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.

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.

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 Usar uma entidade de serviço para autenticar com o Azure Databricks.

  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 Microsoft Entra ID.

  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 o campo Tipo de autenticação.

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 a seguir em um arquivo de configuração de pacote inclui os três arquivos de configuração especificados. Esses arquivos estão no mesmo diretório que o arquivo de configuração do pacote:

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

O exemplo a seguir em um arquivo de configuração de pacote inclui todos os arquivos com nomes de arquivo que começam com bundle e terminam com .yml. Esses arquivos estão no mesmo diretório 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
jobs	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.
pipelines	Mapeamentos de pipeline: POST /api/2.0/pipelines
experiments	Mapeamentos de experimentos: POST /api/2.0/mlflow/experiments/create
models	Mapeamentos de modelo: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoints	Modelo servindo mapeamentos de ponto final: POST /api/2.0/serving-endpoints
registered_models (Catálogo Unity)	Mapeamentos de modelo de catálogo Unity: POST /api/2.1/unity-catalog/models

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.

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

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py
  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

sincronização

O sync mapeamento especifica uma lista de globs de arquivo ou caminho a serem incluídos em implantações de pacote ou a serem 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 pastas e arquivos especificados são relativos ao local do arquivo de configuração do pacote no qual esses caminhos 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

Quando você executa databricks bundle validate --output jsono , a parte relevante do gráfico resultante é a seguinte:

"sync": {
  "include": [
    "my_package/dist/*.whl",
    "my_package/dist/delete-me.whl"
  ],
  "exclude": [
    "my_package/dist/delete-me.whl"
  ]
}

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.

Este targets mapeamento é opcional, mas altamente recomendado. Se for especificado, ele pode aparecer apenas como um mapeamento de nível superior. Se o targets mapeamento não for especificado, as configurações no espaço de trabalho de nível superior, artefatos e mapeamentos de recursos serão sempre usados.

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

Se um mapeamento de destino não especificar workspace, artifactsou resources mapeamentos filho, esse destino usará as configurações nos mapeamentos de nível workspacesuperior , artifactse resources .

Se um mapeamento de destino especificar um workspace, artifactsou resources mapeamento, e um , de nível workspacesuperior , artifactsou resources mapeamento também existir, todas as configurações conflitantes serão substituídas pelas configurações dentro do destino.

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

Para especificar que um destino é o padrão, a menos que especificado de outra forma, adicione o default mapeamento, definido como true. Por exemplo, esse destino chamado dev é o destino padrão:

targets:
  dev:
    default: true

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

targets:
  prod:
    mode: production

A especificação mode fornece uma coleção de comportamentos padrão correspondentes para fluxos de trabalho de pré-produção e produção. Para obter detalhes, consulte Modos de implantação do Databricks Asset Bundle. Além disso, 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.

O exemplo a seguir declara dois destinos. O primeiro destino tem um nome programático (ou lógico) de dev e é o destino padrão. O segundo destino tem um nome programático (ou lógico) de prod e não é o destino padrão. Este segundo destino usa um perfil de conexão do Azure Databricks nomeado PROD para autenticação:

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

Para validar, implantar e executar trabalhos ou pipelines no dev destino, execute os seguintes comandos:

# 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 <job-or-pipeline-programmatic-name>

# 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 <job-or-pipeline-programmatic-name>

Para validar, implantar e executar esse trabalho no prod destino, execute os seguintes comandos:

# 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 <job-or-pipeline-programmatic-name>

Variáveis personalizadas

Você pode usar variáveis personalizadas para tornar seus arquivos de configuração de pacote mais modulares e reutilizáveis. Por exemplo, você pode declarar uma variável que representa a ID de um cluster existente e, em seguida, desejar alterar o valor dessa variável para IDs de cluster diferentes para vários fluxos de trabalho executados em vários destinos sem alterar o código original dos arquivos de configuração do pacote.

As variáveis personalizadas são declaradas em seus arquivos de configuração de pacote dentro do variables mapeamento. Para cada variável, defina uma descrição opcional, valor padrão, tipo ou pesquisa para recuperar um valor de ID, usando o seguinte formato:

variables:
  <variable-name>:
    description: <optional-description>
    default: <optional-default-value>
    type: <optional-type-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.

Por exemplo, para declarar uma variável nomeada my_cluster_id com o valor padrão de 1234-567890-abcde123, e uma variável nomeada my_notebook_path com o valor padrão de ./hello.py:

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

Se você não fornecer um default valor para uma variável como parte dessa declaração, deverá defini-lo ao executar comandos bundle, por meio de uma variável de ambiente ou em qualquer outro lugar dentro de seus arquivos de configuração de pacote, conforme descrito em Definir o valor de uma variável.

Nota

Seja qual for a abordagem escolhida para fornecer valores variáveis, use a mesma abordagem durante os estágios de implantação e execução. Caso contrário, você pode obter resultados inesperados entre o momento de uma implantação e uma execução de trabalho ou pipeline baseada nessa implantação existente.

Para fazer referência às variáveis personalizadas nos arquivos de configuração do pacote, use substituições. Para variáveis, use o formato ${var.<variable_name>}. Por exemplo, para referenciar variáveis nomeadas my_cluster_id e my_notebook_path:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

Definir o valor de uma variável

Se você não tiver fornecido um default valor para uma variável ou se quiser substituir temporariamente o default valor de uma variável, forneça o novo valor temporário da variável usando uma das seguintes abordagens:

• Forneça o valor da variável como parte de um bundle comando como validate, deployou run. Para fazer isso, use a opção --var="<key>=<value>", onde <key> é o nome da variável e <value> é o valor da variável. Por exemplo, como parte do bundle validate comando, para fornecer o valor de 1234-567890-abcde123 para a variável nomeada my_cluster_id, e para fornecer o valor de ./hello.py para a variável chamada my_notebook_path, execute:

  databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"
  
  # Or:
  databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
  

• Forneça o valor da variável definindo uma variável de ambiente. O nome da variável de ambiente deve começar com BUNDLE_VAR_. Para definir variáveis de ambiente, consulte a documentação do seu sistema operacional. Por exemplo, para fornecer o valor de para a variável nomeada my_cluster_id, e para fornecer o valor de para a variável nomeada my_notebook_path, execute o seguinte comando antes de ./hello.py 1234-567890-abcde123 chamar um bundle comando como validate, deploy, ou run:

  Para Linux e macOS:

  export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
  

  Para Windows:

  "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
  

  Ou, forneça o valor da variável como parte de um bundle comando como validate, deployou run, por exemplo, para Linux e macOS:

  BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
  

  Ou para Windows:

  "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
  

• Forneça o valor da variável em seus arquivos de configuração de pacote. Para fazer isso, use um variables mapeamento dentro do targets mapeamento, seguindo este formato:

  variables:
    <variable-name>: <value>
  

  Por exemplo, para fornecer valores para as variáveis nomeadas my_cluster_id e my_notebook_path para dois destinos separados:

  targets:
    dev:
      variables:
        my_cluster_id: 1234-567890-abcde123
        my_notebook_path: ./hello.py
    prod:
      variables:
        my_cluster_id: 2345-678901-bcdef234
        my_notebook_path: ./hello.py
  

Nos exemplos anteriores, a CLI do Databricks procura valores para as variáveis my_cluster_id e my_notebook_path na seguinte ordem, parando quando encontra um valor para cada variável correspondente, ignorando quaisquer outros locais para essa variável:

1. Dentro de quaisquer --var opções especificadas como parte do bundle comando.
2. Dentro de qualquer conjunto de variáveis de ambiente que comece com BUNDLE_VAR_.
3. Dentro de quaisquer variables mapeamentos, entre os mapeamentos dentro de targets seus arquivos de configuração de pacote.
4. Qualquer default valor para a definição dessa variável, entre os mapeamentos de nível variables superior dentro dos arquivos de configuração do pacote.

Definir uma variável complexa

Para definir uma variável personalizada com um tipo complexo para seu pacote, defina type como complex em sua configuração de pacote.

Nota

O único valor válido para a type configuração é complex. Além disso, a validação do pacote falhará se type estiver definida como complex e o default definido para a variável for um único valor.

No exemplo a seguir, as configurações de cluster são definidas dentro de uma variável complexa personalizada chamada my_cluster:

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

Recuperar o valor de ID de um objeto

Para os alerttipos de objeto , cluster_policy, cluster, dashboard, instance_pooljob, querymetastoreservice_principalpipelinee , e , você warehouse pode definir um lookup para sua variável personalizada para recuperar a ID

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

Se uma pesquisa for definida para uma variável, a ID do objeto com o nome especificado será usada como o valor da variável. Isso garante que a ID resolvida correta do objeto seja sempre usada para a variável.

Nota

Um erro ocorre se um objeto com o nome especificado não existir ou se houver mais de um objeto com o nome especificado.

Por exemplo, na configuração a seguir, ${var.my_cluster_id} será substituído pela ID do cluster compartilhado 12.2.

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}

Substituições

Você pode usar substituições para tornar seus arquivos de configuração de pacote mais modulares e reutilizáveis.

Gorjeta

Você também pode usar referências de valor dinâmico para valores de parâmetros de trabalho para passar o contexto sobre uma execução de trabalho para tarefas de trabalho. Consulte Passar contexto sobre tarefas de trabalho em tarefas de trabalho.

Por exemplo, quando você executa o bundle validate --output json comando, você pode ver um gráfico como este (as reticências indicam conteúdo omitido, para brevidade):

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

No exemplo anterior, você pode fazer referência ao valor someone@example.com em seu arquivo de configuração de pacote com a substituição ${workspace.current_user.userName}.

Do mesmo modo, as seguintes substituições:

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

Em um arquivo de configuração de pacote como o seguinte (as reticências indicam conteúdo omitido, para brevidade):

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

Resolveria para o seguinte gráfico quando você executar o bundle validate --output json comando (as reticências indicam conteúdo omitido, para brevidade):

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "profile": "DEFAULT",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "root": "/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev",
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

Você também pode criar substituições para recursos nomeados. Por exemplo, para o pipeline configurado com o nome my_pipeline, ${resources.pipelines.my_pipeline.target} é a substituição para o valor do destino de my_pipeline.

Para determinar substituições válidas, você pode usar a hierarquia de esquema documentada na referência da API REST ou a saída do bundle schema comando.

Aqui estão algumas substituições comumente usadas:

• ${bundle.name}
• ${bundle.target} # Use this substitution instead of ${bundle.environment}
• ${workspace.host}
• ${workspace.current_user.short_name}
• ${workspace.current_user.userName}
• ${workspace.file_path}
• ${workspace.root_path}
• ${resources.jobs.<job-name>.id}
• ${resources.models.<model-name>.name}
• ${resources.pipelines.<pipeline-name>.name}