Aller au contenu principal
Dernière mise à jour le

Gérer les tableaux de bord avec les APIs Workspace

Ce tutoriel montre comment gérer les tableaux de bord à l’aide de l’API Lakeview et de l’API Workspace. Chaque étape comprend un exemple de requête et de réponse, ainsi que des explications sur la façon d’utiliser les outils et les propriétés de l’API ensemble. Chaque étape peut être référencée séparément. Suivre toutes les étapes dans l’ordre vous guide à travers un workflow complet.

remarque

Ce workflow appelle l'API Workspace pour récupérer un AI/BI dashboard en tant qu'objet Workspace générique. Les tableaux de bord AI/BI étaient auparavant connus sous le nom de tableaux de bord Lakeview. L'API Lakeview conserve ce nom.

Prérequis​

Étape 1 : Explorer un répertoire Workspace​

L'API Workspace List GET /api/2.0/workspace/list vous permet d’explorer la structure de répertoires de votre workspace. Par exemple, vous pouvez récupérer une liste de tous les fichiers et répertoires dans votre Workspace actuel.

Dans l'exemple suivant, la propriété path de la requête pointe vers un dossier nommé examples_folder stocké dans le dossier personnel d'un utilisateur. Le nom d’utilisateur est fourni dans le chemin, first.last@example.com.

La réponse montre que le dossier contient un fichier texte, un répertoire et un AI/BI dashboard.

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

Étape 2 : Exporter un tableau de bord​

L'API d'exportation Workspace GET /api/2.0/workspace/export vous permet d'exporter le contenu d'un tableau de bord sous forme de fichier. Les fichiers AI/BI dashboard reflètent la version brouillon d'un tableau de bord. La réponse dans les exemples suivants montre le contenu d'une définition de tableau de bord minimale. Pour explorer et comprendre plus de détails sur la sérialisation, essayez d'exporter certains de vos propres tableaux de bord.

Download le fichier exporté​

L'exemple suivant montre comment download un fichier de tableau de bord à l'aide de l'API.

La propriété "path" dans cet exemple se termine par l'extension de type de fichier lvdash.json, un AI/BI dashboard. Le nom de fichier, tel qu'il apparaît dans le Workspace, précède cette extension. Dans ce cas, c'est mydashboard.

De plus, la propriété "direct_download" pour cette requête est définie sur true afin que la réponse soit le fichier exporté lui-même, et la propriété "format" est définie sur "AUTO".

remarque

La propriété "displayName", affichée dans la propriété « pages » de la réponse, ne reflète pas le nom visible du tableau de bord dans le Workspace.

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

Encodez le fichier exporté​

Le code suivant montre un exemple de réponse où la propriété "direct_download" est définie sur faux. La réponse contient le contenu sous forme de chaîne encodée en 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"
}

Étape 3 : importer un tableau de bord​

Vous pouvez utiliser l'API d'importation de Workspace POST /api/2.0/workspace/import pour importer des tableaux de bord brouillons dans un Workspace. Par exemple, après avoir exporté un fichier encodé, comme dans l’exemple précédent, vous pouvez importer ce tableau de bord dans un nouveau workspace.

Pour qu'une importation soit reconnue comme un AI/BI dashboard, deux parameters doivent être définis :

  • "format": « AUTO » - ce paramètre permettra au système de détecter automatiquement le type d'asset.
  • "path": doit inclure un chemin de fichier qui se termine par « .lvdash.json ».
important

Si ces paramètres ne sont pas configurés correctement, l'importation peut réussir, mais le tableau de bord serait traité comme un fichier normal.

L'exemple suivant montre une requête d'importation correctement configurée.


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

Étape 4 : Écrasement à l'importation (Facultatif)​

Toute tentative de réémission de la même requête API entraîne l’erreur suivante :

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

Si vous souhaitez remplacer la requête en double à la place, définissez la propriété "overwrite" sur true comme dans l'exemple suivant.


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

Étape 5 : Récupérer les métadonnées​

Vous pouvez récupérer les métadonnées de n'importe quel objet du workspace, y compris un AI/BI dashboard. Consultez GET /api/2.0/workspace/get-status.

L'exemple suivant montre une requête get-status pour le tableau de bord importé de l'exemple précédent. La réponse inclut des détails confirmant que le fichier a été importé avec succès en tant que "DASHBOARD". De plus, il se compose d'une propriété "resource_id" que vous pouvez utiliser comme identifiant avec 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"
}

Étape 6 : Publier un tableau de bord.​

Les exemples précédents utilisaient l'API Workspace, permettant de travailler avec les tableaux de bord AI/BI en tant qu'objets workspace génériques. L’exemple suivant utilise l’API Lakeview pour effectuer une opération de publication spécifique aux tableaux de bord AI/BI. Voir POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Le chemin d'accès à l'Endpoint API inclut la propriété "resource_id" renvoyée dans l'exemple précédent. Dans les parameters de requête, "embed_credentials" est défini sur true afin que les informations d'identification de l'éditeur soient intégrées au tableau de bord. L'éditeur, dans ce cas, est l'utilisateur qui effectue la demande d'API autorisée. L'éditeur ne peut pas intégrer les identifiants d'utilisateurs différents. Consultez Publier un tableau de bord pour savoir comment fonctionne le paramètre « Partager avec les autorisations de données ».

La propriété "warehouse_id" définit le warehouse à utiliser pour le tableau de bord publié. Si spécifiée, cette propriété remplace le warehouse spécifié pour le tableau de bord brouillon, le cas échéant.

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

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

Response:
{}

Le tableau de bord publié est accessible depuis votre navigateur une fois la commande terminée. L'exemple suivant montre comment construire le Link vers votre tableau de bord publié.

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

Pour construire votre Link unique :

  • Remplacez <deployment-url> par votre URL de déploiement. Ce Link est l’adresse figurant dans la barre d’adresse de votre navigateur lorsque vous êtes sur la page d’accueil de votre Workspace Databricks.
  • Remplacez <resource_id> par la valeur de la propriété "resource_id" que vous avez identifiée dans récupérer les métadonnées.

Étape 7 : Supprimer un tableau de bord​

Pour supprimer un tableau de bord, utilisez l'API Workspace. Voir POST /api/2.0/workspace/delete.

important

Il s'agit d'une suppression définitive. Lorsque la commande est terminée, le tableau de bord est supprimé définitivement.

Dans l'exemple suivant, la requête inclut le chemin d'accès au fichier créé aux étapes précédentes.

POST /api/2.0/workspace/delete

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

Response:
{}

Étapes suivantes​

Sur cette page