設定APIを使用して設定を管理する
Settings APIを使用すると、アカウントレベルおよびワークスペースレベルの機能プレビューを含む、Databricksのアカウント、ワークスペース、およびユーザーの設定をプログラムで読み取り、更新できます。このページでは、利用可能な設定を見つける方法と、それらを読み取りおよび更新する方法について説明します。パブリックAPIを通じて利用可能な設定のリストについては、 「Settings APIキーリファレンス」を参照してください。
完全な Endpoint リファレンスについては、Settings REST API を参照してください。
ワークスペースおよびアカウントレベルの機能プレビューも Settings v2 API を通じて管理されますが、機能が正式リリースされるか削除されるとプレビューは最終的に終了するため、Settings API キーリファレンスには記載されていません。settings-metadata Endpointを通じて、現在利用可能なプレビューを確認してください。それが返す各プレビューは、他の設定と同様に、同じ取得および更新 (PATCH) Endpointを通じて読み取りおよび更新が可能です。
設定 API モデル
Settings v2 API は動的です。単一の汎用 API ですべての設定が提供されるため、新しい API バージョン、SDK リリース、またはドキュメントの更新なしで、新しい設定が利用可能になります。固定された手動管理のEndpointリストではなく、メタデータEndpointを通じて、ランタイム時に現在設定可能な項目を確認できます。
設定には名前、設定のタイプによって形状が異なる値、および適用範囲を決定するスコープがあります：
- アカウント設定 は、アカウント全体に適用されます。
- ワークスペース設定 は、単一のワークスペースに適用されます。
- ユーザー設定 は、アカウント内のユーザーに適用されます。
一部の設定は、複数のスコープで利用可能です。アカウントおよびワークスペースの設定は、一般的に読み取りや更新に管理者権限が必要です。
スコープ別のEndpoint
各スコープには、それぞれ独自のEndpointセットがあります。設定の管理方法に一致するものを使用してください：
スコープ | 取得 | 更新 ( |
|---|---|---|
アカウント | ||
ワークスペース | ||
ユーザー設定 |
|
|
利用可能な設定を検出する
設定名とその現在のメタデータ（更新に必要な値の型を含む）は、メタデータEndpointから入手できます。これは、ワークスペースまたはアカウントで現在設定可能な項目に関する、常に最新の信頼できるソースです。Endpointはページ分割されているため、結果をページ送りしてリスト全体を取得してください：
curl -n --request GET \
'https://<databricks-instance>/api/2.1/settings-metadata'
Databricks CLI を使用して設定を一覧表示することもできます：
databricks workspace-settings-v2 list-workspace-settings-metadata
アカウント設定については、代わりにアカウントスコープのメタデータ Endpoint を使用してください：
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings-metadata'
設定を読み取る
GET 応答は、各設定に対して 2 つの値を返します。 保存された値 はタイプフィールド（例：boolean_val）にあり、設定された値です。The effective value is in the corresponding effective_* field (for example, effective_boolean_val) and is the value the server computes after applying default and any higher-scope overrides. たとえば、boolean設定は以下を返します：
{
"name": "<key-name>",
"boolean_val": { "value": true },
"effective_boolean_val": { "value": true }
}
ワークスペースの設定を読み取るには、設定のキー名を使用して get Endpoint を呼び出します。
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（またはメタデータ Endpoint）を使用します。例えば、Boolean ワークスペース設定を更新するには、次のようにします。
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>" }
}'