Manage dashboards with Workspace APIs

Article
10/21/2024

This tutorial demonstrates how to manage dashboards using the Lakeview API and Workspace API. Each step includes a sample request and response, and explanations about how to use the API tools and properties together. Each step can be referenced on its own. Following all steps in order guides you through a complete workflow.

Note

This workflow calls the Workspace API to retrieve an AI/BI dashboard as a generic workspace object.

Prerequisites

You need a personal access token to connect with your workspace. See Azure Databricks personal access token authentication.
You need the workspace ID of the workspace you want to access. See Workspace instance names, URLs, and IDs
Familiarity with the Databricks REST API reference.

Step 1: Explore a workspace directory

The Workspace List API GET /api/2.0/workspace/list allows you to explore the directory structure of your workspace. For example, you can retrieve a list of all files and directories in your current workspace.

In the following example, the path property in the request points to a folder named examples_folder stored in a user's home folder. The username is provided in the path, first.last@example.com.

The response shows that the folder contains a text file, a directory, and an AI/BI dashboard.

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

Step 2: Export a dashboard

The Workspace Export API GET /api/2.0/workspace/export allows you to export the contents of a dashboard as a file. AI/BI dashboard files reflect the draft version of a dashboard. The response in the following examples shows the contents of a minimal dashboard definition. To explore and understand more serialization details, try exporting some of your own dashboards.

Download the exported file

The following example shows how to download a dashboard file using the API.

The "path" property in this example ends with the file type extension lvdash.json, an AI/BI dashboard. The filename, as it appears in the workspace, precedes that extension. In this case, it's mydashboard.

Additionally, the "direct_download" property for this request is set to true so the response is the exported file itself, and the "format" property is set to "AUTO".

Note

The "displayName" property, shown in the pages property of the response, does not reflect the visible name of the dashboard in the workspace.

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

Encode the exported file

The following code shows an example response where "direct_download" property is set to false. The response contains content as a base64 encoded string.

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

Step 3: Import a dashboard

You can use the Workspace Import API POST /api/2.0/workspace/import to import draft dashboards into a workspace. For example, after you've exported an encoded file, as in the previous example, you can import that dashboard to a new workspace.

For an import to be recognized as a AI/BI dashboard, two parameters must be set:

"format": "AUTO" - this setting will allow the system to detect the asset type automatically.
"path": must include a file path that ends with ".lvdash.json".

Important

If these settings are not configured properly, the import might succeed, but the dashboard would be treated like a regular file.

The following example shows a properly configured import request.


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

Step 4: Overwrite on import (Optional)

Attempting to reissue the same API request results in the following error:

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

If you want to overwrite the duplicate request instead, set the "overwrite" property to true as in the following example.


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

Step 5: Retrieve metadata

You can retrieve metadata for any workspace object, including an AI/BI dashboard. See GET /api/2.0/workspace/get-status.

The following example shows a get-status request for the imported dashboard from the previous example. The response includes details affirming that the file has been successfully imported as a "DASHBOARD". Also, it consists of a "resource_id" property that you can use as an identifier with the 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"
}

Step 6: Publish a dashboard

The previous examples used the Workspace API, enabling work with AI/BI dashboards as generic workspace objects. The following example uses the Lakeview API to perform a publish operation specific to AI/BI dashboards. See POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

The path to the API endpoint includes the "resource_id" property returned in the previous example. In the request parameters, "embed_credentials" is set to true so that the publisher's credentials are embedded in the dashboard. The publisher, in this case, is the user who is making the authorized API request. The publisher cannot embed different user's credentials. See Publish a dashboard to learn how the Embed credentials setting works.

The "warehouse_id" property sets the warehouse to be used for the published dashboard. If specified, this property overrides the warehouse specified for the draft dashboard, if any.

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

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

Response:
{}

The published dashboard can be accessed from your browser when the command is complete. The following example shows how to construct the link to your published dashboard.

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

To construct your unique link:

Replace <deployment-url> with your deployment URL. This link is the address in your browser address bar when you are on your Azure Databricks workspace homepage.
Replace <resource_id> with the value of the "resource_id" property that you identified in retrieve metadata.

Step 7: Delete a dashboard

To delete a dashboard, use the Workspace API. See POST /api/2.0/workspace/delete.