Configurações do pacote ativo do Databricks

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

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

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 pacotes, consulte Fluxo de trabalho de desenvolvimento de pacotes ativos do Databricks.

Visão geral

Esta seção fornece uma representação visual do esquema do arquivo de configuração do pacote configurável. 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

# 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 configurável. Este pacote configurável especifica a implementação remota de um arquivo local denominado hello.py que está no mesmo diretório que este arquivo de configuração de pacote configurável local denominado databricks.yml. Ele executa este Notebook como um Job usando os clusters remotos com o ID clusters especificado. A URL workspace remoto e as credenciais de autenticação workspace são lidas no perfil de configuração local do chamador denominado DEFAULT.

Observação

A Databricks recomenda que você use o mapeamento host em vez do mapeamento default sempre que possível, pois isso torna os arquivos de configuração do pacote mais portáteis. Definir o mapeamento host instrui a CLI do Databricks a encontrar um perfil correspondente em seu arquivo .databrickscfg 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 host correspondente em seu arquivo .databrickscfg , você deverá usar o profile para instruir a CLI do Databricks sobre qual perfil específico usar. Por exemplo, consulte a declaração de destino prod posteriormente nesta seção.

Essa técnica permite reutilizar e substituir as definições e configurações Job no bloco resources:

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 arquivo de configuração do pacote a seguir seja funcionalmente equivalente, ele não é modularizado, o que não permite uma boa reutilização. Além disso, esta declaração anexa uma tarefa ao Job em vez de substituir o existente Job:

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 programático (ou lógico) prod que usa uma URL de workspace remoto diferente e credenciais de autenticação workspace , que são lidas a partir do arquivo .databrickscfg correspondente do chamador host entrada com o URL workspace especificado. Este Job executa o mesmo Notebook , mas usa clusters remotos diferentes com o ID clusters especificado. Observe que você não precisa declarar o mapeamento notebook_task dentro do mapeamento prod , pois ele volta a usar o mapeamento notebook_task dentro do mapeamento resources de nível superior, se o mapeamento notebook_task não for explicitamente substituído no mapeamento prod .

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

Para validar, implantar e executar este Job dentro do target dev, 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 este Job dentro do alvo prod, 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 configurável. Essa técnica permite não apenas reutilizar várias definições e configurações, mas também swap 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 pacotes no GitHub.

Mapeamentos

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

feixe

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

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

bundle:
  name: hello-bundle

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

computar

O mapeamento bundle pode ter um mapeamento compute_id filho. Esse mapeamento permite especificar o ID de um clusters para usar como uma substituição para todo e qualquer clusters definido em outro lugar no arquivo de configuração do pacote configurável. Essa substituição destina-se a cenários somente de desenvolvimento antes da produção. O mapeamento compute_id funciona apenas para o destino que tem seu mapeamento mode definido como development. Para obter mais informações sobre o mapeamento compute_id , consulte o mapeamento de alvos .

git

É possível recuperar e substituir os detalhes do controle de versão do Git que estão associados ao seu pacote. Isso é útil para anotar seu recurso implantado. Por exemplo, talvez o senhor queira incluir o URL de origem do seu repositório na descrição de um modelo de aprendizado de máquina que implantou.

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

• bundle.git.origin_url, que representa a URL de origem do repo. Este é o mesmo valor que você obteria se executasse o comando git config --get remote.origin.url do seu repo clonado. Você pode usar substituições para se referir a esse valor com os arquivos de configuração do pacote, como ${bundle.git.origin_url}.

• bundle.git.branch, que representa o branch atual dentro do repo. Este é o mesmo valor que você obteria se executasse o comando git branch --show-current do seu repo clonado. Você pode usar substituições para se referir a esse valor com os arquivos de configuração do pacote, como ${bundle.git.branch}.

• bundle.git.commit, que representa o commit HEAD dentro do repo. Este é o mesmo valor que você obteria se executasse o comando git rev-parse HEAD do seu repo clonado. Você pode usar substituições para se referir a esse valor com os arquivos de configuração do pacote, como ${bundle.git.commit}.

Para recuperar ou substituir as configurações do Git, seu pacote deve estar em um diretório associado a um repositório Git, por exemplo, um diretório local inicializado executando o comando git clone . 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 configurações origin_url e branch no mapeamento git de seu mapeamento bundle de nível superior, se necessário, da seguinte maneira:

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

