Teilen über

Verwalten von Dashboards mit Arbeitsbereich-APIs

  • Artikel

In diesem Lernprogramm wird das Verwalten von Dashboards mithilfe der Lakeview-API und der Arbeitsbereichs-API veranschaulicht. Jeder Schritt enthält eine Beispielanforderung und -antwort sowie Erläuterungen zur gemeinsamen Verwendung der API-Tools und -Eigenschaften. Jeder Schritt kann eigenständig referenziert werden. Indem Sie alle Schritte der Reihe nach ausführen, gelangen Sie durch einen vollständigen Workflow.

Hinweis

Dieser Workflow ruft die Arbeitsbereichs-API auf, um ein AI/BI-Dashboard als generisches Arbeitsbereichsobjekt abzurufen. AI/BI-Dashboards wurden zuvor als Lakeview-Dashboards bezeichnet. Die Lakeview-API behält diesen Namen bei.

Voraussetzungen

Schritt 1: Erkunden eines Arbeitsbereichsverzeichnisses

Mit der Arbeitsbereichslisten-API GET /api/2.0/workspace/list können Sie die Verzeichnisstruktur Ihres Arbeitsbereichs erkunden. Sie können beispielsweise eine Liste aller Dateien und Verzeichnisse in Ihrem aktuellen Arbeitsbereich abrufen.

Im folgenden Beispiel verweist die path-Eigenschaft in der Anforderung auf einen Ordner mit dem Namen examples_folder, der im Heimordner eines Benutzers gespeichert ist. Der Benutzername wird im Pfad first.last@example.comangegeben.

Die Antwort zeigt, dass der Ordner eine Textdatei, ein Verzeichnis und ein AI/BI-Dashboard enthält.

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

Schritt 2: Exportieren eines Dashboards

Mit der Arbeitsbereichsexport-API GET /api/2.0/workspace/export können Sie den Inhalt eines Dashboards als Datei exportieren. AI/BI-Dashboarddateien spiegeln die Entwurfsversion eines Dashboards wider. Die Antwort in den folgenden Beispielen zeigt den Inhalt einer minimalen Dashboarddefinition. Um weitere Serialisierungsdetails zu erkunden und zu verstehen, versuchen Sie, einige Ihrer eigenen Dashboards zu exportieren.

Herunterladen der exportierten Datei

Das folgende Beispiel zeigt, wie Sie eine Dashboarddatei mithilfe der API herunterladen.

Die "path"-Eigenschaft in diesem Beispiel endet mit der Dateityperweiterung lvdash.json, einem AI/BI-Dashboard. Der Dateiname, wie er im Arbeitsbereich angezeigt wird, steht vor dieser Erweiterung. In diesem Fall ist es mydashboard.

Darüber hinaus wird die "direct_download"-Eigenschaft für diese Anforderung auf true festgelegt, sodass die Antwort die exportierte Datei selbst ist und die "format"-Eigenschaft auf "AUTO"festgelegt ist.

Hinweis

Die "displayName"-Eigenschaft, die in der Seiteneigenschaft der Antwort angezeigt wird, spiegelt nicht den sichtbaren Namen des Dashboards im Arbeitsbereich wider.

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

Codieren der exportierten Datei

Der folgende Code zeigt eine Beispielantwort, in der "direct_download" Eigenschaft auf "false" festgelegt ist. Die Antwort enthält Inhalt als base64-codierte Zeichenfolge.

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

Schritt 3: Importieren eines Dashboards

Sie können die Arbeitsbereichsimport-API POST /api/2.0/workspace/import verwenden, um Entwurfsdashboards in einen Arbeitsbereich zu importieren. Nachdem Sie beispielsweise eine codierte Datei exportiert haben, wie im vorherigen Beispiel, können Sie dieses Dashboard in einen neuen Arbeitsbereich importieren.

Damit ein Import als AI/BI-Dashboard erkannt wird, müssen zwei Parameter festgelegt werden:

  • "format": "AUTO" – Diese Einstellung ermöglicht dem System, den Objekttyp automatisch zu erkennen.
  • "path": muss einen Dateipfad enthalten, der mit ".lvdash.json" endet.

