Gestionar la configuración a través de la API de Configuración

La API de Configuración te permite leer y actualizar la cuenta, el espacio de trabajo y la configuración de usuario de Azure Databricks, incluyendo previsualizaciones de cuentas y funciones a nivel de espacio de trabajo, de forma programática. Esta página explica cómo descubrir los ajustes disponibles y cómo leerlos y actualizarlos. Para la lista de configuraciones disponibles a través de la API pública, consulte la referencia de claves de la API de Configuración.

Para la referencia completa del endpoint, consulta la API REST de Configuración.

Nota

Las vistas previas de funciones a nivel de espacio de trabajo y a nivel de cuenta también se gestionan a través de la API de Configuración v2, pero no aparecen en la referencia de claves de la API de Configuración porque una vista previa llega finalmente al final de su vida útil cuando la función se gradúa o se elimina. Descubre las versiones preliminares a las que tienes acceso actualmente a través del endpoint settings-metadata. Cada vista previa que devuelve puede leerse y actualizarse a través de los mismos endpoints de get y update (PATCH) que cualquier otra configuración.

Configuración modelo de API

La API de Configuración v2 es dinámica. Una API única y generalizada sirve a todos los ajustes, y nuevas configuraciones se disponen a través de ella sin una nueva versión de la API, una versión del SDK o una actualización de documentación. En lugar de una lista fija de puntos de conexión mantenida manualmente, puedes descubrir qué se puede configurar actualmente en tiempo de ejecución a través del metadata endpoint.

Un escenario tiene un nombre, un valor cuya forma depende del tipo de configuración y un ámbito que determina dónde se aplica:

  • La configuración de la cuenta se aplica a toda la cuenta.
  • La configuración del espacio de trabajo se aplica a un único espacio de trabajo.
  • Las preferencias del usuario se aplican a un usuario dentro de una cuenta.

Algunos ajustes están disponibles en más de un telescopio. La configuración de cuentas y espacios de trabajo generalmente requiere permisos de administrador para leer o actualizar.

Puntos de conexión según el alcance

Cada ámbito tiene su propio conjunto de extremos. Usa la que se ajuste a cómo se gestiona el escenario:

Ámbito Get Actualización (PATCH)
Cuenta /api/2.1/accounts/<account-id>/settings/<key-name> /api/2.1/accounts/<account-id>/settings/<key-name>
Área de trabajo /api/2.1/settings/<key-name> /api/2.1/settings/<key-name>
Preferencia del usuario /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name> /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>

Descubre los ajustes disponibles

Los nombres de configuración y sus metadatos actuales (incluido el tipo de valor que necesitas para las actualizaciones) están disponibles desde el endpoint de metadatos. Esta es la fuente de referencia siempre actualizada de lo que actualmente puede configurarse en tu espacio de trabajo o cuenta. El punto final está paginado, así que hojea los resultados para obtener la lista completa:

curl -n --request GET \
  'https://<databricks-instance>/api/2.1/settings-metadata'

También puedes enumerar la configuración con la CLI de Databricks:

databricks workspace-settings-v2 list-workspace-settings-metadata

Para la configuración de la cuenta, utiliza en su lugar el endpoint de metadatos específico de la cuenta:

curl -n --request GET \
  'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings-metadata'

Leer una configuración

Una respuesta get devuelve dos valores para cada configuración. El valor almacenado está en el campo tipo (por ejemplo, boolean_val) y es el valor que se ha establecido. El valor efectivo está en el campo correspondiente effective_* (por ejemplo, effective_boolean_val) y es el valor que el servidor calcula tras aplicar valores por defecto y cualquier sobreescritura de mayor alcance. Por ejemplo, un ajuste booleano devuelve:

{
  "name": "<key-name>",
  "boolean_val": { "value": true },
  "effective_boolean_val": { "value": true }
}

Para leer una configuración del espacio de trabajo, llame al endpoint `get` con la clave de la configuración:

curl -n --request GET \
  'https://<databricks-instance>/api/2.1/settings/<key-name>'

Para leer una configuración de la cuenta, utiliza la ruta con ámbito de cuenta:

curl -n --request GET \
  'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings/<key-name>'

Para leer una preferencia de usuario, utiliza la ruta de usuario de ámbito de cuenta. Leer y actualizar las preferencias de usuario requiere permisos de administrador de cuenta:

curl -n --request GET \
  'https://<databricks-instance>/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>'

Actualizar un ajuste

Para actualizar un ajuste, envía una solicitud PATCH cuyo cuerpo sea el objeto de ajuste, con el valor incluido en el campo que coincida con el tipo del ajuste. Usa list-workspace-settings-metadata (o el endpoint de metadatos) para determinar el campo de tipo correcto para una configuración dada. Por ejemplo, para actualizar una configuración de espacio de trabajo booleano:

curl -n --request PATCH \
  'https://<databricks-instance>/api/2.1/settings/<key-name>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<key-name>",
    "boolean_val": { "value": true }
  }'

Para actualizar una configuración de la cuenta, envía el mismo cuerpo de la solicitud a la ruta del ámbito de la cuenta:

curl -n --request PATCH \
  'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings/<key-name>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<key-name>",
    "boolean_val": { "value": true }
  }'

Para actualizar una preferencia de usuario, envía la solicitud a la ruta de usuario del ámbito de la cuenta. El siguiente ejemplo actualiza una preferencia de tipo de cadena:

curl -n --request PATCH \
  'https://<databricks-instance>/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<key-name>",
    "string_val": { "value": "<value>" }
  }'

Recursos adicionales

  • Se actualizó por última vez el