Comparteix via

Sustituciones y variables en Agrupaciones de recursos de Databricks

Agrupaciones de recursos de Databricks admite sustituciones y variables personalizadas, lo que hace que los archivos de configuración de agrupación sean más modulares y reutilizables. Tanto las sustituciones como las variables personalizadas permiten la recuperación dinámica de valores, de modo que la configuración se pueda determinar en el momento en que se implementa y se ejecuta una agrupación.

Sugerencia

También puede usar referencias de valor dinámico para los valores de parámetros de trabajo para pasar contexto sobre una ejecución de trabajo a tareas de trabajo. Consulte ¿Qué es una referencia de valores dinámicos? y Parametrización de trabajos.

Sustituciones

Puede usar sustituciones para recuperar valores de configuración que pueden cambiar en función del contexto de la implementación y ejecución de la agrupación. Por ejemplo, las subsituciones se pueden usar para hacer referencia a los valores de los campos de agrupación, agrupación nametargety área de trabajo userName para construir el área de trabajo root_path en el archivo de configuración de agrupación:

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Si someone@example.com se implementa esta agrupación, se implementaría en la ruta de acceso /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/devraíz .

También puede crear sustituciones para los recursos nombrados. Por ejemplo, para la siguiente definición de canalización, puede usar ${resources.pipelines.my_pipeline.target} para el valor del destino de la canalización:

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

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

Para determinar las sustituciones válidas, use la referencia de configuración de agrupación, la referencia de configuración de recursos o la jerarquía de esquemas de los objetos correspondientes documentados en la referencia de la API REST o la salida del bundle schema comando.

Sugerencia

Para obtener una lista completa de las sustituciones disponibles para los recursos, consulte Repositorio de GitHub de la CLI de Databricks out.fields.txt

Estas son algunas sustituciones usadas habitualmente:

  • ${bundle.name}
  • ${bundle.target} # Use this substitution instead of ${bundle.environment}
  • ${workspace.host}
  • ${workspace.current_user.domain_friendly_name}
  • ${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}

Variables personalizadas

Puede definir variables personalizadas simples y complejas en la agrupación a fin de habilitar la recuperación dinámica de valores necesarios para muchos escenarios. Las variables personalizadas se declaran en los archivos de configuración de paquetes dentro del mapeo de variables o en un archivo de variable-overrides.json. Para obtener información sobre lavariablesasignación, consulte variables.

La siguiente configuración de ejemplo define las variables my_cluster_id y 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

Si no proporciona un default valor para una variable como parte de esta declaración, debe establecerlo al ejecutar comandos de agrupación, a través de una variable de entorno, en otro lugar dentro de los archivos de configuración de lote o en el .databricks/bundle/<target>/variable-overrides.json archivo del proyecto de agrupación. Consulte Establecer el valor de una variable.

Hacer referencia a una variable

Para hacer referencia a una variable personalizada dentro de la configuración de agrupación, use la variable sustitución${var.<variable_name>}. Por ejemplo, la siguiente configuración hace referencia a las variables my_cluster_id y 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}

Establecer el valor de una variable

Si no ha establecido un default valor para una variable o si desea invalidar temporalmente el default valor de una variable, proporcione el nuevo valor temporal de la variable mediante uno de los métodos siguientes.

Nota:

