通过设置API管理设置

设置API允许您通过程序读取和更新Azure Databricks账户、工作区和用户设置，包括账户和工作区级的功能预览。本页介绍如何发现可用设置以及如何读取和更新设置。关于通过公共API提供的设置列表，请参见设置API键参考。

有关完整端点参考信息，请参见设置 REST API。

注释

工作区级和账户级的功能预览也通过 Settings v2 API 进行管理，但它们没有列在 Settings API 键参考文档中，因为当功能正式发布或被移除时，预览最终都会终止生命周期。通过 settings-metadata endpoint 了解当前可供您使用的预览版本。它返回的每个预览都可通过与其他任何设置相同的 get 和 update（PATCH）端点进行读取和更新。

设置 API 模型

设置v2的API是动态的。一个统一的通用 API 服务于所有设置，且无需更新 API 版本、SDK 发布或文档更新，即可通过它获得新设置。与其依赖固定的、手动维护的端点列表，不如通过 metadata 端点在运行时发现当前可设置的内容。

一个设置包含名称、一个其形式取决于该设置类型的值，以及决定其适用范围的作用域：

账户设置 会在整个账户中应用。
工作区设置 适用于单个工作区。
用户偏好 适用于账户中的用户。

有些设置可以在多个瞄准镜上使用。账户和工作区设置通常需要管理员权限才能读取或更新。

按范围划分的端点

每个范围都有自己的端点集合。使用与设置管理方式相匹配的选项：

Scope	Get	更新（`PATCH`）
帐户	`/api/2.1/accounts/<account-id>/settings/<key-name>`	`/api/2.1/accounts/<account-id>/settings/<key-name>`
Workspace	`/api/2.1/settings/<key-name>`	`/api/2.1/settings/<key-name>`
用户偏好	`/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>`	`/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>`

发现可用设置

设置名称及其当前元数据（包括你需要更新的值类型）都可以从元数据端点获取。这是关于你的工作区或账户中当前可设置内容的始终最新的权威信息来源。该端点支持分页，因此请逐页获取结果，以检索完整列表：

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

你也可以用 Databricks 的 CLI 列出设置：

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

对于账户设置，请改用账户级元数据端点：

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

读取设置

get响应会为每个设置返回两个值。 存储值位于类型字段（例如，boolean_val），是已被设置的值。 有效值位于对应effective_*字段（例如，effective_boolean_val），是服务器在应用默认值和更高范围覆盖后计算出的值。例如，布尔值设置返回如下内容：

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

要读取工作区设置，请调用带有设置键名的获取端点：

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

要读取账户设置，请使用账户范围路径：

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

要读取用户偏好，可以使用账户范围的用户路径。读取和更新用户偏好设置需要账户管理员权限：

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

更新设定

要更新设置，发送 PATCH 一个请求，其主体为设置对象，字段中携带的值与设置类型相匹配。使用 list-workspace-settings-metadata （或元数据端点）来确定给定环境下的正确类型字段。例如，要更新布尔工作区设置：

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 }
  }'

要更新账户设置，请将相同的请求体发送到账户作用域路径：

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 }
  }'

要更新用户偏好设置，将请求发送到账户范围的用户路径。下面的示例更新了字符串类型的偏好：

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>" }
  }'

其他资源

Last updated on 2026-08-26