Share via

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. Seguendo tutti i passaggi nell'ordine viene illustrato un flusso di lavoro completo.

Nota

Questo flusso di lavoro chiama l'API workspace per recuperare un dashboard Lakeview come oggetto area di lavoro generica.

Prerequisiti

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 Lakeview.

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 Lakeview 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.jsondel tipo di file , un dashboard Lakeview. 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 Lakeview, è 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 lakeview. 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 dei dashboard di Lakeview 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 Lakeview. 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