通过设置API管理设置

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

完整端点参考,请参见 设置 REST API。

注释

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

设置 API 模型

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

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

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

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

按范围划分的端点

每个范围都有自己的端点集合。 选择与该设置的管理方式相匹配的那个:

Scope Get 更新(PATCH)
帐户 /api/2.1/accounts/<account-id>/settings/<key-name> /api/2.1/accounts/<account-id>/settings/<key-name>
工作空间 /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>" }
  }'

其他资源