Verwenden von Dashboard-APIs zum Erstellen und Verwalten von Dashboards

Die Databricks-REST-API enthält Verwaltungstools speziell für die Verwaltung von AI/BI-Dashboards. In diesem Artikel wird veranschaulicht, wie Sie ein neues AI/BI-Dashboard aus einem vorhandenen Legacy-Dashboard erstellen. Anschließend wird gezeigt, wie Api-Tools zum Verwalten des Dashboards verwendet werden.

Hinweis

AI/BI-Dashboards wurden zuvor als Lakeview-Dashboards bezeichnet. Die Lakeview-API behält diesen Namen weiterhin bei.

Voraussetzungen

Richten Sie die Authentifizierung für den Zugriff auf Azure Databricks-Ressourcen ein. Informationen zu Authentifizierungsoptionen und Einrichtungsanweisungen finden Sie unter Autorisieren des Zugriffs auf Azure Databricks-Ressourcen.
Sie benötigen die Arbeitsbereichs-URL(n), auf die Sie zugreifen möchten. Weitere Informationen finden Sie unter Instanznamen, URLs und IDs von Arbeitsbereichen.
Vertrautheit mit der Databricks REST API-Referenz.

Migrieren eines Dashboards

Sie können ein neues AI/BI-Dashboard aus einem vorhandenen Legacy-Dashboard erstellen. Für den Endpunkt zum Migrieren des Dashboards in der Lakeview-API ist source_dashboard_id erforderlich. Optional können Sie einen Anzeigenamen und einen Pfad angeben, in dem das neue Dashboard gespeichert werden soll.

Abrufen von Legacydashboards

Verwenden Sie zum Abrufen von source_dashboard_id die Legacydashboard-API, um eine Liste aller Dashboards in Ihrem Arbeitsbereich abzurufen. Jedes Dashboardobjekt in der liste results enthält eine UUID, die Sie verwenden können, um auf das Legacy-Dashboard in azure Databricks-REST-API-Diensten zu verweisen.

Das folgende Beispiel zeigt eine Beispielanforderung und -antwort für den Endpunkt zum Abrufen von Dashboardobjekten. Einige Antwortdetails wurden aus Gründen der Klarheit weggelassen. Eine vollständige Beschreibung dieses Endpunkts und eine Beispielantwort finden Sie unter GET "/api/2.0/preview/sql/dashboards ".

Die UUID für ein Legacy-Dashboard ist die id aus der obersten Ebene der Liste der Objekte, die in resultszurückgegeben werden. Bei älteren Dashboards sieht die UUID wie 4e443c27-9f61-4f2e-a12d-ea5668460bf1aus.

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

Legacy-Dashboard migrieren

Verwenden Sie die UUID, die dem Legacy-Dashboard zugeordnet ist, um eine Kopie zu erstellen, die automatisch in ein neues AI/BI-Dashboard konvertiert wird. Dies funktioniert wie das Tool zum Klonen im AI/BI-Dashboard, das auf der Benutzeroberfläche verfügbar ist. Weitere Informationen zum Ausführen dieses Vorgangs mithilfe der Azure Databricks-Benutzeroberfläche finden Sie unter Klonen eines legacy-Dashboards zu einem AI/BI-Dashboard.

Die UUID des legacy-Dashboards, das Sie konvertieren möchten, ist im Anforderungstext erforderlich. Optional können Sie einen neuen display_name-Wert und einen parent_path einschließen, der den Arbeitsbereichspfad des Ordners angibt, in dem das konvertierte Dashboard gespeichert werden soll.

Die Antwort enthält eine dashboard_id, die UUID für das neue Dashboard. Die UUID für ein AI/BI-Dashboard ist ein 32-stelliger alphanumerischer Wert wie 04aab30f99ea444490c10c85852f216c. Sie können es verwenden, um dieses Dashboard im Lakeview-Namespace und über verschiedene Azure Databricks-REST-API-Dienste hinweg zu identifizieren.

Das folgende Beispiel zeigt eine Beispielanforderung und -antwort. Weitere Informationen finden Sie unter 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"
}

Abrufen eines Entwurfsdashboards

Sie können die dashboard_id verwenden, um Dashboarddetails aus einem Entwurfsdashboard abzurufen. Die folgende Beispielanforderung und -antwort enthält Details zur aktuellen Version des Entwurfsdashboards im Arbeitsbereich.

Im Feld etag wird die aktuelle Version des Dashboards nachverfolgt. Sie können dies verwenden, um die Version zu überprüfen, bevor Sie zusätzliche Updates vornehmen.

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

Aktualisieren eines Dashboards

Sie können die dashboard_id in der vorherigen Antwort verwenden, um das mit diesem Vorgang erstellte neue AI/BI-Dashboard zu aktualisieren. Das folgende Beispiel zeigt eine Beispielanforderung und -antwort. Die dashboard_id aus dem vorherigen Beispiel ist als Pfadparameter enthalten.

display_name und warehouse_id wurden geändert. Das aktualisierte Dashboard verfügt über einen neuen Namen und zugewiesenes Standardlager, wie in der Antwort dargestellt. Das feld etag ist optional. Wenn die in der etag angegebene Version nicht mit der aktuellen Version übereinstimmt, wird das Update abgelehnt.

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

