Tutorial: Mengelola dasbor dengan API Ruang Kerja

  • Artikel

Tutorial ini menunjukkan cara mengelola dasbor menggunakan API Lakeview dan API Ruang Kerja. Setiap langkah mencakup sampel permintaan dan respons, dan penjelasan tentang cara menggunakan alat api dan properti bersama-sama. Setiap langkah dapat dirujuk sendiri. Mengikuti semua langkah dalam urutan memandu Anda melalui alur kerja lengkap.

Catatan

Alur kerja ini memanggil API Ruang Kerja untuk mengambil dasbor Lakeview sebagai objek ruang kerja generik.

Prasyarat

  • Anda memerlukan token akses pribadi untuk terhubung dengan ruang kerja Anda. Lihat Autentikasi token akses pribadi Azure Databricks.
  • Anda memerlukan ID ruang kerja ruang kerja yang ingin Anda akses. Lihat Nama, URL, dan ID instans ruang kerja
  • Keakraban dengan referensi Databricks REST API.

Langkah 1: Menjelajahi direktori ruang kerja

WORKspace List API GET /api/2.0/workspace/list memungkinkan Anda menjelajahi struktur direktori ruang kerja Anda. Misalnya, Anda dapat mengambil daftar semua file dan direktori di ruang kerja Anda saat ini.

Dalam contoh berikut, path properti dalam permintaan menunjuk ke folder bernama examples_folder yang disimpan di folder utama pengguna. Nama pengguna disediakan di jalur , first.last@example.com.

Respons menunjukkan bahwa folder berisi file teks, direktori, dan dasbor Lakeview.

GET /api/2.0/workspace/list

Query Parameters:
{
"path": "/Users/first.last@example.com/examples_folder"
}

Response:
{
  "objects": [
    {
      "object_type": "FILE",
      "path": "/Users/first.last@example.com/examples_folder/myfile.txt",
      "created_at": 1706822278103,
      "modified_at": 1706822278103,
      "object_id": 3976707922053539,
      "resource_id": "3976707922053539"
  },
  {
      "object_type": "DIRECTORY",
      "path": "/Users/first.last@example.com/examples_folder/another_folder",
      "object_id": 2514959868792596,
      "resource_id": "2514959868792596"
  },
  {
      "object_type": "DASHBOARD",
      "path": "/Users/first.last@example.com/examples_folder/mydashboard.lvdash.json",
      "object_id": 7944020886653361,
      "resource_id": "01eec14769f616949d7a44244a53ed10"
    }
  ]
}

Langkah 2: Mengekspor dasbor

Workspace Export API GET /api/2.0/workspace/export memungkinkan Anda mengekspor konten dasbor sebagai file. File dasbor Lakeview mencerminkan versi draf dasbor. Respons dalam contoh berikut menunjukkan konten definisi dasbor minimal. Untuk menjelajahi dan memahami lebih banyak detail serialisasi, coba ekspor beberapa dasbor Anda sendiri.

Mengunduh file yang diekspor

Contoh berikut menunjukkan cara mengunduh file dasbor menggunakan API.

Properti "path" dalam contoh ini berakhir dengan ekstensi lvdash.jsonjenis file , dasbor Lakeview. Nama file, seperti yang muncul di ruang kerja, mendahului ekstensi tersebut. Dalam hal ini, ini adalah mydashboard.

Selain itu, "direct_download" properti untuk permintaan ini diatur ke true sehingga responsnya adalah file yang diekspor itu sendiri.

Catatan

Properti "displayName" , yang ditampilkan di properti halaman respons, tidak mencerminkan nama dasbor yang terlihat di ruang kerja.

GET /api/2.0/workspace/export

Query parameters:
{
  "path": "/Users/first.last@example.com/examples_folder/mydashboard.lvdash.json",
  "direct_download": true
}

Response:
{
  "pages": [
    {
      "name": "880de22a",
      "displayName": "New Page"
    }
  ]
}

Mengodekan file yang diekspor

Kode berikut menunjukkan contoh respons di mana "direct_download" properti diatur ke false. Respons berisi konten sebagai string yang dikodekan base64.

GET /api/2.0/workspace/export

Query parameters:
{
    "path": "/Users/first.last@example.com/examples_folder/mydashboard.lvdash.json",
    "direct_download": false
}

Response:
{
    "content": "IORd/DYYsCNElspwM9XBZS/i5Z9dYgW5SkLpKJs48dR5p5KkIW8OmEHU8lx6CZotiCDS9hkppQG=",
    "file_type": "lvdash.json"
}

Langkah 3: Mengimpor dasbor

Anda dapat menggunakan Workspace Import API POST /api/2.0/workspace/import untuk mengimpor dasbor draf ke ruang kerja. Misalnya, setelah Anda mengekspor file yang dikodekan, seperti dalam contoh sebelumnya, Anda dapat mengimpor dasbor tersebut ke ruang kerja baru.

