Partager via

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

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. Pour obtenir des exemples détaillés de paramètres d’API et de requête, consultez la documentation sur l’API REST Create Lakehouse.

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/aaaabbbb-0000-cccc-1111-dddd2222eeee 
{ 
    "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 :

  1. Chargez des fichiers et dossiers dans la section Fichiers du lakehouse à l’aide des API OneLake.
  2. Envoyez la requête d’API de chargement dans des tables.
  3. 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/bbbbcccc-1111-dddd-2222-eeee3333ffff. Le guid bbbbcccc-1111-dddd-2222-eeee3333ffff 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. Avec cette API, il est possible d'appliquer le compactage de bin, V-Order, et le nettoyage des anciens fichiers non référencés (vidange).

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

  1. Envoyez une requête d’API de maintenance de table.
  2. 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}",
        "schemaName": "{schema_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/ccccdddd-2222-eeee-3333-ffff4444aaaa. Le guid ccccdddd-2222-eeee-3333-ffff4444aaaa 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.

Important

La définition d’une période de rétention plus courte a un impact sur les fonctionnalités de voyage temporel de Delta. Il est recommandé de définir un intervalle de rétention sur au moins sept jours, car les anciens instantanés et les fichiers non validés peuvent toujours être utilisés par les lecteurs de table et les enregistreurs simultanés. Le nettoyage des fichiers actifs avec la commande VACUUM peut entraîner des échecs de lecture ou même une altération de la table si les fichiers non validés sont supprimés. Les expériences de maintenance de table dans l’interface utilisateur et dans les API publiques échouent par défaut lorsque les intervalles sont inférieurs à 7 jours. Pour forcer les intervalles de rétention inférieurs pour la commande vide, configurez la spark.databricks.delta.retentionDurationCheck.enabled valeur dans false l’espace de travail. Les travaux de maintenance de table prennent ensuite en charge la configuration et permettent une rétention inférieure pendant l’exécution du travail.

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

Contenu connexe

  • Last updated on