Ein Dashboard erstellen

Sie können den Endpunkt 'Dashboard erstellen' in der Lakeview-API verwenden, um Ihr Dashboard zwischen Arbeitsbereichen zu verschieben. Das folgende Beispiel enthält einen Beispielanforderungstext und eine Antwort, die ein neues Dashboard erstellt. Der serialized_dashboard Schlüssel aus dem vorherigen Beispiel enthält alle erforderlichen Details zum Erstellen eines doppelten Entwurfsdashboards.

Das Beispiel enthält einen neuen warehouse_id Wert, der einem Lager im neuen Arbeitsbereich entspricht. Weitere Informationen finden Sie unter 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"
}

Die einzige erforderliche Eigenschaft im Anforderungstext ist display_name. Dieses Tool kann Dashboardinhalte kopieren oder neue leere Dashboards erstellen.

Veröffentlichen eines Dashboards

Sie können den Endpunkt zum Veröffentlichung von Dashboards verwenden, um ein Dashboard zu veröffentlichen, Anmeldeinformationen für Viewer festzulegen und die im Entwurfsdashboard festgelegte Warehouse-ID (warehouse_id) außer Kraft zu setzen. Sie müssen die UUID des Dashboards als Pfadparameter einschließen.

Der Anforderungstext legt die eigenschaft embed_credentials auf falsefest. embed_credentials ist standardmäßig auf true festgelegt. Durch das Einbetten von Anmeldeinformationen können Benutzer auf Kontoebene Dashboarddaten anzeigen. Siehe Veröffentlichen eines Dashboards. Ein neuer warehouse_id Wert wird weggelassen, sodass das veröffentlichte Dashboard das gleiche Lager verwendet, das dem Entwurfsdashboard zugewiesen ist.

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

Veröffentlichen eines Dashboards mit Anmeldeinformationen des Dienstprinzipals

Sie können ein Dashboard veröffentlichen, das Dienstprinzipalanmeldeinformationen eingebettet hat, indem Sie sich beim API-Aufruf als Dienstprinzipal authentifizieren. Wenn Sie mit dem Token eines Dienstprinzipals veröffentlichen, wird das Dashboard mit den Daten und Berechtigungen zur Datenverarbeitung dieses Dienstprinzipals veröffentlicht, sodass Benutzer ohne direkten Datenzugriff das Dashboard anzeigen können.

Vor der Veröffentlichung muss der Dienstprinzipal mindestens über "CAN MANAGE"-Berechtigungen für das Dashboard, SELECT-Privilegien für alle im Dashboard verwendeten Datenquellen und "CAN USE"-Berechtigungen für das Lager verfügen. Ausführliche Informationen zum Erstellen von Dienstprinzipalen und zum Generieren von OAuth-Schlüsseln finden Sie unter Dienstprinzipale und Autorisieren des Dienstprinzipalszugriffs auf Azure Databricks mit OAuth.

Authentifizieren Sie sich zunächst als Dienstprinzipal, um ein Zugriffstoken abzurufen:

POST https://<databricks-instance>/oidc/v1/token

Request body (form-urlencoded):

grant_type=client_credentials&scope=all-apis

Authorization header:

Basic <base64-encoded-client-id:client-secret>

Response:

{
  "access_token": "eyJraWQiOiJkYTA4ZTVjZ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Verwenden Sie dann das Zugriffstoken, um das Dashboard mit den Anmeldeinformationen des Dienstprinzipals zu veröffentlichen:

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

Authorization header:

Bearer <service-principal-access-token>

Request body:

{
  "embed_credentials": true,
  "warehouse_id": "5e2f98ab3476cfd0"
}

Response:

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

Wenn embed_credentials diese Einstellung festgelegt true ist, verwenden die Viewer des Dashboards die Berechtigungen des Dienstprinzipals für den Zugriff auf Daten und Rechenressourcen. Benutzer benötigen nur Berechtigungen für den Zugriff auf das Dashboardobjekt selbst. Alle Dashboardabfragen werden mit der Identität des Dienstprinzipals ausgeführt, sodass Überwachungsprotokolle den Dienstprinzipal als Abfrageausführer anzeigen.

Veröffentlichtes Dashboard abrufen

Die Antwort von GET /api/2.0/lakeview/dashboards/{dashboard_id}/published ähnelt der Antwort im vorherigen Beispiel. Die dashboard_id ist als Pfadparameter enthalten.

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

Aufheben der Veröffentlichung eines Dashboards

Das Entwurfsdashboard wird beibehalten, wenn Sie die Lakeview-API verwenden, um die Veröffentlichung eines Dashboards aufzuheben. Diese Anforderung löscht die veröffentlichte Version des Dashboards.

Im folgenden Beispiel wird die dashboard_id aus dem vorherigen Beispiel verwendet. Eine erfolgreiche Anforderung liefert einen 200 Statuscode. Es gibt keinen Antwortkörper.

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

Entfernen eines Dashboards

Verwenden Sie DELETE /api/2.0/lakeview/dashboards/{dashboard_id}, um ein Entwurfs-Dashboard an den Papierkorb zu senden. Das Dashboard kann weiterhin wiederhergestellt werden.