Wichtig

Wenn diese Einstellungen nicht ordnungsgemäß konfiguriert sind, kann der Import erfolgreich ausgeführt werden, das Dashboard wird jedoch wie eine normale Datei behandelt.

Das folgende Beispiel zeigt eine ordnungsgemäß konfigurierte Importanforderung.


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

Schritt 4: Überschreiben beim Import (optional)

Beim Versuch, dieselbe API-Anforderung erneut aufzufordern, tritt der folgende Fehler auf:

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

Wenn Sie stattdessen die duplizierte Anforderung überschreiben möchten, legen Sie die eigenschaft "overwrite" wie im folgenden Beispiel auf true fest.


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

Schritt 5: Abrufen von Metadaten

Sie können Metadaten für jedes Arbeitsbereichsobjekt abrufen, einschließlich eines AI/BI-Dashboards. Weitere Informationen finden Sie unter GET/api/2.0/workspace/get-status.

Das folgende Beispiel zeigt eine get-status Anforderung für das importierte Dashboard aus dem vorherigen Beispiel. Die Antwort enthält Details, die bestätigen, dass die Datei erfolgreich als "DASHBOARD"importiert wurde. Außerdem besteht sie aus einer "resource_id" Eigenschaft, die Sie als Bezeichner mit der Lakeview-API verwenden können.

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

Schritt 6: Veröffentlichen eines Dashboards

In den vorherigen Beispielen wurde die Arbeitsbereichs-API verwendet, um die Arbeit mit AI/BI-Dashboards als generische Arbeitsbereichsobjekte zu ermöglichen. Im folgenden Beispiel wird die Lakeview-API verwendet, um einen Veröffentlichungsvorgang auszuführen, der speziell für AI/BI-Dashboards spezifisch ist. Weitere Informationen finden Sie unter POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Der Pfad zum API-Endpunkt enthält die im vorherigen Beispiel zurückgegebene "resource_id" Eigenschaft. In den Anforderungsparametern wird "embed_credentials" auf true festgelegt, sodass die Anmeldeinformationen des Herausgebers im Dashboard eingebettet sind. Der Herausgeber ist in diesem Fall der Benutzer, der die autorisierte API-Anforderung durchführt. Der Herausgeber kann die Anmeldeinformationen eines anderen Benutzers nicht einbetten. Lesen Sie Veröffentlichen eines Dashboards, um zu erfahren, wie die Einstellung Einbetten von Anmeldeinformationen funktioniert.

Die "warehouse_id"-Eigenschaft legt das Warehouse fest, das für das veröffentlichte Dashboard verwendet werden soll. Sofern angegeben, überschreibt diese Eigenschaft das für das Entwurfsdashboard (sofern vorhanden) angegebene Warehouse.

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

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

Response:
{}

Auf das veröffentlichte Dashboard kann über Ihren Browser zugegriffen werden, wenn der Befehl abgeschlossen ist. Das folgende Beispiel zeigt, wie Sie den Link zu Ihrem veröffentlichten Dashboard erstellen.

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

So erstellen Sie Ihren eindeutigen Link:

  • Ersetzen Sie <deployment-url> durch Ihre Bereitstellungs-URL. Dieser Link ist die Adresse in Ihrer Browseradressleiste, wenn Sie sich auf Ihrer Azure Databricks-Arbeitsbereich-Homepage befinden.
  • Ersetzen Sie <resource_id> durch den Wert der "resource_id"-Eigenschaft, den Sie unter Abrufen von Metadaten identifiziert haben.

Schritt 7: Löschen eines Dashboards

Verwenden Sie die Arbeitsbereichs-API, um ein Dashboard zu löschen. Weitere Informationen finden Sie unter POST /api/2.0/workspace/delete.

Wichtig

Dies ist ein endgültiger Löschvorgang. Nach Abschluss des Befehls wird das Dashboard endgültig gelöscht.

Im folgenden Beispiel enthält die Anforderung den Pfad zu der Datei, die in den vorherigen Schritten erstellt wurde.

POST /api/2.0/workspace/delete

Query parameters:
{
        "path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json"
}

Response:
{}

Nächste Schritte