Partager via

Gérer les tableaux de bord avec des API d’espace de travail

Ce tutoriel montre comment gérer des tableaux de bord à l’aide de l’API Lakeview et de l’API Espace de travail. Chaque étape inclut un exemple de demande et de réponse, ainsi que des explications sur l’utilisation des outils et propriétés de l’API ensemble. Chaque étape peut être référencée par elle-même. Suivre toutes les étapes dans l’ordre vous guide tout au long d’un flux de travail complet.

Remarque

Ce flux de travail appelle l’API Espace de travail pour récupérer un tableau de bord IA/BI en tant qu’objet d’espace de travail générique. Les tableaux de bord IA/BI étaient précédemment appelés tableaux de bord Lakeview. L’API Lakeview conserve ce nom.

Prérequis

Étape 1 : Explorer un répertoire d’espace de travail

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

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

La réponse indique que le dossier contient un fichier texte, un répertoire et un tableau de bord IA/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"
    }
  ]
}

Étape 2 : Exporter un tableau de bord

L’API d’exportation d’espace de travail GET /api/2.0/workspace/export vous permet d’exporter le contenu d’un tableau de bord en tant que fichier. Les fichiers de tableau de bord IA/BI 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 de sérialisation, essayez d’exporter certains de vos propres tableaux de bord.

Télécharger le fichier exporté

L’exemple suivant montre comment télécharger 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 tableau de bord IA/BI. Le nom de fichier, tel qu’il apparaît dans l’espace de travail, précède cette extension. Dans ce cas, il s’agit de vmoracle19cVMNic.

En outre, 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é des pages de la réponse, ne reflète pas le nom visible du tableau de bord dans l’espace de travail.

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

Encoder le fichier exporté

Le code suivant montre un exemple de réponse où "direct_download" propriété a la valeur false. La réponse contient du 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 d’espace de travail POST /api/2.0/workspace/import pour importer des tableaux de bord brouillons dans un espace de travail. 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 nouvel espace de travail.

Pour qu’une importation soit reconnue comme tableau de bord IA/BI, deux paramètres doivent être définis :

  • "format": « AUTO » : ce paramètre permet au système de détecter automatiquement le type de ressource.
  • "path": doit inclure un chemin d’accès de fichier qui se termine par «.lvdash.json».

Essentiel

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

L’exemple suivant montre une demande 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 : Remplacer lors de l’importation (facultatif)

La tentative de réédition de la même requête d’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 dupliquée à 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 des métadonnées pour n’importe quel objet d’espace de travail, y compris un tableau de bord IA/BI. Consultez GET /api/2.0/workspace/get-status.

L’exemple suivant montre une demande de get-status pour le tableau de bord importé à partir de l’exemple précédent. La réponse inclut des détails indiquant que le fichier a été importé avec succès en tant que "DASHBOARD". En outre, il se compose d’une propriété "resource_id" que vous pouvez utiliser comme identificateur 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 Espace de travail, ce qui permet d’utiliser des tableaux de bord IA/BI en tant qu’objets d’espace de travail génériques. L’exemple suivant utilise l’API Lakeview pour effectuer une opération de publication spécifique aux tableaux de bord IA/BI. Consultez POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Le chemin d’accès au point de terminaison d’API inclut la propriété "resource_id" retournée dans l’exemple précédent. Dans les paramètres de requête, "embed_credentials" est défini à true afin que les informations d’identification de l’éditeur soient incorporées dans le tableau de bord. Dans ce cas, l’éditeur est l’utilisateur qui effectue la demande d’API autorisée. L’éditeur ne peut pas incorporer les informations d’identification d’un utilisateur différent. Consultez Publier un tableau de bord pour découvrir comment fonctionne le paramètre Partager avec des autorisations de données .

La propriété "warehouse_id" définit l’entrepôt à utiliser pour le tableau de bord publié. Si celle-ci est spécifiée, cette propriété remplace l’entrepôt spécifié pour le tableau de bord brouillon, si applicable.

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

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

Response:
{}

Le tableau de bord publié est accessible à partir de votre navigateur lorsque la commande est terminée. L’exemple suivant montre comment construire le lien vers votre tableau de bord publié.

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

Pour construire votre lien unique :

  • Remplacez <deployment-url> par votre URL de déploiement. Ce lien est l’adresse de votre barre d’adresses de navigateur lorsque vous êtes sur votre page d’accueil de l’espace de travail Azure 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 Espace de travail. Consultez POST /api/2.0/workspace/delete.

Essentiel

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

Dans l’exemple suivant, la requête inclut le chemin d’accès au fichier créé dans les é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

  • Last updated on