Menggunakan API dasbor untuk membuat dan mengelola dasbor

Databricks REST API mencakup alat manajemen khusus untuk mengelola dasbor AI/BI. Halaman ini menunjukkan cara menggunakan alat API untuk membuat dan mengelola dasbor. Untuk melakukan tugas-tugas ini menggunakan UI, lihat Dasbor pembuat.

Nota

Dasbor AI/BI sebelumnya dikenal sebagai dasbor Lakeview. API Lakeview masih mempertahankan nama tersebut.

Prasyarat

Siapkan autentikasi untuk mengakses sumber daya Azure Databricks. Untuk mempelajari tentang opsi autentikasi dan mendapatkan instruksi penyiapan, lihat Otorisasi akses ke sumber daya Azure Databricks.
Anda memerlukan URL ruang kerja yang ingin Anda akses. Lihat nama instans Ruang Kerja, URL, dan ID.
Pemahaman tentang referensi Databricks REST API.

Mendapatkan dasbor draf

Anda dapat menggunakan dashboard_id untuk menarik detail papan kontrol dari papan kontrol draf. Contoh permintaan dan respons berikut menyertakan detail untuk versi dasbor draf saat ini di ruang kerja.

Bidang etag memantau versi terbaru papan laporan. Anda dapat menggunakan ini untuk memverifikasi versi sebelum membuat pembaruan tambahan.

GET /api/2.0/lakeview/dashboards/04aab30f99ea444490c10c85852f216c

Response:

{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report",
  "path": "/path/to/dir/Monthly Traffic Report.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "47bb1c472649e711",
  "etag": "80611980",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Memperbarui dasbor

Anda dapat menggunakan dashboard_id di respons sebelumnya untuk memperbarui dasbor AI/BI baru yang dibuat dengan operasi tersebut. Contoh berikut menunjukkan contoh permintaan dan respons. dashboard_id dari contoh sebelumnya disertakan sebagai parameter jalur.

display_name dan warehouse_id telah diubah. Dasbor yang diperbarui memiliki nama baru dan gudang default yang ditetapkan, seperti yang ditunjukkan dalam respons. Bidang etag bersifat opsional. Jika versi yang ditentukan dalam etag tidak cocok dengan versi saat ini, pembaruan ditolak.

PATCH /api/2.0/lakeview/dashboards/04aab30f99ea444490c10c85852f216c

Request body:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "c03a4f8a7162bc9f",
  "etag": "80611980"
}

Response:

{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report 2",
  "path": "/path/to/dir/Monthly Traffic Report 2.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "c03a4f8a7162bc9f",
  "etag": "80611981",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Membuat dasbor

Anda dapat menggunakan Create dashboard endpoint di Lakeview API untuk memindahkan dasbor Anda antara ruang kerja. Contoh berikut mencakup isi permintaan sampel dan respons yang membuat dasbor baru. Kunci serialized_dashboard dari contoh sebelumnya berisi semua detail yang diperlukan untuk membuat dasbor draf duplikat.

Contoh ini mencakup nilai warehouse_id baru yang berkaitan dengan sebuah gudang di ruang kerja yang baru. Lihat POST /api/2.0/lakeview/dashboards.

POST /api/2.0/lakeview/dashboards

Request body:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "parent_path": "/path/to/dir"
}

Response:

{
  "dashboard_id": "1e23fd84b6ac7894e2b053907dca9b2f",
  "display_name": "Monthly Traffic Report 2",
  "path": "/path/to/dir/Monthly Traffic Report 2.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "5e2f98ab3476cfd0",
  "etag": "14350695",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Satu-satunya properti yang diperlukan dalam isi permintaan adalah display_name. Alat ini dapat menyalin konten dasbor atau membuat dasbor kosong baru.

Menerbitkan dasbor

Anda dapat menggunakan endpoint Publikasi untuk menerbitkan dasbor, mengatur kredensial bagi pemirsa, dan menggantikan warehouse_id yang diatur di dasbor draf. Anda harus menyertakan UUID dasbor sebagai parameter jalur.

Isi permintaan menetapkan properti embed_credentials menjadi false. Secara default, embed_credentials diatur ke true. Menyematkan kredensial memungkinkan pengguna tingkat akun untuk melihat data dasbor. Lihat Menerbitkan dasbor. Nilai warehouse_id baru dihilangkan, sehingga dasbor yang diterbitkan menggunakan gudang yang sama yang ditetapkan ke dasbor draf.

POST /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Request body:

{
  "embed_credentials": false
}

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": false,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Publikasikan dasbor dengan kredensial prinsipal layanan

Anda dapat menerbitkan dasbor dengan kredensial perwakilan layanan yang disematkan dengan mengautentikasi sebagai perwakilan layanan saat melakukan panggilan API. Saat Anda menerbitkan menggunakan token perwakilan layanan, dasbor diterbitkan dengan data perwakilan layanan tersebut dan izin komputasi, memungkinkan pengguna tanpa akses data langsung untuk melihat dasbor.

Sebelum menerbitkan, perwakilan layanan harus memiliki setidaknya izin CAN MANAGE di dasbor, SELECT hak istimewa pada semua sumber data yang digunakan di dasbor, dan izin CAN USE pada gudang. Untuk detail tentang membuat perwakilan layanan dan menghasilkan kunci rahasia OAuth, lihat Perwakilan Layanan dan Otorisasi akses perwakilan layanan ke Azure Databricks dengan OAuth.

Pertama, autentikasi sebagai perwakilan layanan untuk mendapatkan token akses:

POST https://<databricks-instance>/oidc/v1/token

Request body (form-urlencoded):

grant_type=client_credentials&scope=all-apis

Authorization header:

Basic <base64-encoded-client-id:client-secret>

Response:

{
  "access_token": "eyJraWQiOiJkYTA4ZTVjZ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Kemudian, gunakan token akses untuk menerbitkan dasbor dengan kredensial perwakilan layanan:

POST /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Authorization header:

Bearer <service-principal-access-token>

Request body:

{
  "embed_credentials": true,
  "warehouse_id": "5e2f98ab3476cfd0"
}

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": true,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Ketika embed_credentials diatur ke true, pengguna dasbor menggunakan izin principal layanan untuk mengakses data dan sumber daya komputasi. Pengguna hanya memerlukan izin untuk mengakses objek dasbor itu sendiri. Semua kueri dasbor berjalan menggunakan identitas perwakilan layanan, sehingga log audit menunjukkan perwakilan layanan sebagai pelaksana kueri.

Akses dasbor yang diterbitkan

Respons dari GET /api/2.0/lakeview/dashboards/{dashboard_id}/ yang diterbitkan mirip dengan respons yang disediakan dalam contoh sebelumnya. dashboard_id disertakan sebagai parameter jalur.

GET /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": false,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Membatalkan penerbitan dasbor

Dasbor draf dipertahankan saat Anda menggunakan API Lakeview untuk membatalkan penerbitan dasbor. Permintaan ini menghapus versi dasbor yang diterbitkan.

Contoh berikut menggunakan dashboard_id dari contoh sebelumnya. Permintaan yang berhasil menghasilkan kode status 200. Tidak ada isi respons.

DELETE /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Dasbor sampah

Gunakan DELETE /api/2.0/lakeview/dashboards/{dashboard_id} untuk mengirim dasbor draf ke tempat sampah. Dasbor masih dapat dipulihkan.