Gérer un lakehouse dans Microsoft Fabric avec l’API REST

Article
09/05/2024

L’API REST de Microsoft Fabric fournit un point de terminaison de service pour l’opération CRUD d’un élément Fabric. Les actions suivantes sont disponibles pour le lakehouse :

Action	Description
Création	Crée un lakehouse à l’intérieur d’un espace de travail. Un point de terminaison d’analytique SQL est également approvisionné avec le lakehouse.
Mettre à jour	Met à jour le nom d’un lakehouse et le point de terminaison d’analytique SQL.
Supprimer	Supprime le lakehouse et le point de terminaison d’analytique SQL associé.
Obtenir des propriétés	Obtient les propriétés d’un lakehouse et le point de terminaison d’analytique SQL.
Lister des tables	Répertoriez les tables dans le lakehouse.
Chargement de table	Crée des tables delta à partir des dossiers et fichiers CSV et Parquet.
Maintenance de table	Appliquer le compactage bin, V-Order et la suppression de fichiers anciens et non référencés.

Prérequis

Pour utiliser l’API REST Fabric, vous devez d’abord obtenir un jeton Microsoft Entra pour le service Fabric. Utilisez ensuite ce jeton dans l’en-tête d’autorisation de l’appel d’API.
L’API REST de Microsoft Fabric définit un point de terminaison unifié pour les opérations. Le point de terminaison a la valeur https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items. Les espaces réservés {workspaceId} et {lakehouseId} doivent être remplacés par les valeurs appropriées lors de l’émission des commandes illustrées dans cet article.

CRUD lakehouse

Utilisez l’API suivante pour créer, modifier et supprimer le lakehouse à l’intérieur d’un espace de travail.

Créer un lakehouse.

Demande :

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items 
{ 
    "displayName": "demo", 
    "type": "Lakehouse" 
}

Réponse :

{
    "id": "56c6dedf-2640-43cb-a412-84faad8ad648", 
    "type": "Lakehouse", 
    "displayName": "demo", 
    "description": "", 
    "workspaceId": "fc67689a-442e-4d14-b3f8-085076f2f92f" 
}

Mettre à jour un lakehouse

Mettez à jour la description et renommez le lakehouse.

Demande :

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/dc39f96a-47d7-4c2d-9358-740f50c0aa31 
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
}

Réponse :

{ 
    "id": "56c6dedf-2640-43cb-a412-84faad8ad648", 
    "type": "Lakehouse", 
    "displayName": "newname", 
    "description": "", 
    "workspaceId": "fc67689a-442e-4d14-b3f8-085076f2f92f" 
}

Obtenir les propriétés du lakehouse

Demande :

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}

Réponse :

{ 
    "id": "daaa77c7-9ef4-41fc-ad3c-f192604424f5", 
    "type": "Lakehouse", 
    "displayName": "demo", 
    "description": "", 
    "workspaceId": "bee6c118-c2aa-4900-9311-51546433bbb8", 
    "properties": { 
        "oneLakeTablesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{lakehouseId}/Tables", 
        "oneLakeFilesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{lakehouseId}/Files", 
        "sqlEndpointProperties": { 
            "connectionString": "A1bC2dE3fH4iJ5kL6mN7oP8qR9-C2dE3fH4iJ5kL6mN7oP8qR9sT0uV-datawarehouse.pbidedicated.windows.net", 
            "id": "0dfbd45a-2c4b-4f91-920a-0bb367826479", 
            "provisioningStatus": "Success" 
        } 
    } 
}

Supprimer un lakehouse

Lorsque vous supprimez un lakehouse, les métadonnées et données de l’objet sont supprimées. Les références de raccourci sont supprimées, mais les données sont conservées dans la cible.

Demande :

DELETE https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}

Réponse: vide

Répertorier les tables dans un lakehouse

Demande :

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables

Réponse :

