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 mudam com base no contexto da implantação e execução do pacote.
Por exemplo, ao executar o comando bundle validate --output json
, o senhor poderá ver um gráfico como este:
{
"bundle": {
"name": "hello-bundle",
"target": "dev",
"...": "..."
},
"workspace": {
"...": "...",
"current_user": {
"...": "...",
"userName": "someone@example.com",
"...": "...",
},
"...": "..."
},
"...": {
"...": "..."
}
}
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:
bundle:
name: hello-bundle
workspace:
root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}
# ...
targets:
dev:
default: true
Também é possível 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 substituições válidas, você pode usar a hierarquia do esquema documentada na referência da API REST ou na 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
. Veja as variáveis.
O exemplo de configuração a seguir define as variáveis my_cluster_id
e my_notebook_path
:
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 dessa declaração, deverá defini-la ao executar os comandos do pacote, por meio de uma variável de ambiente ou em outro local dos arquivos de configuração do pacote, conforme descrito em Definir o valor de 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, para referenciar as variáveis 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 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
, comovalidate
,deploy
ourun
. Para fazer isso, utilize 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 comandobundle validate
, para fornecer o valor de1234-567890-abcde123
para a variável denominadamy_cluster_id
e para fornecer o valor de./hello.py
para a variável denominadamy_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 sistema operacional. Por exemplo, para fornecer o valor de1234-567890-abcde123
para a variável denominadamy_cluster_id
e para fornecer o valor de./hello.py
para a variável denominadamy_notebook_path
, execute o seguinte comando antes de chamar um comandobundle
, comovalidate
,deploy
ourun
:No Linux e macOS:
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
No 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
, comovalidate
,deploy
ourun
, 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 isso, utilize um mapeamento de
variables
dentro do mapeamento detargets
, seguindo este formato:variables: <variable-name>: <value>
Por exemplo, para fornecer valores para as variáveis denominadas
my_cluster_id
emy_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
Observação
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.
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:
Dentro de quaisquer opções
--var
especificadas como parte do comandobundle
.Dentro de qualquer conjunto de variáveis de ambiente que comece com
BUNDLE_VAR_
.Em qualquer mapeamento de
variables
, entre os mapeamentos detargets
em seus arquivos de configuração de pacote.Qualquer valor
default
para a definição dessa variável, entre os mapeamentos devariables
de nível superior em seus arquivos de configuração de pacote.
Defina 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, defina type
como complex
na configuração do pacote.
Observação
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
:
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 tipos de objetos alert
, cluster_policy
, cluster
, dashboard
, instance_pool
, job
, metastore
, pipeline
, query
, service_principal
e warehouse
, você pode definir um lookup
para sua variável personalizada para recuperar um objeto nomeado do ID usando este 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 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}