Kelola pengaturan melalui API Pengaturan

API Pengaturan memungkinkan Anda membaca dan memperbarui pengaturan akun, ruang kerja, dan pengguna Azure Databricks, termasuk pratinjau fitur di tingkat akun dan ruang kerja, secara terprogram. Halaman ini menjelaskan cara menemukan pengaturan yang tersedia serta cara membaca dan memperbaruinya. Untuk daftar pengaturan yang tersedia melalui API publik, lihat referensi kunci API Pengaturan.

Untuk referensi endpoint lengkap, lihat Settings REST API.

Note

Pratinjau fitur tingkat workspace dan akun juga dikelola melalui API Settings v2, tetapi tidak tercantum dalam referensi tombol Settings API karena pratinjau akhirnya mencapai akhir masa pakai ketika fitur tersebut lulus atau dihapus. Temukan pratinjau yang saat ini tersedia bagi Anda melalui titik akhir settings-metadata. Setiap pratinjau yang dikembalikan dapat dibaca dan diperbarui melalui endpoint get dan update (PATCH) yang sama seperti pada pengaturan lainnya.

Model API Pengaturan

API Settings v2 bersifat dinamis. Satu API umum melayani setiap pengaturan, dan pengaturan baru tersedia melalui aplikasi tersebut tanpa versi API baru, rilis SDK, atau pembaruan dokumentasi. Alih-alih menggunakan daftar endpoint tetap yang dipelihara secara manual, Anda dapat mengetahui apa saja yang saat ini dapat diatur saat runtime melalui metadata endpoint.

Sebuah pengaturan memiliki nama, nilai yang bentuknya bergantung pada tipe pengaturan, dan cakupan yang menentukan di mana pengaturan tersebut berlaku:

  • Pengaturan akun berlaku di seluruh akun.
  • Pengaturan ruang kerja berlaku untuk satu ruang kerja.
  • Preferensi pengguna berlaku untuk pengguna dalam sebuah akun.

Beberapa pengaturan tersedia dalam lebih dari satu cakupan. Pengaturan akun dan workspace umumnya memerlukan izin administrator untuk membaca atau memperbarui.

Titik akhir berdasarkan cakupan

Setiap cakupan memiliki sekumpulan endpoint tersendiri. Gunakan yang sesuai dengan cara pengaturan tersebut dikelola:

Cakupan Get Pembaruan (PATCH)
Akun /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>
Preferensi pengguna /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name> /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>

Temukan pengaturan yang tersedia

Nama pengaturan dan metadata saat ini (termasuk tipe nilai yang Anda butuhkan untuk pembaruan) tersedia dari endpoint metadata. Ini adalah sumber acuan utama yang selalu diperbarui tentang apa saja yang saat ini dapat diatur di ruang kerja atau akun Anda. Endpoint ini dipaginasi, jadi telusuri hasilnya per halaman untuk mendapatkan daftar lengkap:

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

Anda juga dapat mencantumkan pengaturan dengan Databricks CLI:

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

Untuk pengaturan akun, gunakan endpoint metadata yang dijangkau akun sebagai gantinya:

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

Baca sebuah pengaturan

Respons get mengembalikan dua nilai untuk setiap pengaturan. Nilai yang disimpan berada di bidang tipe (misalnya, boolean_val) dan adalah nilai yang telah diatur. Nilai efektif berada di bidang yang sesuai effective_* (misalnya, effective_boolean_val) dan adalah nilai yang dihitung server setelah menerapkan default dan override dengan cakupan lebih tinggi. Misalnya, pengaturan boolean mengembalikan:

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

Untuk membaca pengaturan ruang kerja, panggil endpoint get dengan nama kunci pengaturan tersebut:

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

Untuk membaca pengaturan akun, gunakan jalur dengan cakupan akun:

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

Untuk membaca preferensi pengguna, gunakan jalur pengguna yang dibatasi akun. Membaca dan memperbarui preferensi pengguna memerlukan izin administrator akun:

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

Perbarui pengaturan

Untuk memperbarui pengaturan, kirim permintaan PATCH yang body-nya berupa objek pengaturan, dengan nilai ditempatkan dalam field yang sesuai dengan tipe pengaturan tersebut. Gunakan list-workspace-settings-metadata (atau titik akhir metadata) untuk menentukan bidang tipe yang benar untuk pengaturan tertentu. Misalnya, untuk memperbarui pengaturan ruang kerja 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 }
  }'

Untuk memperbarui pengaturan akun, kirim payload yang sama ke jalur khusus akun:

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

Untuk memperbarui preferensi pengguna, kirim permintaan ke path pengguna dalam cakupan akun. Contoh di bawah ini memperbarui preferensi bertipe string:

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

Sumber daya tambahan

  • Terakhir diperbarui pada