Gestire i dashboard con le API dell'area di lavoro
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. Seguendo tutti i passaggi nell'ordine viene illustrato un flusso di lavoro completo.
Nota
Questo flusso di lavoro chiama l'API dell'area di lavoro per recuperare un dashboard di intelligenza artificiale/BI come oggetto area di lavoro generica.
Prerequisiti
- È necessario un token di accesso personale per connettersi all'area di lavoro. Vedere Autenticazione del token di accesso personale di Azure Databricks.
- È necessario l'ID area di lavoro dell'area di lavoro a cui si vuole accedere. Vedere Nomi, URL e ID dell'istanza dell'area di lavoro
- Familiarità con le informazioni di riferimento sull'API REST di Databricks.
Passaggio 1: Esplorare una directory dell'area di lavoro
L'API dell'elenco di aree di lavoro GET /api/2.0/workspace/list consente di esplorare la struttura di 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 path
proprietà 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, provare a esportare alcuni dashboard personalizzati.
Scaricare il file esportato
L'esempio seguente illustra come scaricare un file del dashboard usando l'API.
La "path"
proprietà in questo esempio termina con l'estensione lvdash.json
del tipo di file , un dashboard di intelligenza artificiale/BI. Il nome file, come appare nell'area di lavoro, precede tale estensione. In questo caso, è mydashboard
.
Inoltre, la "direct_download"
proprietà per questa richiesta è impostata su true
in modo che la risposta sia il file esportato stesso.
Nota
La "displayName"
proprietà, 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
}
Response:
{
"pages": [
{
"name": "880de22a",
"displayName": "New Page"
}
]
}
Codificare il file esportato
Il codice seguente mostra una risposta di esempio in cui "direct_download"
la 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 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: Sovrascrivere 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 "overwrite"
proprietà 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.
Nell'esempio seguente viene illustrata una get-status
richiesta per il dashboard importato dell'esempio precedente. La risposta include dettagli che confermano che il file è stato importato correttamente come "DASHBOARD"
. È inoltre costituita da una "resource_id"
proprietà 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 "resource_id"
proprietà restituita nell'esempio precedente. Nei parametri "embed_credentials"
della richiesta è impostato su true
in modo che le credenziali dell'editore siano incorporate nel dashboard. L'autore, in questo caso, è l'utente che effettua la richiesta API autorizzata. Il server di pubblicazione non può incorporare credenziali dell'utente diverso. Per informazioni sul funzionamento dell'impostazione Incorpora credenziali, vedere Pubblicare un dashboard.
La "warehouse_id"
proprietà imposta il magazzino da utilizzare per il dashboard pubblicato. Se specificato, questa proprietà esegue l'override del magazzino specificato per il dashboard bozza, 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 dal browser. L'esempio seguente illustra come costruire il collegamento al dashboard pubblicato.
https://<deployment-url>/dashboardsv3/<resource_id>/published
Per costruire il collegamento 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"resource_id"
proprietà identificata nei metadati di recupero.
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
- Per altre informazioni sui dashboard, vedere Dashboard.
- Per altre informazioni sull'API REST, vedere Informazioni di riferimento sull'API REST di Databricks.