Agar impor dikenali sebagai dasbor Lakeview, dua parameter harus diatur:

  • "format": "AUTO" - pengaturan ini akan memungkinkan sistem mendeteksi jenis aset secara otomatis.
    • "path": harus menyertakan jalur file yang diakhir dengan ".lvdash.json".

Penting

Jika pengaturan ini tidak dikonfigurasi dengan benar, impor mungkin berhasil, tetapi dasbor akan diperlakukan seperti file biasa.

Contoh berikut menunjukkan permintaan impor yang dikonfigurasi dengan benar.


POST /api/2.0/workspace/import

Request body parameters:
{
        "path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json",
        "content": "IORd/DYYsCNElspwM9XBZS/i5Z9dYgW5SkLpKJs48dR5p5KkIW8OmEHU8lx6CZotiCDS9hkppQG=",
        "format": "AUTO"
}

Response:
{}

Langkah 4: Timpa impor (Opsional)

Mencoba menerbitkan ulang permintaan API yang sama menghasilkan kesalahan berikut:

{
        "error_code": "RESOURCE_ALREADY_EXISTS",
        "message": "Path (/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json) already exists."
}

Jika Anda ingin menimpa permintaan duplikat sebagai gantinya "overwrite" , atur properti ke true seperti dalam contoh berikut.


POST /api/2.0/workspace/import

Request body parameters:
{
        "path": /Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json",
        "content": "IORd/DYYsCNElspwM9XBZS/i5Z9dYgW5SkLpKJs48dR5p5KkIW8OmEHU8lx6CZotiCDS9hkppQG=",
        "format": "AUTO",
        "overwrite": true
}

Response:
{}

Langkah 5: Mengambil metadata

Anda dapat mengambil metadata untuk objek ruang kerja apa pun, termasuk dasbor Lakeview. Lihat GET /api/2.0/workspace/get-status.

Contoh berikut menunjukkan get-status permintaan untuk dasbor yang diimpor dari contoh sebelumnya. Respons mencakup detail yang menonfirmasi bahwa file telah berhasil diimpor sebagai "DASHBOARD". Selain itu, ini terdiri dari "resource_id" properti yang dapat Anda gunakan sebagai pengidentifikasi dengan API Lakeview.

GET /api/2.0/workspace/get-status

Query parameters:
{
        "path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json"
}

Response:
{
        "object_type": "DASHBOARD",
        "path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json",
        "object_id": 7616304051637820,
        "resource_id": "9c1fbf4ad3449be67d6cb64c8acc730b"
}

Langkah 6: Menerbitkan dasbor

Contoh sebelumnya menggunakan API Ruang Kerja, memungkinkan pekerjaan dengan dasbor Lakeview sebagai objek ruang kerja generik. Contoh berikut menggunakan API Lakeview untuk melakukan operasi penerbitan khusus untuk dasbor Lakeview. Lihat POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Jalur ke titik akhir API menyertakan properti yang "resource_id" dikembalikan dalam contoh sebelumnya. Dalam parameter permintaan, "embed_credentials" diatur ke true sehingga kredensial penerbit disematkan di dasbor. Penerbit, dalam hal ini, adalah pengguna yang membuat permintaan API resmi. Penerbit tidak dapat menyematkan kredensial pengguna yang berbeda. Lihat Menerbitkan dasbor untuk mempelajari cara kerja pengaturan Sematkan kredensial .

Properti "warehouse_id" mengatur gudang yang akan digunakan untuk dasbor yang diterbitkan. Jika ditentukan, properti ini akan mengambil alih gudang yang ditentukan untuk dasbor draf, jika ada.

POST /api/2.0/lakeview/dashboards/9c1fbf4ad3449be67d6cb64c8acc730b/published

Request parameters
{
  "embed_credentials": true,
  "warehouse_id": "1234567890ABCD12"
}

Response:
{}

Dasbor yang diterbitkan dapat diakses dari browser Anda ketika perintah selesai. Contoh berikut menunjukkan cara membuat tautan ke dasbor yang diterbitkan.

https://<deployment-url>/dashboardsv3/<resource_id>/published

Untuk membuat tautan unik Anda:

  • Ganti <deployment-url> dengan URL penyebaran Anda. Tautan ini adalah alamat di bilah alamat browser Anda saat Anda berada di beranda ruang kerja Azure Databricks Anda.
  • Ganti <resource_id> dengan nilai "resource_id" properti yang Anda identifikasi dalam mengambil metadata.

Langkah 7: Menghapus dasbor

Untuk menghapus dasbor, gunakan API Ruang Kerja. Lihat POST /api/2.0/workspace/delete.

Penting

Ini adalah penghapusan keras. Setelah perintah selesai, dasbor akan dihapus secara permanen.

Dalam contoh berikut, permintaan menyertakan jalur ke file yang dibuat di langkah-langkah sebelumnya.

POST /api/2.0/workspace/delete

Query parameters:
{
        "path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json"
}

Response:
{}

Langkah berikutnya

  • Untuk mempelajari selengkapnya tentang dasbor, lihat Dasbor.
  • Untuk mempelajari selengkapnya tentang REST API, lihat Referensi DATABricks REST API.