{ 
    "continuationToken": null, 
    "continuationUri": null, 
    "data": [ 
        { 
            "type": "Managed", 
            "name": "demo1", 
            "location": "abfss://c522396d-7ac8-435d-8d77-442c3ff21295@onelake.dfs.fabric.microsoft.com/{workspaceId}/Tables/demo1", 
            "format": "delta" 
        } 
    ] 
}

L’API pour répertorier les tables prend en charge la pagination. Fournissez les maxResults par page en tant que paramètre pour la requête et l’API répond avec l’URI de continuation qui peut être utilisé pour obtenir la page de résultats suivante.

Exemple de pagination

Demande :

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables?maxResults=1

Réponse :

{ 
    "continuationToken": "+RID:~HTsuAOseYicH-GcAAAAAAA==#RT:1#TRC:1#ISV:2#IEO:65567#QCF:8#FPC:AgKfAZ8BnwEEAAe8eoA=", 
    "continuationUri": "https://api.fabric.microsoft.com:443/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables?continuationToken=%2BRID%3A~HTsuAOseYicH-GcAAAAAAA%3D%3D%23RT%3A1%23TRC%3A1%23ISV%3A2%23IEO%3A65567%23QCF%3A8%23FPC%3AAgKfAZ8BnwEEAAe8eoA%3D", 
    "data": [ 
        { 
            "type": "Managed", 
            "name": "nyctaxismall", 
            "location": "abfss://bee6c118-c2aa-4900-9311-51546433bbb8@onelake.dfs.fabric.microsoft.com/daaa77c7-9ef4-41fc-ad3c-f192604424f5/Tables/nyctaxismall", 
            "format": "delta" 
        } 
    ] 
}

Charger dans des tables

Cette API expose les capacités de la fonctionnalité lakehouse Chargement dans des tables. Cette API permet de charger des fichiers CSV et parquet dans des tables delta lake nouvelles ou existantes dans le lakehouse.

Cette API est asynchrone, donc trois étapes sont requises :

Chargez des fichiers et dossiers dans la section Fichiers du lakehouse à l’aide des API OneLake.
Envoyez la requête d’API de chargement dans des tables.
Surveillez l’état de l’opération jusqu’à son achèvement.

Les sections suivantes supposent que les fichiers sont déjà chargés.

Requête d’API de chargement dans des tables

Le paramètre mode prend en charge les opérations overwrite et append. Le paramètre pathType est spécifié si vous chargez des fichiers individuels ou tous les fichiers du dossier spécifié. CSV et parquet sont pris en charge en tant que paramètre format du fichier.

Cet exemple charge un fichier CSV nommé demo.csv dans une table existante nommée demo.

Demande :

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables/demo/load 
{ 
    "relativePath": "Files/demo.csv", 
    "pathType": "File", 
    "mode": "overwrite", 
    "formatOptions": 
    { 
        "header": true, 
        "delimiter": ",", 
        "format": "CSV" 
    } 
}

L’en-tête de réponse contient l’URI utilisé pour interroger l’état des opérations asynchrones. L’URI se trouve dans la variable Emplacement de l’en-tête de réponse.

La variable Emplacement contient un URI comme suit : https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/32ad6d2a-82bb-420d-bb57-4620c8860373. Le guid 32ad6d2a-82bb-420d-bb57-4620c8860373 est l’ID d’opération pour interroger l’état de la charge en cours d’exécution sur les opérations de tables, tel que décrit dans la section suivante.

Analyse des opérations de chargement dans des tables

Une fois l’operationId capturé dans la réponse de la requête d’API de chargement dans des tables, exécutez la requête suivante :

Demande :

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/{operationId}

Réponse :

{ 
    "Status": 3, 
    "CreatedTimeUtc": "", 
    "LastUpdatedTimeUtc": "", 
    "PercentComplete": 100, 
    "Error": null 
}

État potentiel de l’opération pour le chargement dans des tables :

1 - Opération non démarrée
2 - Exécution en cours
3 - Réussite
4 - Échec

Maintenance de table

