使用 Lakeview API 创建和管理仪表板

项目
05/22/2024

Lakeview API 提供了专门用于管理 Lakeview 仪表板的管理工具。本文演示如何基于现有的旧版仪表板创建新的 Lakeview 仪表板。然后，演示如何使用 Lakeview API 管理该仪表板。

先决条件

需要个人访问令牌才能与工作区连接。请参阅 Azure Databricks 个人访问令牌身份验证。
你需要掌握要访问的工作区 URL。请参阅工作区实例名称、URL 和 ID
熟悉 Databricks REST API 参考。

迁移仪表板

你可以基于现有的旧版仪表板创建新的 Lakeview 仪表板。 Lakeview API 中的“迁移仪表板”终结点需要 source_dashboard_id。（可选）你可以包含显示名称和要用于存储新仪表板的路径。

获取 Databricks SQL 仪表板

若要获取 source_dashboard_id，请使用 Databricks SQL 仪表板 API 获取工作区中所有仪表板的列表。 results 列表中的每个仪表板对象都包含一个 UUID，可用于在各个 Azure Databricks REST API 服务中引用旧版仪表板。

以下示例演示了“获取仪表板对象”终结点的示例请求和响应。为了清楚起见，这里省略了一些响应详细信息。有关此终结点和示例响应的完整说明，请参阅 GET /api/2.0/preview/sql/dashboards。

旧版仪表板的 UUID 是在 results 中返回的对象列表的顶层 id。对于旧版仪表板，UUID 的形式类似于 4e443c27-9f61-4f2e-a12d-ea5668460bf1。

GET /api/2.0/preview/sql/dashboards

Query Parameters:

{
"page_size": <optional>,
"page": <optional>,
"order": <optional>
"q": <optional>
}

Response:

{
  "count": 1,
  "page": 1,
  "page_size": 25,
  "results": [
    {
      "id": "4e443c27-9f61-4f2e-a12d-ea5668460bf1",
      "slug": "sales-dashboard",
      "parent": "folders/2025532471912059",
      ...
    }
  ]
}

迁移旧版仪表板

请使用与旧版仪表板关联的 UUID 创建将会自动转换为新 Lakeview 仪表板的副本。这类似于 UI 中提供的“克隆到 Lakeview”工具。请参阅将旧版仪表板克隆到 Lakeview 仪表板，了解如何使用 Azure Databricks UI 执行此操作。

请求正文中需要具有要转换的旧版仪表板的 UUID。（可选）你可以包含一个新的 display_name 值和一个 parent_path，后者所标识的工作区路径指代的是要用于存储转换后的仪表板的文件夹。

响应包括 dashboard_id，即新仪表板的 UUID。 Lakeview 仪表板的 UUID 是一个 32 位的字母数字值，如 04aab30f99ea444490c10c85852f216c。你可以使用它来在 Lakeview 命名空间和不同的 Azure Databricks REST API 服务中标识此仪表板。

以下示例演示了一个示例请求和响应。请参阅 POST /api/2.0/lakeview/dashboards/migrate。

POST /api/2.0/lakeview/dashboards/migrate

Request body parameters:
{
  "source_dashboard_id": "4e443c27-9f61-4f2e-a12d-ea5668460bf1",
  "display_name": "Monthly Traffic Report",
  "parent_path": "/path/to/dir"
}

Response:
{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report",
  "path": "/path/to/dir/Monthly Traffic Report.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "47bb1c472649e711",
  "etag": "80611980",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

获取草稿仪表板

你可以使用 dashboard_id 从草稿仪表板拉取仪表板详细信息。以下示例请求和响应包括工作区中当前版本的草稿仪表板的详细信息。

etag 字段会跟踪最新版本的仪表板。你可以在进行其他更新之前使用此字段来验证所用版本。

GET /api/2.0/lakeview/dashboards/04aab30f99ea444490c10c85852f216c

Response:

{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report",
  "path": "/path/to/dir/Monthly Traffic Report.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "47bb1c472649e711",
  "etag": "80611980",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

更新仪表板

你可以使用上一响应中的 dashboard_id 来更新使用该操作创建的新 Lakeview 仪表板。以下示例演示了一个示例请求和响应。前面示例中的 dashboard_id 将作为路径参数包含在内。

display_name 和 warehouse_id 已发生更改。更新后的仪表板具有新的名称和分配的默认仓库，如响应中所示。 etag 字段为可选。如果 etag 中指定的版本与当前版本不匹配，系统将拒绝更新。

PATCH /api/2.0/lakeview/dashboards/04aab30f99ea444490c10c85852f216c

Request body:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "c03a4f8a7162bc9f",
  "etag": "80611980"
}

Response:

{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report 2",
  "path": "/path/to/dir/Monthly Traffic Report 2.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "c03a4f8a7162bc9f",
  "etag": "80611981",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

创建仪表板

你可以使用 Lakeview API 中的“创建仪表板”终结点来在工作区之间移动仪表板。以下示例包含一个创建新仪表板的示例请求正文和响应。前面示例中的 serialized_dashboard 键包含创建重复草稿仪表板所需的所有详细信息。

此示例包含对应于新工作区中的仓库的新 warehouse_id 值。请参阅 POST /api/2.0/lakeview/dashboards。

POST /api/2.0/lakeview/dashboards

Request body:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "parent_path": "/path/to/dir"
}

Response:

{
  "dashboard_id": "1e23fd84b6ac7894e2b053907dca9b2f",
  "display_name": "Monthly Traffic Report 2",
  "path": "/path/to/dir/Monthly Traffic Report 2.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "5e2f98ab3476cfd0",
  "etag": "14350695",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

请求正文中唯一必需的属性是 display_name。此工具可以复制仪表板内容或创建新的空白仪表板。

发布仪表板

你可以使用“发布仪表板”终结点来发布仪表板、为审查者设置凭据，以及覆盖草稿仪表板中设置的 warehouse_id。请务必将仪表板的 UUID 作为路径参数包含在内。

下方的请求正文将 embed_credentials 属性设置为 false。默认情况下，embed_credentials 设置为 true。嵌入凭据允许帐户级用户查看仪表板数据。请参阅发布仪表板。请求正文中省略了新的 warehouse_id 值，因此发布的仪表板将使用分配给草稿仪表板的同一仓库。

POST /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Request body:

{
  "embed_credentials": false
}

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": false,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

获取发布的仪表板

来自 GET /api/2.0/lakeview/dashboards/{dashboard_id}/发布的的响应类似于上一示例中提供的响应。 dashboard_id 将作为路径参数包含在内。

GET /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": false,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

取消发布仪表板

使用 Lakeview API 取消发布仪表板时，会保留草稿仪表板。此请求将删除发布的仪表板版本。

以下示例使用了上一示例中的 dashboard_id。成功的请求将生成 200 状态代码。此时没有响应正文。

DELETE /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

将仪表板移入回收站

请使用 DELETE /api/2.0/lakeview/dashboards/{dashboard_id} 将草稿仪表板发送到回收站。该仪表板仍可恢复。