設定APIを通じて設定を管理

設定APIでは、Azure Databricksのアカウント、ワークスペース、ユーザー設定、アカウントやワークスペースレベルの機能プレビューをプログラム的に読み書き更新できます。 このページでは、利用可能な設定の発見方法や、それらの読み方や更新方法を説明しています。 公開APIで利用可能な設定一覧については、 Settings API keys referenceを参照してください。

エンドポイントの完全な参照については、 設定REST APIをご覧ください。

設定APIモデル

設定v2のAPIは動的です。 すべての環境に対応した単一の汎用APIが用意されており、新しいAPIバージョンやSDKリリース、ドキュメント更新なしで新しい設定が利用可能になります。 固定された手作業で管理されるエンドポイントのリストではなく、 メタデータのエンドポイントを通じて実行時に設定可能なものを発見します。

設定には名前、その設定の型に依存する形状の値、そして適用場所を決定するスコープがあります:

• アカウント設定 はアカウント全体に適用されます。
• ワークスペースの設定 は単一のワークスペースに適用されます。
• ユーザー設定 はアカウント内のユーザーに適用されます。

一部の設定は複数のスコープで利用可能です。 アカウントやワークスペースの設定は、一般的に管理者の権限で読みや更新が必要です。

スコープ別エンドポイント

各スコープには独自のエンドポイントセットがあります。 設定の管理方法に合ったものを使いましょう:

利用可能な設定を発見

設定名とその現在のメタデータ(更新に必要な値タイプを含む)はメタデータエンドポイントから取得できます。 これは、ワークスペースまたはアカウントで現在設定可能な項目についての、常に最新の信頼できる情報源です。 エンドポイントはページ付きなので、結果をページめくって全リストを取得できます:

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レスポンスは各設定ごとに2つの値を返します。 保存値は型フィールド(例えばboolean_val)にあり、設定された値です。 実効値は対応するeffective_*フィールド(例えばeffective_boolean_val)にあり、デフォルト設定やより大きな範囲のオーバーライドを適用した後にサーバーが計算する値です。 例えば、ブール値の設定では、次のような値が返されます:

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

ワークスペース設定を読み取るには、getエンドポイントを設定のキーネームで呼び出します:

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

その他のリソース

• 設定のAPIキー リファレンス
• 設定REST API
• workspace-settings-v2 コマンド グループ
• account settings コマンド グループ
• settings コマンド グループ
• ワークスペースを管理する
• アカウントの管理