Las variables de paquete son variables en el tiempo de implementación. Se interpretan cuando despliegas el paquete. Por ejemplo, al ejecutar un trabajo, ejecuta un trabajo implementado previamente y las variables configuradas para esa implementación, por lo que no se aplicarán valores diferentes para la ejecución del trabajo. En su lugar, pase valores a la ejecución de un trabajo usando parámetros de trabajo. Consulte Pasar parámetros de trabajo.

  • Proporcione el valor de la variable como parte de un bundle comando como validate, deployo run. Para ello, use la opción --var="<key>=<value>", donde <key> es el nombre de la variable y <value> es el valor de la variable. Por ejemplo, como parte del comando bundle validate, para proporcionar el valor de 1234-567890-abcde123 a la variable denominada my_cluster_id y el valor de ./hello.py a la variable denominada my_notebook_path, ejecute:

    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"

  • Proporcione el valor de la variable estableciendo una variable de entorno. El nombre de la variable de entorno debe comenzar con BUNDLE_VAR_. Para establecer variables de entorno, consulte la documentación del sistema operativo. Por ejemplo, para proporcionar el valor de 1234-567890-abcde123 a la variable denominada my_cluster_id y el valor de ./hello.py a la variable denominada my_notebook_path, ejecute el siguiente comando antes de llamar a un comando bundle como validate, deploy o run:

    Para Linux y 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"

    O bien, proporcione el valor de la variable como parte de un bundle comando como validate, deployo run, por ejemplo para Linux y macOS:

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

    O para Windows:

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

  • Incluya el valor de la variable dentro de los archivos de configuración del paquete mediante el mapeo variables dentro del mapeo targets, siguiendo este formato:

    variables:
  <variable-name>: <value>

    Por ejemplo, para establecer valores para las variables denominadas my_cluster_id y my_notebook_path para dos destinos independientes:

    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

  • Proporcione el valor de la variable en el .databricks/bundle/<target>/variable-overrides.json archivo con el siguiente formato:

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

    Por ejemplo, para proporcionar valores para las variables denominadas my_cluster_id y my_notebook_path para el destino de desarrollo, cree un archivo .databricks/bundle/dev/variable-overrides.json y establezca su contenido en:

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

    También puede definir variables complejas en el archivo variable-overrides.json.

Nota:

Independientemente del enfoque que elija para proporcionar valores de variable, debe proporcionar los mismos valores durante las fases de implementación y ejecución. De lo contrario, puede obtener resultados inesperados entre el momento de una implementación y una ejecución de trabajo o canalización que se basa en esa implementación existente.

Orden de precedencia

La CLI de Databricks busca valores para las variables en el orden siguiente, deteniendo cuando encuentra un valor para una variable:

  1. Dentro de cualquier --var opciones especificadas como parte del comando bundle.
  2. Dentro de cualquier conjunto de variables de entorno que comiencen por BUNDLE_VAR_.
  3. En el archivo variables-overrides.json, si existe.
  4. Dentro de las asignaciones de variables, entre las asignaciones de targets dentro de los archivos de configuración de agrupación.
  5. Cualquier default valor de la definición de esa variable, entre las asignaciones superiores de nivel variables dentro de los archivos de configuración de su paquete.

Definición de una variable compleja

Se supone que una variable personalizada es de tipo cadena a menos que la defina como una variable compleja. Para definir una variable personalizada con un tipo complejo para el paquete en su configuración del paquete, establezca type a complex.

Nota:

El único valor válido para la configuración type es complex. Además, la validación de la agrupación no se produce si type se establece en complex y si el valor default definido para la variable es un valor único.

En el ejemplo siguiente, la configuración del clúster se define en una variable compleja personalizada denominada 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

También puede definir una variable compleja en el archivo .databricks/bundle/<target>/variable-overrides.json, como se muestra en el ejemplo siguiente:

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

Recuperar el valor de identificador de un objeto

Para los tipos de objeto alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal, y warehouse, puede definir un lookup para su variable personalizada para recuperar el identificador de un objeto con nombre mediante este formato:

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

Si se define una búsqueda para una variable, el id. del objeto con el nombre especificado se usa como valor de la variable. Esto garantiza que el id. resuelto correcto del objeto siempre se use para la variable.

Nota:

Se produce un error si no existe un objeto con el nombre especificado o si hay más de un objeto con el nombre especificado.

Por ejemplo, en la siguiente configuración, ${var.my_cluster_id} se reemplazará por el identificador del clúster compartido de 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}

Sustitución de salida y valores de variable

Para asegurarse de que las sustituciones y las variables se especifican y analizan correctamente mediante Databricks Asset Bundles, ejecute databricks bundle validate. Consulte validación de conjuntos de databricks. Para ver los valores que se usarán al implementar una agrupación, use la --output json opción :

databricks bundle validate --output json

Por ejemplo, para una agrupación con la variable my_cluster_id definida y usada en una tarea de trabajo:

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

La salida del databricks bundle validate esquema sería la siguiente:

{
  "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"
    }
  },
"..."
}
  • Last updated on