Delen via

Dashboards beheren met werkruimte-API's

  • Artikel

Deze zelfstudie laat zien hoe u dashboards beheert met behulp van de Lakeview-API en werkruimte-API. Elke stap bevat een voorbeeld van een aanvraag en antwoord en uitleg over het gebruik van de API-hulpprogramma's en eigenschappen. Elke stap kan afzonderlijk worden verwezen. Door alle stappen in de juiste volgorde te volgen, wordt u door een volledige werkstroom geleid.

Notitie

Deze werkstroom roept de Werkruimte-API aan om een AI/BI-dashboard op te halen als een algemeen werkruimteobject. AI-/BI-dashboards werden voorheen Lakeview-dashboards genoemd. De Lakeview-API behoudt die naam.

Voorwaarden

stap 1: een werkruimtemap verkennen

Met de WERKRUIMTElijst-API GET /api/2.0/workspace/list kunt u de mapstructuur van uw werkruimte verkennen. U kunt bijvoorbeeld een lijst met alle bestanden en mappen in uw huidige werkruimte ophalen.

In het volgende voorbeeld verwijst de eigenschap path in de aanvraag naar een map met de naam examples_folder opgeslagen in de basismap van een gebruiker. De gebruikersnaam wordt opgegeven in het pad, first.last@example.com.

In het antwoord ziet u dat de map een tekstbestand, een map en een AI/BI-dashboard bevat.

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

Stap 2: Een dashboard exporteren

Met de werkruimte-export-API GET /api/2.0/workspace/export kunt u de inhoud van een dashboard exporteren als bestand. AI/BI-dashboardbestanden weerspiegelen de conceptversie van een dashboard. In het antwoord in de volgende voorbeelden ziet u de inhoud van een minimale dashboarddefinitie. Als u meer serialisatiedetails wilt verkennen en begrijpen, kunt u een aantal van uw eigen dashboards exporteren.

Het geëxporteerde bestand downloaden

In het volgende voorbeeld ziet u hoe u een dashboardbestand downloadt met behulp van de API.

De eigenschap "path" in dit voorbeeld eindigt met de bestandsextensie lvdash.json, een AI/BI-dashboard. De bestandsnaam, zoals deze in de werkruimte wordt weergegeven, gaat vooraf aan die extensie. In dit geval is het mydashboard.

Bovendien wordt de eigenschap "direct_download" voor deze aanvraag ingesteld op true zodat het antwoord het geëxporteerde bestand zelf is en de eigenschap "format" is ingesteld op "AUTO".

Notitie

De eigenschap "displayName", weergegeven in de pagina-eigenschap van de respons, geeft niet de zichtbare naam van het dashboard in de werkomgeving weer.

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

Het geëxporteerde bestand coderen

De volgende code toont een voorbeeldantwoord waarbij "direct_download" eigenschap is ingesteld op false. Het antwoord bevat inhoud als een met base64 gecodeerde tekenreeks.

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

Stap 3: Een dashboard importeren

U kunt de Werkruimte importeren-API POST /api/2.0/workspace/import- gebruiken om conceptdashboards in een werkruimte te importeren. Nadat u bijvoorbeeld een gecodeerd bestand hebt geëxporteerd, zoals in het vorige voorbeeld, kunt u dat dashboard importeren in een nieuwe werkruimte.

Als u wilt dat een import wordt herkend als een AI/BI-dashboard, moeten er twee parameters worden ingesteld:

  • "format": 'AUTO': met deze instelling kan het systeem het assettype automatisch detecteren.
  • "path": moet een bestandspad bevatten dat eindigt op '.lvdash.json'.

Belangrijk

Als deze instellingen niet juist zijn geconfigureerd, kan het importeren lukken, maar wordt het dashboard behandeld als een normaal bestand.

In het volgende voorbeeld ziet u een correct geconfigureerde importaanvraag.


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

Stap 4: Overschrijven bij importeren (optioneel)

Als u dezelfde API-aanvraag opnieuw probeert uit te voeren, treedt de volgende fout op:

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

Als u in plaats daarvan de dubbele aanvraag wilt overschrijven, stelt u de eigenschap "overwrite" in op true zoals in het volgende voorbeeld.


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

stap 5: metagegevens ophalen

U kunt metagegevens ophalen voor elk werkruimteobject, inclusief een AI/BI-dashboard. Zie GET /api/2.0/workspace/get-status.

In het volgende voorbeeld ziet u een get-status aanvraag voor het geïmporteerde dashboard uit het vorige voorbeeld. Het antwoord bevat details die bevestigen dat het bestand succesvol is geïmporteerd als een "DASHBOARD". Het bestaat ook uit een "resource_id" eigenschap die u kunt gebruiken als id met de Lakeview-API.

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

Stap 6: Een dashboard publiceren

In de vorige voorbeelden is de Werkruimte-API gebruikt, waarmee het werken met AI/BI-dashboards als algemene werkruimteobjecten mogelijk wordt gemaakt. In het volgende voorbeeld wordt de Lakeview-API gebruikt om een publicatiebewerking uit te voeren die specifiek is voor AI/BI-dashboards. Zie POST /api/2.0/lakeview/dashboards/{dashboard_id}/gepubliceerd.

Het pad naar het API-eindpunt bevat de "resource_id" eigenschap die in het vorige voorbeeld is geretourneerd. In de aanvraagparameters is "embed_credentials" ingesteld op true zodat de referenties van de uitgever zijn ingesloten in het dashboard. De uitgever is in dit geval de gebruiker die de geautoriseerde API-aanvraag doet. De uitgever kan de referenties van verschillende gebruikers niet insluiten. Zie Een dashboard publiceren voor meer informatie over hoe de instelling Referenties insluiten werkt.

Met de eigenschap "warehouse_id" wordt het magazijn ingesteld dat moet worden gebruikt voor het gepubliceerde dashboard. Indien opgegeven, overschrijft deze eigenschap het magazijn dat is opgegeven voor het conceptdashboard, indien van toepassing.

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

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

Response:
{}

Het gepubliceerde dashboard kan worden geopend vanuit uw browser wanneer de opdracht is voltooid. In het volgende voorbeeld ziet u hoe u de koppeling naar uw gepubliceerde dashboard maakt.

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

Uw unieke koppeling maken:

  • Vervang <deployment-url> door uw implementatie-URL. Deze koppeling is het adres in de adresbalk van uw browser wanneer u zich op de startpagina van uw Azure Databricks-werkruimte bevindt.
  • Vervang <resource_id> door de waarde van de eigenschap "resource_id" die u hebt geïdentificeerd in metagegevensophalen.

Stap 7: Een dashboard verwijderen

Als u een dashboard wilt verwijderen, gebruikt u de Werkruimte-API. Zie POST /api/2.0/workspace/delete.

Belangrijk

Dit is een harde verwijdering. Wanneer de opdracht is voltooid, wordt het dashboard definitief verwijderd.

In het volgende voorbeeld bevat de aanvraag het pad naar het bestand dat in de vorige stappen is gemaakt.

POST /api/2.0/workspace/delete

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

Response:
{}

Volgende stappen