CLI

O mapeamento bundle pode conter um mapeamento databricks_cli_version 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 da Databricks.

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

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 configuráveis pode conter um mapeamento variables de nível 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 superior workspace para especificar quaisquer configurações não dodefault Databricks workspace a serem usadas.

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

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

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

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

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

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

..note:: O mapeamento artifact_path não suporta caminhos do Databricks File System (DBFS).

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

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

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

O default de mapeamento state_path para o caminho default de ${workspace.root}/state e representa o caminho em seu workspace para armazenar informações de estado do Terraform sobre implantações.

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

Importante

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

• O mapeamento profile (ou as opções --profile ou -p ao executar o comando bundle activate, implantado, run e destroy com a CLI do Databricks) especifica o nome de um perfil de configuração a ser usado com este workspace para autenticação do Databricks . Este perfil de configuração é mapeado para aquele que você criou ao configurar a CLI do Databricks.

  Observação

  Databricks recomenda que você use o mapeamento host (ou as opções --profile ou -p ao executar o comando bundle activate, implantado, run e destroy com a CLI do Databricks) em vez do mapeamento profile , pois isso faz com que seus arquivos de configuração do pacote mais portáteis. Definir o mapeamento host instrui a CLI do Databricks a encontrar um perfil correspondente no arquivo .databrickscfg 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 host correspondente em seu arquivo .databrickscfg , você deverá usar o mapeamento profile (ou as opções de linha de comando --profile ou -p ) para instruir a CLI do Databricks sobre qual perfil usar. Por exemplo, consulte a declaração de destino prod nos exemplos.

• O mapeamento host especifica a URL para seu workspace do Databricks. Consulte nomes, URLs e IDs de instâncias do 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 de ambiente local DATABRICKS_CLIENT_ID. Ou você pode criar um perfil de configuração com o valor client_id e então especificar o nome do perfil com o mapeamento profile (ou usando as opções --profile ou -p ao executar o pacote validar, implementar, executar e destruir comando com a CLI do Databricks). Consulte Autenticação máquina a máquina (M2M) OAuth.

  Observação

  Você não pode especificar um valor secreto do cliente no arquivo de configuração do pacote configurável. Em vez disso, configure a variável de ambiente local DATABRICKS_CLIENT_SECRET. Ou você pode adicionar o valor client_secret a um perfil de configuração e então especificar o nome do perfil com o mapeamento profile (ou usando as opções --profile ou -p ao executar o pacote validar, implementar, executar e destruir comando com a CLI do Databricks).

• O mapeamento auth_type especifica o tipo de autenticação do 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 permissions de nível 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_MANAGE e 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 principal de serviço, que são aplicados a todos os trabalhos, pipelines, experimentos e modelos definidos em resources no 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 artifacts de nível superior especifica um ou mais artefatos que são construídos automaticamente durante as implementações do pacote configurável e podem ser usados posteriormente na execução do pacote configurável. Cada artefato filho suporta os seguintes mapeamentos:

• type é necessário. Para criar um arquivo Python wheel antes do implantado, 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 setup.py do arquivo Python wheel. Se path não for incluído, o Databricks CLI tentará localizar o arquivo setup.py do arquivo Python wheel na raiz do pacote.

• files é um mapeamento opcional que inclui um mapeamento filho source, que pode ser usado para especificar locais nãodefault a serem incluídos em instruções de compilação complexas. Os locais são especificados como caminhos relativos do local do arquivo de configuração do pacote configurável.

• build é um conjunto opcional de comandos de compilação nãodefault que você deseja executar localmente antes da implantação. Para builds de Python wheel, a CLI do Databricks assume que pode encontrar uma instalação local do pacote Python wheel para compilações de execução e executar o comando python setup.py bdist_wheel por default durante cada implantação de pacote. Para especificar vários comandos de compilação, separe cada comando com caracteres de e comercial duplo (&&).

Para obter mais informações, incluindo um pacote de amostra que usa artifacts, consulte Desenvolver um arquivo Python wheel usando Databricks ativo Bundles.

Dica

Você pode definir, combinar e substituir as configurações de artefatos em pacotes usando as técnicas descritas em Definir configurações de artefatos dinamicamente em Pacotes ativos do Databricks.

