Dela via

Hantera instrumentpaneler med arbetsytans API:er

  • Artikel

Den här handledningen visar hur du hanterar instrumentpaneler med Lakeview API:et och Workspace API:et. 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.

Not

Det här arbetsflödet anropar API:et för arbetsyta för att hämta en AI/BI-instrumentpanel som ett allmänt arbetsyteobjekt. AI/BI-instrumentpaneler kallades tidigare Lakeview-instrumentpaneler. Lakeview-API:et behåller det namnet.

Förutsättningar

Steg 1: Utforska en arbetsytekatalog

Med API:et för arbetsytelista GET /api/2.0/workspace/list 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 pekar egenskapen path i begäran på en mapp med namnet examples_folder som lagras 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 AI/BI-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 instrumentpanelen

Med API:et för arbetsyteexport GET /api/2.0/workspace/export kan du exportera innehållet i en instrumentpanel som en fil. AI/BI-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 information om serialisering kan du prova att exportera några av dina egna dashboards.

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, vilket är för en AI/BI-instrumentpanel. Filnamnet, som det visas på arbetsytan, föregår tillägget. I det här fallet är det mydashboard.

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

Not

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,
  "format": "AUTO"
}

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

Koda den exporterade filen

Följande kod visar ett exempelsvar där egenskapen "direct_download" ä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 Workspace Import API POST /api/2.0/workspace/import för att importera utkast till instrumentpaneler i 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 AI/BI-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".

Viktig

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 egenskapen "overwrite" 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 AI/BI-instrumentpanel. Se GET /api/2.0/workspace/get-status.

Följande exempel visar en get-status begäran för 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 de föregående exemplen användes API:et För arbetsytor, vilket aktiverade arbete med AI/BI-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 AI/BI-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 för begäran anges "embed_credentials" till true så att utgivarens inloggningsuppgifter bäddas in i 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 lagerhus 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 din publicerade instrumentpanel.

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 egenskapen "resource_id" som du identifierade i hämta metadata.

Steg 7: Ta bort en instrumentpanel

För att ta bort en instrumentpanel, använd arbetsytans API. Se POST /api/2.0/workspace/delete.

Viktig

Det här är en svår borttagning. När kommandot har slutförts tas instrumentpanelen bort permanent.

I följande exempel innehåller begäran sökvägen till filen som skapades i föregående steg.

POST /api/2.0/workspace/delete

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

Response:
{}

Nästa steg