教學課程：使用工作區 API 管理儀錶板

  • 發行項

本教學課程示範如何使用 Lakeview API 和工作區 API 來管理儀錶板。 每個步驟都包含範例要求和回應，以及有關如何一起使用 API 工具和屬性的說明。 每個步驟都可以單獨參考。 遵循所有步驟，引導您完成完整的工作流程。

注意

此工作流程會呼叫工作區 API，以將 Lakeview 儀錶板擷取為一般工作區物件。

必要條件

步驟 1：探索工作區目錄

工作區清單 API GET /api/2.0/workspace/list 可讓您探索工作區的目錄結構。 例如，您可以擷取目前工作區中所有檔案和目錄的清單。

在下列範例中， path 要求中的 屬性會指向儲存在使用者主資料夾中的資料夾 examples_folder 。 用戶名稱會在路徑 first.last@example.com中提供。

回應顯示資料夾包含文字檔、目錄和 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"
    }
  ]
}

步驟 2：匯出儀錶板

工作區匯出 API GET /api/2.0/workspace/export 可讓您將儀錶板的內容導出為檔案。 Lakeview 儀錶板檔案會反映儀錶板的草稿版本。 下列範例中的回應會顯示最小儀錶板定義的內容。 若要探索並瞭解更多串行化詳細數據，請嘗試匯出一些您自己的儀錶板。

下載導出的檔案

下列範例示範如何使用 API 下載儀錶板檔案。

"path"此範例中的 屬性以擴展名 lvdash.json為 、Lakeview 儀錶板結尾。 檔名，如工作區中所示，位於該擴展名之前。 在這裡情況下，它是 mydashboard。

此外， "direct_download" 這個要求的 屬性會設定為 true ，因此響應是導出的檔案本身。

注意

回應 "displayName" 的 pages 屬性中顯示的 屬性不會反映工作區中儀錶板的可見名稱。

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

編碼導出的檔案

下列程式代碼顯示屬性設定為 false 的 "direct_download" 範例回應。 回應會以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"
}

步驟 3：匯入儀錶板

您可以使用工作區匯入 API POST /api/2.0/workspace/import 將草稿儀錶板匯入工作區。 例如，導出編碼的檔案之後，如上一個範例所示，您可以將該儀錶板匯入至新的工作區。

若要將匯入辨識為 Lakeview 儀錶板，必須設定兩個參數：

  • "format"：“AUTO” - 此設定可讓系統自動偵測資產類型。
    • "path"：必須包含以 「.lvdash.json」 結尾的檔案路徑。

重要

如果未正確設定這些設定，匯入可能會成功，但儀錶板會被視為一般檔案。

下列範例顯示正確設定的匯入要求。


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:
{}

步驟 4：在匯入時覆寫 （選擇性）

嘗試重新發出相同的 API 要求會導致下列錯誤：

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

如果您想要改為覆寫重複的要求，請將 屬性true設定"overwrite"為 ，如下列範例所示。


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:
{}

步驟 5：擷取元數據

您可以擷取任何工作區物件的元數據，包括 Lakeview 儀錶板。 請參閱 GET /api/2.0/workspace/get-status。

下列範例顯示 get-status 先前範例中匯入儀錶板的要求。 回應包含詳細資料，確認檔案已成功匯入為 "DASHBOARD"。 此外，它是由 "resource_id" 屬性所組成，您可以搭配 Lakeview API 做為標識符。

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

步驟 6：發佈儀錶板

上述範例使用工作區 API，讓使用 Lakeview 儀錶板作為一般工作區物件。 下列範例會使用 Lakeview API 來執行 Lakeview 儀錶板專屬的發佈作業。 請參閱 POST /api/2.0/lakeview/dashboards/{dashboard_id}/published。

API 端點的路徑包含 "resource_id" 上一個範例中傳回的屬性。 在要求參數中， "embed_credentials" 會設定為 true ，讓發行者的認證內嵌在儀錶板中。 在此情況下，發行者是發出授權 API 要求的使用者。 發行者無法內嵌不同的用戶認證。 請參閱 發佈儀錶板 以瞭解內 嵌認證 設定的運作方式。

屬性會 "warehouse_id" 設定要用於已發佈儀錶板的倉儲。 如果指定，此屬性會覆寫為草稿儀錶板指定的倉儲，如果有的話。

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

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

Response:
{}

當命令完成時，您可以從瀏覽器存取已發佈的儀錶板。 下列範例示範如何建構已發佈儀錶板的連結。

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

若要建構唯一的連結：

  • 將取代 <deployment-url> 為您的部署URL。 當您在 Azure Databricks 工作區首頁上時，此連結是瀏覽器網址列中的位址。
  • 將 取代<resource_id>為您在擷取元數據中所識別的屬性"resource_id"值。

步驟 7：刪除儀錶板

若要刪除儀錶板，請使用工作區 API。 請參閱 POST /api/2.0/workspace/delete。

重要

這是一個硬式刪除。 當命令完成時，儀錶板會永久刪除。

在下列範例中，要求會包含先前步驟中建立之檔案的路徑。

POST /api/2.0/workspace/delete

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

Response:
{}

下一步