incluir

A matriz include 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 configurável no qual os globs de caminho são especificados.

A CLI do Databricks não inclui nenhum arquivo de configuração por default no pacote. Você deve usar a matriz include para especificar todo e qualquer arquivo de configuração a ser incluído no pacote, exceto o próprio arquivo databricks.yml .

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

O exemplo a seguir em um arquivo de configuração de pacote configurável inclui os três arquivos de configuração especificados. Esses arquivos estão no mesmo diretório do 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 que começam com bundle e terminam com .yml. Esses arquivos estão no mesmo diretório do arquivo de configuração do pacote:

include:
  - "bundle*.yml"

recursos

O mapeamento resources especifica informações sobre o recurso Databricks usado pelo pacote.

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

As cargas úteis das solicitações de criação de operações estão documentadas em Databricks REST API Reference, e o comando databricks bundle schema gera todos os esquemas de objetos suportados. Além disso, o comando databricks bundle validate retorna avisos se forem encontradas propriedades de recurso desconhecidas nos arquivos de configuração do pacote.

A tabela a seguir lista os tipos de recurso compatíveis com os pacotes e os links para a documentação sobre as cargas úteis correspondentes.

Tipo de recurso	mapeamentos de recurso
jobs	Job mapeamentos: POST /api/2.1/Job/create Para obter informações adicionais, consulte Job tarefa types and override new Job clusters settings.
pipelines	pipeline mapeamentos: POST /api/2.0/pipelines
experiments	Mapeamentos de experimentos: POST /api/2.0/mlflow/experiments/create
models	Mapeamentos de modelos: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoints	servindo o modelo endpoint mappings: POST /api/2.0/serving-endpoint
registered_models (Catálogo Unity)	Mapeamentos de modelos do Unity Catalog: POST /api/2.1/unity-catalog/models

Todos os caminhos para pastas e arquivos referenciados por declarações de recurso 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 Job com o recurso key de hello-job e um pipeline com o recurso key 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

sincronizar

A matriz sync especifica uma lista de globs de arquivos ou caminhos a serem incluídos nas implantações de pacote configurável ou para excluir das implantações de pacote configurável, dependendo das seguintes regras:

• Com base em qualquer lista de globs de arquivos e caminhos em um arquivo .gitignore na raiz do pacote configurável, o mapeamento include pode conter uma lista de globs de arquivos, globs de caminho ou ambos, relativos à raiz do pacote configurável, para incluir explicitamente.

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

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

A sintaxe para padrões de arquivo e caminho include e exclude segue a sintaxe padrão .gitignore . Consulte Formato do padrão gitignore.

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

.databricks
my_package/dist

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

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

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

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

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

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

A matriz sync também pode ser declarada no mapeamento targets para um destino específico. Qualquer array sync declarado em um destino é merge com qualquer declaração de array sync de nível superior. Por exemplo, continuando com o exemplo anterior, o seguinte mapeamento include no nível targets merge com o mapeamento include na matriz sync de nível superior:

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

Quando você executa databricks bundle validate --output json, 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"
  ]
}

alvos

O mapeamento targets especifica um ou mais contextos nos quais o fluxo de trabalho do Databricks será executado. Cada destino é uma coleção exclusiva de artefatos, configurações workspace do Databricks e detalhes Job ou pipeline do Databricks.

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

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

Se um mapeamento de destino não especificar mapeamentos filhos workspace, artifacts ou resources , esse destino usará as configurações nos mapeamentos de nível superior workspace, artifacts e resources .

Se um mapeamento de destino especificar um mapeamento workspace, artifacts ou resources e também existir um mapeamento de nível superior workspace, artifacts ou resources , quaisquer configurações conflitantes serão substituídas pelas configurações dentro do alvo.

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

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

targets:
  dev:
    default: true

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

targets:
  prod:
    mode: production

A especificação de mode fornece uma coleção de comportamentos default correspondentes para pré-produção e fluxo de trabalho de produção. Para obter detalhes, consulte Databricks ativo Bundle deployment modes. Além disso, o senhor pode especificar run_as para cada destino, conforme descrito em Specify a execution identity for a Databricks ativo Bundles fluxo de trabalho.

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

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

