Självstudie: Hantera instrumentpaneler med API:er för arbetsytor

Artikel
04/27/2024

Den här självstudien visar hur du hanterar instrumentpaneler med lakeview-API:et och api:et för arbetsytor. Varje steg innehåller en exempelbegäran och ett svar samt förklaringar om hur du använder API-verktygen och egenskaperna tillsammans. Varje steg kan refereras på egen hand. Genom att följa alla steg i ordning vägleder du dig genom ett fullständigt arbetsflöde.

Kommentar

Det här arbetsflödet anropar API:et för arbetsyta för att hämta en Lakeview-instrumentpanel som ett allmänt arbetsyteobjekt.

Förutsättningar

Du behöver en personlig åtkomsttoken för att ansluta till din arbetsyta. Mer information finns i autentisering med personlig åtkomsttoken i Azure Databricks.
Du behöver arbetsytans ID för den arbetsyta som du vill komma åt. Se Namn på arbetsyteinstanser, URL:er och ID:er
Kunskaper om Databricks REST API-referens.

Steg 1: Utforska en arbetsytekatalog

Med API :et GET /api/2.0/workspace/list för arbetsytan kan du utforska arbetsytans katalogstruktur. Du kan till exempel hämta en lista över alla filer och kataloger i den aktuella arbetsytan.

I följande exempel path pekar egenskapen i begäran på en mapp med namnet examples_folder lagrad i en användares hemmapp. Användarnamnet anges i sökvägen, first.last@example.com.

Svaret visar att mappen innehåller en textfil, en katalog och en Lakeview-instrumentpanel.

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

Steg 2: Exportera en instrumentpanel

Med API :et för arbetsytans export AV GET /api/2.0/workspace/export kan du exportera innehållet i en instrumentpanel som en fil. Lakeview-instrumentpanelsfiler återspeglar utkastversionen av en instrumentpanel. Svaret i följande exempel visar innehållet i en minimal instrumentpanelsdefinition. Om du vill utforska och förstå mer serialiseringsinformation kan du prova att exportera några av dina egna instrumentpaneler.

Ladda ned den exporterade filen

I följande exempel visas hur du laddar ned en instrumentpanelsfil med hjälp av API:et.

Egenskapen "path" i det här exemplet slutar med filtypstillägget lvdash.json, en Lakeview-instrumentpanel. Filnamnet, som det visas på arbetsytan, föregår tillägget. I det här fallet är mydashboarddet .

Dessutom är egenskapen för den "direct_download" här begäran inställd på så att true svaret är själva den exporterade filen.

Kommentar

Egenskapen "displayName" , som visas i sidegenskapen för svaret, återspeglar inte instrumentpanelens synliga namn på arbetsytan.

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

Koda den exporterade filen

Följande kod visar ett exempelsvar där "direct_download" egenskapen är inställd på false. Svaret innehåller innehåll som en base64-kodad sträng.

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

Steg 3: Importera en instrumentpanel

Du kan använda API:et för import av arbetsytan POST /api/2.0/workspace/import för att importera utkastinstrumentpaneler till en arbetsyta. När du till exempel har exporterat en kodad fil, som i föregående exempel, kan du importera instrumentpanelen till en ny arbetsyta.

För att en import ska kunna identifieras som en Lakeview-instrumentpanel måste två parametrar anges:

"format": "AUTO" – med den här inställningen kan systemet identifiera tillgångstypen automatiskt.
- "path": måste innehålla en filsökväg som slutar med ".lvdash.json".

Viktigt!

Om de här inställningarna inte har konfigurerats korrekt kan importen lyckas, men instrumentpanelen behandlas som en vanlig fil.

I följande exempel visas en korrekt konfigurerad importbegäran.


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

Steg 4: Skriv över vid import (valfritt)

Försök att återutge samma API-begäran resulterar i följande fel:

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

Om du vill skriva över den duplicerade begäran i stället anger du "overwrite" egenskapen till true som i följande exempel.


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

Steg 5: Hämta metadata

Du kan hämta metadata för valfritt arbetsyteobjekt, inklusive en Lakeview-instrumentpanel. Se GET /api/2.0/workspace/get-status.

I följande exempel visas en get-status begäran om den importerade instrumentpanelen från föregående exempel. Svaret innehåller information som bekräftar att filen har importerats som en "DASHBOARD". Dessutom består den av en "resource_id" egenskap som du kan använda som identifierare med Lakeview-API:et.

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

Steg 6: Publicera en instrumentpanel

I föregående exempel användes API:et För arbetsytor, vilket aktiverade arbete med Lakeview-instrumentpaneler som allmänna arbetsyteobjekt. I följande exempel används Lakeview API för att utföra en publiceringsåtgärd som är specifik för Lakeview-instrumentpaneler. Se POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Sökvägen till API-slutpunkten innehåller egenskapen "resource_id" som returnerades i föregående exempel. I parametrarna "embed_credentials" för begäran anges till true så att utgivarens autentiseringsuppgifter bäddas in på instrumentpanelen. Utgivaren är i det här fallet den användare som gör den auktoriserade API-begäran. Utgivaren kan inte bädda in olika användares autentiseringsuppgifter. Se Publicera en instrumentpanel för att lära dig hur inställningen Bädda in autentiseringsuppgifter fungerar.

Egenskapen "warehouse_id" anger vilket lager som ska användas för den publicerade instrumentpanelen. Om den här egenskapen anges åsidosätter den informationslager som angetts för den eventuella instrumentpanelen för utkast.

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

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

Response:
{}

Den publicerade instrumentpanelen kan nås från webbläsaren när kommandot är klart. I följande exempel visas hur du skapar länken till den publicerade instrumentpanelen.

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

Så här skapar du din unika länk:

Ersätt <deployment-url> med distributions-URL:en. Den här länken är adressen i webbläsarens adressfält när du är på startsidan för Azure Databricks-arbetsytan.
Ersätt <resource_id> med värdet för den "resource_id" egenskap som du identifierade i hämta metadata.

Steg 7: Ta bort en instrumentpanel

Om du vill ta bort en instrumentpanel använder du API:et för arbetsyta. Se POST /api/2.0/workspace/delete.