Condividi tramite

Gestire i dashboard con le API dell'area di lavoro

  • Articolo

Questa esercitazione illustra come gestire i dashboard usando l'API Lakeview e l'API Workspace. Ogni passaggio include una richiesta e una risposta di esempio e spiegazioni su come usare insieme gli strumenti e le proprietà dell'API. A ogni passaggio è possibile fare riferimento autonomamente. Seguire tutti i passaggi nell'ordine ti guida attraverso un flusso di lavoro completo.

Nota

Questo flusso di lavoro chiama l'API dell'area di lavoro per recuperare un dashboard AI/BI come oggetto generico dell'area di lavoro. I dashboard di intelligenza artificiale/BI erano precedentemente noti come dashboard di Lakeview. L'API Lakeview mantiene tale nome.

Prerequisiti

  • È necessario un token di accesso personale per connettersi all'area di lavoro. Vedi l'autenticazione tramite token di accesso personale di Azure Databricks .
  • È necessario l'ID dell'area di lavoro a cui si vuole accedere. Vedere nomi delle istanze dell'area di lavoro, URL e ID
  • Familiarità con il riferimento dell'API REST di Databricks.

Passaggio 1: Esplorare una directory dell'area di lavoro

L'API Elenco delle aree di lavoro GET /api/2.0/workspace/list consente di esplorare la struttura delle directory dell'area di lavoro. Ad esempio, è possibile recuperare un elenco di tutti i file e le directory nell'area di lavoro corrente.

Nell'esempio seguente la proprietà path nella richiesta punta a una cartella denominata examples_folder archiviata nella home folder di un utente. Il nome utente viene fornito nel percorso first.last@example.com.

La risposta mostra che la cartella contiene un file di testo, una directory e un dashboard di intelligenza artificiale/BI.

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

Passaggio 2: Esportare un dashboard

L'API di esportazione dell'area di lavoro GET /api/2.0/workspace/export consente di esportare il contenuto di un dashboard come file. I file del dashboard di intelligenza artificiale/BI riflettono la versione bozza di un dashboard. La risposta negli esempi seguenti mostra il contenuto di una definizione minima del dashboard. Per esplorare e comprendere altri dettagli di serializzazione, prova a esportare alcuni dei tuoi dashboard.

Scaricare il file esportato

L'esempio seguente illustra come scaricare un file del dashboard usando l'API.

La proprietà "path" in questo esempio termina con l'estensione del tipo di file lvdash.json, un dashboard di intelligenza artificiale/BI. Il nome file, come appare nell'area di lavoro, precede tale estensione. In questo caso, è mydashboard.

Inoltre, la proprietà "direct_download" per questa richiesta è impostata su true in modo che la risposta sia il file esportato stesso e la proprietà "format" sia impostata su "AUTO".

Nota

La proprietà "displayName", visualizzata nella proprietà pages della risposta, non riflette il nome visibile del dashboard nell'area di lavoro.

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

Codificare il file esportato

Il codice seguente mostra una risposta di esempio in cui "direct_download" proprietà è impostata su false. La risposta contiene contenuto come stringa con codifica Base64.

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

Passaggio 3: Importare un dashboard

È possibile usare l'API di importazione dell'area di lavoro POST /api/2.0/workspace/import per importare i dashboard in bozza in un'area di lavoro. Ad esempio, dopo aver esportato un file codificato, come nell'esempio precedente, è possibile importare tale dashboard in una nuova area di lavoro.

Affinché un'importazione venga riconosciuta come dashboard di intelligenza artificiale/BI, è necessario impostare due parametri:

  • "format": "AUTO" - questa impostazione consentirà al sistema di rilevare automaticamente il tipo di asset.
  • "path": deve includere un percorso di file che termina con ".lvdash.json".

Importante

Se queste impostazioni non sono configurate correttamente, l'importazione potrebbe avere esito positivo, ma il dashboard verrà considerato come un file normale.

L'esempio seguente mostra una richiesta di importazione configurata correttamente.


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

Passaggio 4: Sovrascrittura all'importazione (facoltativo)

Il tentativo di eseguire nuovamente la stessa richiesta API genera l'errore seguente:

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

Se invece si desidera sovrascrivere la richiesta duplicata, impostare la proprietà "overwrite" su true come nell'esempio seguente.


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

Passaggio 5: Recuperare i metadati

È possibile recuperare i metadati per qualsiasi oggetto dell'area di lavoro, incluso un dashboard di intelligenza artificiale/BI. Vedere GET /api/2.0/workspace/get-status.

L'esempio seguente mostra una richiesta di get-status per il dashboard importato dall'esempio precedente. La risposta include dettagli che confermano che il file è stato importato correttamente come "DASHBOARD". Inoltre, è costituita da una proprietà "resource_id" che è possibile usare come identificatore con l'API Lakeview.

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

Passaggio 6: Pubblicare un dashboard

Negli esempi precedenti è stata usata l'API Workspace, abilitando l'uso di dashboard di intelligenza artificiale/BI come oggetti di area di lavoro generici. L'esempio seguente usa l'API Lakeview per eseguire un'operazione di pubblicazione specifica per i dashboard di intelligenza artificiale/BI. Vedere POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Il percorso dell'endpoint API include la proprietà "resource_id" restituita nell'esempio precedente. Nei parametri della richiesta "embed_credentials" è impostato su true in modo che le credenziali dell'editore siano incorporate nel dashboard. L'editore, in questo caso, è l'utente che effettua la richiesta API autorizzata. Il pubblicatore non può incorporare le credenziali di utenti diversi. Consulta Pubblica un dashboard per sapere come funziona l'impostazione delle credenziali di incorporamento .

L'attributo "warehouse_id" definisce il magazzino destinato al dashboard pubblicato. Se viene specificato, questa proprietà sovrascrive il magazzino specificato per la bozza del dashboard, se presente.

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

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

Response:
{}

Al termine del comando, è possibile accedere al dashboard pubblicato tramite il browser. L'esempio seguente illustra come creare il collegamento al dashboard pubblicato.

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

Per costruire il tuo link univoco:

  • Sostituire <deployment-url> con l'URL di distribuzione. Questo collegamento è l'indirizzo nella barra degli indirizzi del browser quando ci si trova nella home page dell'area di lavoro di Azure Databricks.
  • Sostituire <resource_id> con il valore della proprietà "resource_id" identificata in recuperare i metadati.

Passaggio 7: Eliminare un dashboard

Per eliminare un dashboard, usare l'API dell'area di lavoro. Vedere POST /api/2.0/workspace/delete.

Importante

Si tratta di un'eliminazione difficile. Al termine del comando, il dashboard viene eliminato definitivamente.

Nell'esempio seguente la richiesta include il percorso del file creato nei passaggi precedenti.

POST /api/2.0/workspace/delete

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

Response:
{}

Passaggi successivi