Para validar, implantar e executar Job ou pipelines no destino dev, 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 este Job dentro do alvo prod, 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

O senhor pode usar variáveis personalizadas para tornar os arquivos de configuração do pacote mais modulares e reutilizáveis. Por exemplo, o senhor pode declarar uma variável que represente o ID de um cluster existente e, em seguida, desejar alterar o valor dessa variável para diferentes IDs de clusters para várias execuções de fluxo de trabalho em vários destinos sem alterar o código original dos arquivos de configuração do pacote.

O senhor pode declarar uma ou mais variáveis nos arquivos de configuração do pacote dentro do mapeamento variables. Para cada variável, o senhor pode definir uma descrição opcional, um valor default ou uma pesquisa para recuperar um valor de ID, seguindo este formato:

variables:
  <variable-name>:
    description: <optional-description>
    default: <optional-default-value>
    lookup:
      <optional-object-type>: <optional-object-name>

Por exemplo, para declarar uma variável chamada my_cluster_id com o valor default 1234-567890-abcde123 e uma variável chamada my_notebook_path com o valor default ./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 valor default para uma variável como parte desta declaração, deverá fornecer o valor posteriormente na linha de comando, por meio de uma variável de ambiente ou em outro lugar nos arquivos de configuração do pacote. Essas abordagens são descritas posteriormente nesta seção.

Observação

Seja qual for a abordagem que o senhor escolher para fornecer valores variáveis, use a mesma abordagem durante os estágios de implementação e execução. Caso contrário, o senhor poderá obter resultados inesperados entre o momento de uma implantação e uma execução do Job ou do pipeline que se baseia nessa implantação existente.

Para fazer referência às suas 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 fazer referência a variáveis denominadas 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 o senhor não tiver fornecido um valor default para uma variável ou se quiser substituir temporariamente o valor default de uma variável, forneça o novo valor temporário da variável usando uma das abordagens a seguir:

• Forneça o valor da variável como parte de um comando bundle como validate, deploy ou 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 comando bundle validate , para fornecer o valor de 1234-567890-abcde123 para a variável chamada my_cluster_id e para fornecer o valor de ./hello.py para a variável chamada my_notebook_path, execução:

  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 a variável de ambiente, consulte a documentação do seu sistema operacional. Por exemplo, para fornecer o valor de 1234-567890-abcde123 para a variável chamada my_cluster_id e para fornecer o valor de ./hello.py para a variável chamada my_notebook_path, execute o seguinte comando antes de chamar um comando bundle 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 comando bundle como validate, deploy ou 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 nos arquivos de configuração do pacote. Para fazer isso, use um mapeamento variables dentro do mapeamento targets , seguindo este formato:

  variables:
    <variable-name>: <value>
  

  Por exemplo, para fornecer valores para as variáveis denominadas 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 opções --var especificadas como parte do comando bundle .

2. Dentro de qualquer conjunto de variáveis de ambiente que comece com BUNDLE_VAR_.

3. Dentro de qualquer mapeamento variables , entre os mapeamentos targets nos arquivos de configuração do pacote.

4. Qualquer valor default para a definição dessa variável, entre os mapeamentos variables de nível superior nos arquivos de configuração do pacote.

Recuperar o valor de ID de um objeto

Para os tipos de objeto alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, pipeline, query, service_principal e warehouse, o senhor pode definir um lookup para sua variável personalizada a fim de recuperar o ID de um objeto nomeado usando esse formato:

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.

Observação

Ocorrerá um erro 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 pelo ID dos clusters compartilhados 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 os arquivos de configuração do pacote configurável mais modulares e reutilizáveis.

Dica

O senhor também pode usar referências de valores dinâmicos para valores de parâmetrosJob para passar o contexto de uma execução Job para Job tarefa. Veja o contexto do Pass sobre Job execução em Job tarefa.

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

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

No exemplo anterior, você poderia consultar o valor someone@example.com no arquivo de configuração do pacote com a substituição ${workspace.current_user.userName}.

Da mesma forma, 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, por questões de 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 gráfico a seguir quando você executar o comando bundle validate --output json (as reticências indicam o conteúdo omitido, para abreviar):

{
  "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",
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

O senhor 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 do valor do destino de my_pipeline.

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

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}