Tutorial: Verwalten von Dashboards mit Arbeitsbereich-APIs

  • Artikel

In diesem Tutorial 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. Wenn Sie alle Schritte in der vorgegebenen Reihenfolge ausführen, werden Sie durch einen vollständigen Workflow geführt.

Hinweis

Mit diesem Workflow wird die Arbeitsbereichs-API aufgerufen, um ein Lakeview-Dashboard als generisches Arbeitsbereichsobjekt abzurufen.

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 namens examples_folder, der im Startordner eines Benutzers gespeichert ist. Der Benutzername wird im Pfad angegeben (first.last@example.com).

Die Antwort zeigt, dass der Ordner eine Textdatei, ein Verzeichnis und ein Lakeview-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. Lakeview-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 (Lakeview-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.

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
}

Response:
{
  "pages": [
    {
      "name": "880de22a",
      "displayName": "New Page"
    }
  ]
}

Codieren der exportierten Datei

Der folgende Code zeigt eine Beispielantwort, bei der die "direct_download"-Eigenschaft auf „false“ festgelegt ist. Die Antwort enthält eine 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 wie im vorherigen Beispiel eine codierte Datei exportiert haben, können Sie dieses Dashboard in einen neuen Arbeitsbereich importieren.

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

  • "format": "AUTO" – Diese Einstellung ermöglicht es dem System, den Objekttyp automatisch zu erkennen.
    • "path": Diese Angabe 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 auszugeben, 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 "overwrite"-Eigenschaft 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 Lakeview-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 und die Arbeit mit Lakeview-Dashboards als generische Arbeitsbereichsobjekte ermöglicht. Im folgenden Beispiel wird die Lakeview-API verwendet, um einen Veröffentlichungsvorgang auszuführen, der spezifisch für Lakeview-Dashboards 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 in das Dashboard eingebettet werden. 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. Unter Veröffentlichen eines Dashboards erfahren Sie, wie die Einstellung zum 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

Erstellen Ihres eindeutigen Links:

  • Ersetzen Sie <deployment-url> durch Ihre Bereitstellungs-URL. Dieser Link ist die Adresse in Ihrer Browseradressleiste, wenn Sie sich auf der Startseite Ihres Azure Databricks-Arbeitsbereichs 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