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. Auf dieser Seite 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. Um diese Aufgaben mithilfe der Benutzeroberfläche durchzuführen, siehe Autorendashboards.

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.

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.

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

Nächste Schritte

• Weitere Informationen zu Dashboards finden Sie unter Dashboards.
• Weitere Informationen zur REST-API finden Sie unter Databricks REST API-Referenz.