使用工作區 API 管理儀表板

發行項
09/26/2024

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

注意

此工作流程會呼叫工作區 API，以將 AI/BI 儀表板作為一般工作區物件擷取。

必要條件

您需要個人存取權杖才能與工作區連線。請參閱 Azure Databricks 個人存取權杖驗證 (機器翻譯)。
您需要希望存取之工作區的工作區識別碼。請參閱工作區執行個體名稱、URL 和識別碼
熟悉 Databricks REST API 參考。

步驟 1：探索工作區目錄

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

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

回應顯示資料夾包含文字檔、目錄和 AI/BI 儀表板。

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 可讓您將儀表板的內容匯出為檔案。 AI/BI 儀表板檔案會反映儀表板的草稿版本。下列範例中的回應會顯示最小儀表板定義的內容。若要探索並了解更多序列化詳細資料，請嘗試匯出您自己的部分儀表板。

下載匯出的資料

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

此範例中的 "path" 屬性以副檔名 lvdash.json (為 AI/BI 儀表板) 結尾。如工作區中所示，檔名位於該副檔名之前。在此案例中，檔名為 mydashboard。

此外，此要求的 "direct_download" 屬性設定為 true，因此回應是匯出的檔案本身，並且 "format" 屬性設為 "AUTO"。

注意

回應之頁面屬性中顯示的 "displayName" 屬性，不會反映工作區中儀表板的可見名稱。

GET /api/2.0/workspace/export

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

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

編碼匯出的檔案

下列程式代碼顯示 "direct_download" 屬性設定為 false 的範例回應。回應會以 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 將草稿儀表板匯入工作區。例如，如上一個範例所示，匯出編碼的檔案之後，您可以將該儀表板匯入新的工作區。

若要將匯入識別為 AI/BI 儀表板，您必須設定兩個參數：

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

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


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：擷取中繼資料

您可以擷取任何工作區物件的中繼資料，包括 AI/BI 儀表板。請參閱 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，讓 AI/BI 儀表板作為一般工作區物件使用。下列範例會使用 Lakeview API 來執行 AI/BI 儀表板專屬的發佈作業。請參閱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

若要建構唯一的連結：

使用您的部署 URL 取代 <deployment-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:
{}

下一步

若要深入了解儀表板，請參閱儀表板。
若要深入了解 REST API，請參閱 Databricks REST API 參考 (英文)。

共用方式為