Cette API surface les capacités de la fonctionnalité de maintenance de table du lakehouse. Cette API permet d’appliquer le compactage bin, V-Order et le nettoyage de fichiers anciens non référencés.

Cette API est asynchrone, donc deux étapes sont requises :

Envoyez une requête d’API de maintenance de table.
Surveillez l’état de l’opération jusqu’à son achèvement.

Requête d’API de maintenance de table

Cet exemple exécute une tâche de maintenance de table qui applique V-Order à une table, tout en appliquant Z-Order à la colonne tipAmount et en exécutant l’opération VACUUM avec une rétention de sept jours et une heure.

Demande :

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances?jobType=TableMaintenance
{
    "executionData": {
        "tableName": "{table_name}",
        "optimizeSettings": {
            "vOrder": true,
            "zOrderBy": [
                "tipAmount"
            ]
        },
        "vacuumSettings": {
            "retentionPeriod": "7.01:00:00"
        }
    }
}

L’en-tête de réponse contient l’URI utilisé pour interroger l’état des opérations asynchrones. L’URI se trouve dans la variable Emplacement de l’en-tête de réponse.

La variable Emplacement contient un URI comme suit : https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b. Le guid f2d65699-dd22-4889-980c-15226deb0e1b est l’ID d’opération pour interroger l’état des opérations de maintenance de table en cours, tel que décrit dans la section suivante.

Analyse des opérations de maintenance de tables

Une fois l’operationId capturé dans la réponse de la requête d’API de chargement dans des tables, exécutez la requête suivante :

Demande :

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{operationId}

Réponse :

{
    "parameters": {
        "workspaceId": "{workspaceId}",
        "itemId": "{lakehouseId}",
        "jobInstanceId": "{operationId}"
    },
    "responses": {
        "200": {
            "body": {
                "id": "{operationId}",
                "itemId": "431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7",
                "jobType": "DefaultJob",
                "invokeType": "Manual",
                "status": "Completed",
                "rootActivityId": "8c2ee553-53a4-7edb-1042-0d8189a9e0ca",
                "startTimeUtc": "2023-04-22T06:35:00.7812154",
                "endTimeUtc": "2023-04-22T06:35:00.8033333",
                "failureReason": null
            }
        }
    }
}

État potentiel de l’opération pour la maintenance de table :

NotStarted - Tâche non démarrée
InProgress - Tâche en cours
Completed - Tâche terminée
Failed - Échec de tâche
Canceled - Tâche annulée
Deduped - Une instance du même type de tâche est déjà en cours d’exécution et cette instance de tâche est ignorée

Fonctionnalité lakehouse Chargement dans des tables.
Utilisez la fonctionnalité de maintenance de table pour gérer les tables delta dans Fabric.
Optimisation de table Delta Lake et V-Order.

Partager via

Gérer un lakehouse dans Microsoft Fabric avec l’API REST

Prérequis

CRUD lakehouse

Créer un lakehouse.

Mettre à jour un lakehouse

Obtenir les propriétés du lakehouse

Supprimer un lakehouse

Répertorier les tables dans un lakehouse

Charger dans des tables

Requête d’API de chargement dans des tables

Analyse des opérations de chargement dans des tables

Maintenance de table

Requête d’API de maintenance de table

Analyse des opérations de maintenance de tables

Commentaires

Ressources supplémentaires

Partager via

Gérer un lakehouse dans Microsoft Fabric avec l’API REST

Prérequis

CRUD lakehouse

Créer un lakehouse.

Mettre à jour un lakehouse

Obtenir les propriétés du lakehouse

Supprimer un lakehouse

Répertorier les tables dans un lakehouse

Exemple de pagination

Charger dans des tables

Requête d’API de chargement dans des tables

Analyse des opérations de chargement dans des tables

Maintenance de table

Requête d’API de maintenance de table

Analyse des opérations de maintenance de tables

Contenu connexe

Commentaires

Ressources supplémentaires