Pular para o conteúdo principal

Substituições e variáveis em Databricks ativo Bundles

Databricks O ativo Bundles suporta substituições e variáveis personalizadas, o que torna seus arquivos de configuração de pacotes mais modulares e reutilizáveis. Tanto as substituições quanto as variáveis personalizadas permitem a recuperação dinâmica de valores para que as configurações possam ser determinadas no momento em que um pacote é implantado e executado.

dica

O senhor também pode usar referências de valores dinâmicos para valores de parâmetros do Job para passar o contexto sobre a execução de um Job para a tarefa do Job. Consulte O que é uma referência de valor dinâmico? e Parameterize Job.

Substituições

O senhor pode usar substituições para recuperar valores de configurações que podem mudar com base no contexto da implantação e execução do pacote. Por exemplo, as subsituições podem ser usadas para fazer referência aos valores dos campos bundle name, bundle target e workspace userName para construir o workspace root_path no arquivo de configuração do bundle:

YAML
bundle:
name: hello-bundle

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

targets:
dev:
default: true

Se someone@example.com implantasse esse pacote, ele seria implantado no caminho raiz /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev.

O senhor também pode criar substituições para recursos nomeados. Por exemplo, na definição de pipeline a seguir, o senhor pode usar ${resources.pipelines.my_pipeline.target} para o valor do destino do pipeline:

YAML
resources:
pipelines:
my_pipeline:
name: my_pipeline
schema: pipeline_bundle_${bundle.target}
libraries:
- notebook:
path: ../src/dlt_pipeline.ipynb

configuration:
bundle.sourcePath: ${workspace.file_path}/src

Para determinar as substituições válidas, use a referência de configuração do pacote, a referência de configuração do recurso ou a hierarquia do esquema dos objetos correspondentes documentados 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}

Variáveis personalizadas

Você pode definir variáveis personalizadas simples e complexas em seu pacote para permitir a recuperação dinâmica dos valores necessários para muitos cenários. As variáveis personalizadas são declaradas nos arquivos de configuração do pacote no mapeamento variables ou em um arquivo variable-overrides.json. Para obter informações sobre o mapeamento variables, consulte variáveis.

O exemplo de configuração a seguir define as variáveis my_cluster_id e my_notebook_path:

YAML
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 o senhor não fornecer um valor default para uma variável como parte dessa declaração, deverá defini-la ao executar o comando do pacote, por meio de uma variável de ambiente, em outro local dos arquivos de configuração do pacote ou no arquivo .databricks/bundle/<target>/variable-overrides.json do projeto do pacote. Consulte Definir o valor de uma variável.

Referenciar uma variável

Para fazer referência a uma variável personalizada na configuração do pacote, use a substituição de variável ${var.<variable_name>}. Por exemplo, a configuração a seguir faz referência às variáveis my_cluster_id e my_notebook_path:

YAML
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 forneceu um valor default para uma variável, ou se quiser substituir temporariamente o valor default para 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 comando bundle, como validate, deploy, ou run. Para fazer isso, use a opção --var="<key>=<value>", em que <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 à variável denominada my_cluster_id, e para fornecer o valor de ./hello.py à variável denominada my_notebook_path, execute:

    Bash
    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 à variável denominada my_cluster_id e para fornecer o valor de ./hello.py à variável denominada my_notebook_path, execute o seguinte comando antes de chamar um comando bundle, como validate, deploy ou run:

    No Linux e macOS:

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

    No Windows:

    Bash
    "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:

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

    Ou para Windows:

    Bash
    "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 usando o mapeamento variables no mapeamento targets, seguindo este formato:

    YAML
    variables:
    <variable-name>: <value>

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

    YAML
    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
  • Forneça o valor da variável no arquivo .databricks/bundle/<target>/variable-overrides.json, usando o seguinte formato:

    JSON
    {
    "<variable-name>": "<variable-value>"
    }

    Por exemplo, para fornecer valores para as variáveis denominadas my_cluster_id e my_notebook_path para o destino dev, crie um arquivo .databricks/bundle/dev/variable-overrides.json e defina seu conteúdo como:

    JSON
    {
    "my_cluster_id": "1234-567890-abcde123",
    "my_notebook_path": "./hello.py"
    }

    Você também pode definir variáveis complexas no arquivo variable-overrides.json.

nota

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

Ordem de precedência

A CLI da Databricks procura valores para variáveis na seguinte ordem, parando quando encontra um valor para uma 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 do arquivo variables-overrides.json, se ele existir.
  4. Em qualquer mapeamento de variables, entre os mapeamentos de targets em seus arquivos de configuração de pacote.
  5. 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.

Definir uma variável complexa

Presume-se que uma variável personalizada seja do tipo string, a menos que o senhor a defina como uma variável complexa. Para definir uma variável personalizada com um tipo complexo para seu pacote na configuração do pacote, defina type como complex.

nota

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

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

YAML
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

Você também pode definir uma variável complexa no arquivo .databricks/bundle/<target>/variable-overrides.json, conforme mostrado no exemplo a seguir:

JSON
{
"my_cluster": {
"spark_version": "13.2.x-scala2.11",
"node_type_id": "Standard_DS3_v2",
"num_workers": 2
}
}

Recuperar o valor de ID de um objeto

Para os tipos de objetos alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal e warehouse, você pode definir um lookup para seu variável personalizada para recuperar o ID de um objeto nomeado usando este formato:

YAML
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

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 do cluster compartilhado 12.2 .

YAML
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ção de saída e valores variáveis

Para garantir que suas substituições e variáveis sejam corretamente especificadas e analisadas pelo Databricks ativo Bundles, execute databricks bundle validate. Consulte Validar um pacote. Para view valores que serão usados quando o senhor implantar um pacote, use a opção --output json:

Bash
databricks bundle validate --output json

Por exemplo, para um pacote com a variável my_cluster_id definida e usada em uma tarefa de trabalho:

YAML
bundle:
name: variables_bundle

variables:
my_cluster_id:
default: 1234-567890-abcde123

resources:
jobs:
variables_bundle_job:
name: variables_bundle_job
tasks:
- task_key: notebook_task
existing_cluster_id: ${var.my_cluster_id}
notebook_task:
notebook_path: ../src/notebook.ipynb

A saída do esquema databricks bundle validate seria a seguinte:

JSON
{
"bundle": {
"..."
"name": "variables_bundle",
"target": "dev",
"..."
},
"resources": {
"jobs": {
"variables_bundle_job": {
"deployment": {
"kind": "BUNDLE",
"metadata_file_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/state/metadata.json"
},
"max_concurrent_runs": 4,
"name": "[dev someone] variables_bundle_job",
"tasks": [
{
"existing_cluster_id": "1234-567890-abcde123",
"notebook_task": {
"notebook_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/files/variables_bundle/src/notebook"
},
"task_key": "notebook_task"
},
],
"..."
}
}
},
"..."
"variables": {
"my_cluster_id": {
"default": "1234-567890-abcde123",
"value": "1234-567890-abcde123"
}
},
"..."
}