使用工作区 API 管理仪表板

项目
11/26/2024

本教程演示如何使用 Lakeview API 和工作区 API 管理仪表板。每个步骤都包含一个示例请求和响应，以及有关如何结合使用 API 工具和属性的说明。每个步骤都可以单独參考。按顺序完成所有步骤可引导你完成完整的工作流。

注意

此工作流调用工作区 API，以将 AI/BI 仪表板作为通用工作区对象进行检索。 AI/BI 仪表板以前称为 Lakeview 仪表板。 Lakeview API 仍保留该名称。

先决条件

需要个人访问令牌才能与工作区连接。请参阅 Azure Databricks 个人访问令牌身份验证。
需要具有要访问的工作区的工作区 ID。请参阅工作区实例名称、URL 和 ID
熟悉 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"。

注意

响应的 pages 属性中显示的 "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

构造唯一链接：

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

后续步骤

要了解有关仪表板的更多信息，请参阅仪表板。
若要详细了解 REST API，请参阅 Databricks REST API 参考。

通过