Substituições e variáveis em pacotes de ativos do Databricks

Artigo
12/06/2024

Os Pacotes de Ativos do Databricks dão suporte a substituições e variáveis personalizadas, o que torna os arquivos de configuração do pacote 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 configurável é implantado e executado.

Dica

Você também pode usar referências de valor dinâmico para valores de parâmetro de trabalho para passar contexto sobre uma execução de trabalho para tarefas de trabalho. Confira O que é uma referência de valor dinâmico? e Parametrizar trabalhos.

Substituições

Você pode usar substituições para recuperar valores de configurações que mudam com base no contexto da implementação e execução do pacote.

Por exemplo, ao executar o comando bundle validate --output json, você pode ver um gráfico como este:

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

As substituições podem ser usadas para se referir aos valores dos campos pacote name, pacote targete espaço de trabalho userName para construir a área de trabalho root_path no arquivo de configuração do pacote:

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

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

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

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

${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 habilitar a recuperação dinâmica de valores necessários para muitos cenários. Variáveis personalizadas são declaradas em seus arquivos de configuração de pacote dentro do mapeamento de variables. Confira variáveis.

A configuração de exemplo 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 comandos de pacote, por meio de uma variável de ambiente ou em outro lugar dentro de seus arquivos de configuração de pacote, conforme descrito em Definir o valor de uma variável.

Para referenciar uma variável personalizada dentro da configuração do seu 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 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>", sendo <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 1234-567890-abcde123 à variável nomeada my_cluster_ide para fornecer o valor ./hello.py à variável nomeada 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 precisa começar com BUNDLE_VAR_. Para definir variáveis de ambiente, confira a documentação do sistema operacional. Por exemplo, para fornecer o valor 1234-567890-abcde123 à variável nomeada my_cluster_id e para fornecer o valor ./hello.py à variável nomeada my_notebook_path, execute o seguinte comando antes de chamar um comando bundle como validate, deploy ou run:

No 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, então, 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 o 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 às variáveis nomeadas my_cluster_id e my_notebook_path a 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 as fases de implantação e execução. Caso contrário, você poderá obter resultados inesperados entre o momento de uma implantação e uma execução de trabalho ou pipeline baseada 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, interrompendo a pesquisa quando encontra um valor para cada variável correspondente, ignorando qualquer outro local dessa variável:

Em todas as opções --var especificadas como parte do comando bundle.
Em qualquer conjunto de variáveis de ambiente que comece com BUNDLE_VAR_.
Em qualquer mapeamento variables, entre os mapeamentos targets nos arquivos de configuração do pacote.
Qualquer valor default para a definição dessa variável, entre os mapeamentos variables de nível superior em seus arquivos de configuração do pacote.

Definir uma variável complexa

Uma variável personalizada é considerada do tipo string, a menos que você a defina como uma variável complexa. Para definir uma variável personalizada com um tipo complexo para o pacote, defina type como complex na configuração do pacote.

Observação

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

No exemplo a seguir, as configurações de 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 da ID de um objeto

Para os tipos de objeto alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principale warehouse, você pode definir um lookup para a variável personalizada recuperar a ID de um objeto nomeado 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á utilizada como o valor da variável. Isso garante que a ID resolvida corretamente 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 pela ID do cluster 12.2 compartilhado.

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}

Compartilhar via

Substituições e variáveis em pacotes de ativos do Databricks

Substituições

Variáveis personalizadas

Definir o valor de uma variável

Definir uma variável complexa

Recuperar o valor da ID de um objeto

Comentários

Recursos adicionais