Tutoriel : Gérer des tableaux de bord avec les API Espace de travail

Ce tutoriel montre comment gérer des tableaux de bord en utilisant l’API Lakeview et l’API Espace de travail. Chaque étape comprend un exemple de requête et de réponse ainsi que des explications sur la façon d’utiliser ensemble les outils et les propriétés des API. Chaque étape peut être référencée de façon indépendante. Le fait de suivre toutes les étapes dans l’ordre vous permet d’être guidé tout au long d’un workflow complet.

Remarque

Ce workflow appelle l’API Espace de travail pour récupérer un tableau de bord Lakeview en tant qu’objet d’espace de travail générique.

Prérequis

• Vous avez besoin d’un jeton d’accès personnel pour vous connecter à votre espace de travail. Consultez Authentification à l’aide de jetons d’accès personnels Azure Databricks.
• Vous avez besoin de l’ID d’espace de travail de l’espace de travail auquel vous souhaitez accéder. Consultez Noms d’instance, URL et ID d’espace de travail
• Connaissance des Informations de référence sur l’API REST Databricks.

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

L’API servant à lister les espaces de travail GET /api/2.0/workspace/list vous permet d’explorer la structure des répertoires 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 propriété path de la requête pointe vers un dossier nommé examples_folder, stocké dans le dossier de base 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 tableau de bord 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"
    }
  ]
}

Étape 2 : Exporter un tableau de bord

L’API servant à exporter un espace de travail GET /api/2.0/workspace/export vous permet d’exporter le contenu d’un tableau de bord sous forme de fichier. Les fichiers de tableau de bord Lakeview 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 découvrir et comprendre plus de détails sur la 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 en utilisant l’API.

La propriété "path" de cet exemple finit par l’extension de type de fichier lvdash.json, un tableau de bord Lakeview. 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 mydashboard.

De plus, la propriété "direct_download" de cette requête a la valeur true, ce qui signifie que la réponse correspond au fichier exporté lui-même.

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

Response:
{
  "pages": [
    {
      "name": "880de22a",
      "displayName": "New Page"
    }
  ]
}

Coder le fichier exporté

Le code suivant montre un exemple de réponse où la propriété "direct_download" a la valeur false. La réponse comporte du contenu sous forme de chaîne codée au format 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 servant à importer un espace de travail POST /api/2.0/workspace/import pour importer des brouillons de tableaux de bord dans un espace de travail. Par exemple, une fois que vous avez exporté un fichier codé, 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 en tant que tableau de bord Lakeview, 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 de fichier qui finit par « .lvdash.json ».

Important

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 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 : Remplacer à l’importation (facultatif)

Toute tentative de réémission 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 plutôt remplacer la requête dupliquée, affectez la valeur true à la propriété "overwrite", 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 d’espace de travail, notamment un tableau de bord Lakeview. Consultez GET /api/2.0/workspace/get-status.

L’exemple suivant montre une requête get-status pour le tableau de bord importé à partir de l’exemple précédent. La réponse comprend des détails indiquant que le fichier a été correctement importé en tant que "DASHBOARD". Elle comprend également une propriété "resource_id" que vous pouvez utiliser en tant qu’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 ont utilisé l’API Espace de travail, ce qui a permis d’utiliser des tableaux de bord Lakeview 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 Lakeview. Consultez POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Le chemin du point de terminaison d’API comprend la propriété "resource_id" retournée dans l’exemple précédent. Dans les paramètres de requête, "embed_credentials" a la valeur true pour que les informations d’identification de l’éditeur soient incorporées dans le tableau de bord. L’éditeur, dans le cas présent, est l’utilisateur qui effectue la requête d’API autorisée. L’éditeur ne peut pas incorporer les informations d’identification d’autres utilisateurs. Consultez Publier un tableau de bord pour découvrir le fonctionnement du paramètre Incorporer des informations d’identification.

La propriété "warehouse_id" définit l’entrepôt à utiliser pour le tableau de bord publié. Si elle est spécifiée, cette propriété remplace l’entrepôt indiqué pour le brouillon de tableau de bord, 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 à partir de votre navigateur, une fois que la commande a fini de s’exécuter. L’exemple suivant montre comment créer le lien vers votre tableau de bord publié.

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

Pour créer votre lien unique :

• Remplacez <deployment-url> par votre URL de déploiement. Ce lien est l’adresse figurant dans la barre d’adresse du navigateur quand 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.

Important

Il s’agit d’une suppression définitive. À la fin de l’exécution de la commande, le tableau de bord est supprimé de manière définitive.

Dans l’exemple suivant, la requête inclut le chemin du 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

• Pour en savoir plus sur les tableaux de bord, consultez Tableaux de bord.
• Pour en savoir plus sur l’API REST, consultez les Informations de référence sur l’API REST Databricks.