Gestire lakehouse in Microsoft Fabric con l'API REST

Articolo
01/16/2025

L'API REST di Microsoft Fabric fornisce l'endpoint di servizio per il funzionamento CRUD di un elemento di Fabric. Per il lakehouse sono disponibili le azioni seguenti:

Azione	Descrizione
Creazione	Crea un lakehouse all'interno di un'area di lavoro. Viene eseguito anche il provisioning di un endpoint di Analisi SQL insieme al lakehouse.
Update	Aggiorna il nome di un lakehouse e l'endpoint di Analisi SQL.
Elimina	Elimina lakehouse e l'endpoint di Analisi SQL associato.
Ottenere le proprietà	Ottiene le proprietà di un lakehouse e dell'endpoint di Analisi SQL.
Elencare le tabelle	Elencare tabelle nel lakehouse.
Caricamento di tabelle	Crea tabelle Delta da file e cartelle CSV e Parquet.
Manutenzione delle tabelle	Applicare bin-compaction, V-Order e rimozione di file vecchi o senza riferimento.

Prerequisiti

Per usare l'API REST di Fabric, è necessario prima ottenere un token di Microsoft Entra per il servizio Fabric. Usare quindi tale token nell'intestazione di autorizzazione della chiamata API.
L'API REST di Microsoft Fabric definisce un endpoint unificato per le operazioni. L'endpoint è https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items. I segnaposto {workspaceId} e {lakehouseId} devono essere sostituiti con i valori appropriati quando si emettono i comandi esemplificati in questo articolo.

Lakehouse CRUD

Usare l'API seguente per eseguire la creazione, le modifiche e la rimozione del lakehouse all'interno di un'area di lavoro.

Creare un lakehouse

Richiesta:

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

Risposta:

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

Aggiornare un lakehouse

Aggiornare la descrizione e rinominare il lakehouse.

Richiesta:

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

Risposta:

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

Ottenere le proprietà del lakehouse

Richiesta:

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

Risposta:

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

Eliminare un lakehouse

Quando si elimina un lakehouse, i dati e i metadati dell'oggetto vengono eliminati. I riferimenti dei collegamenti vengono eliminati, ma i dati vengono mantenuti nella destinazione.

Richiesta:

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

Risposta: Vuoto

Elencare tabelle in un lakehouse

Richiesta:

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

Risposta:

{ 
    "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 delle tabelle dell’elenco supporta la paginazione. Specificando maxResults per ogni pagina come parametro per la richiesta, l'API risponde con l'URI di continuazione che può essere usato per ottenere la pagina successiva dei risultati.

Esempio di paginazione

Richiesta:

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

Risposta:

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

Carica in tabelle

Questa API illustra le capacità della funzionalità Carica in tabelle di Lakehouse. Con questa API, è possibile caricare file CSV e Parquet in tabelle Delta Lake nuove o esistenti nel lakehouse.

Questa API è asincrona, quindi sono necessari tre passaggi:

Caricare file e cartelle nella sezione File di Lakehouse usando le API OneLake.
Inviare la richiesta dell’API Carica in tabelle.
Tenere traccia dello stato dell'operazione fino al completamento.

Le sezioni seguenti presuppongono che i file siano già stati caricati.

Richiesta dell’API Carica in tabelle

Il parametro mode supporta operazioni overwrite e append. Il parametro pathType viene specificato se si caricano singoli file o tutti i file da una cartella specificata. Sia CSV che parquet sono supportati come parametro file format.

In questo esempio viene caricato un file CSV denominato demo.csv in una tabella esistente denominata demo.

Richiesta:

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'intestazione della risposta contiene l'URI per eseguire il polling dello stato delle operazioni asincrone. L’URI si trova nella variabile Location dell’intestazione della risposta.

La variabile Location contiene un URI come indicato di seguito: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/32ad6d2a-82bb-420d-bb57-4620c8860373. Il GUID 32ad6d2a-82bb-420d-bb57-4620c8860373 è l'ID operazione per eseguire una query sullo stato dell'esecuzione di operazioni Carica in tabelle, come descritto nella sezione successiva.

Monitoraggio delle operazioni di Carica in tabelle

Dopo aver acquisito operationId dalla risposta della richiesta dell’API Carica in tabelle, eseguire la richiesta seguente:

Richiesta:

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

Risposta:

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

Possibile stato dell'operazione per Carica in tabelle:

1- Operazione non avviata
2 - Esecuzione
3 - Operazione riuscita
4 - Operazione non riuscita

Manutenzione delle tabelle

Questa API illustra le capacità della funzionalità di manutenzione delle tabelle di Lakehouse. Con questa API è possibile applicare bin-compaction, V-Order e pulizia di file precedenti senza riferimenti.

Questa API è asincrona, quindi sono necessari due passaggi:

Inviare una richiesta API di manutenzione tabelle.
Tenere traccia dello stato dell'operazione fino al completamento.

Richiesta dell'API di manutenzione tabelle

In questo esempio viene eseguito un processo di manutenzione tabelle che applica V-Order a una tabella, applicando al tempo stesso Z-Order alla colonna tipAmount ed eseguendo l'operazione VACUUM con una conservazione di sette giorni e un'ora.

Richiesta:

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'intestazione della risposta contiene l'URI per eseguire il polling dello stato delle operazioni asincrone. L’URI si trova nella variabile Location dell’intestazione della risposta.

La variabile Location contiene un URI come indicato di seguito: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b. Il GUID f2d65699-dd22-4889-980c-15226deb0e1b è l'ID operazione per eseguire una query sullo stato delle operazioni di manutenzione tabelle, come descritto nella sezione successiva.

Monitoraggio delle operazioni di manutenzione delle tabelle

Dopo aver acquisito operationId dalla risposta della richiesta dell’API Carica in tabelle, eseguire la richiesta seguente:

Richiesta:

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

Risposta:

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

Possibile stato dell'operazione per la manutenzione delle tabelle:

NotStarted - Processo non avviato
InProgress - Processo in corso
Completed - Processo completato
Failed - Processo non riuscito
Canceled - Processo annullato
Deduped - Un'istanza dello stesso tipo di processo è già in esecuzione e questa istanza del processo viene ignorata

Funzionalità Carica in tabelle di Lakehouse.
Usare la funzionalità di manutenzione delle tabelle per gestire tabelle Delta in Fabric.
Ottimizzazione delle tabelle Delta Lake e V-Order.

Condividi tramite

Gestire lakehouse in Microsoft Fabric con l'API REST

Prerequisiti

Lakehouse CRUD

Creare un lakehouse

Aggiornare un lakehouse

Ottenere le proprietà del lakehouse

Eliminare un lakehouse

Elencare tabelle in un lakehouse

Carica in tabelle

Richiesta dell’API Carica in tabelle

Monitoraggio delle operazioni di Carica in tabelle

Manutenzione delle tabelle

Richiesta dell'API di manutenzione tabelle

Monitoraggio delle operazioni di manutenzione delle tabelle

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Gestire lakehouse in Microsoft Fabric con l'API REST

Prerequisiti

Lakehouse CRUD

Creare un lakehouse

Aggiornare un lakehouse

Ottenere le proprietà del lakehouse

Eliminare un lakehouse

Elencare tabelle in un lakehouse

Esempio di paginazione

Carica in tabelle

Richiesta dell’API Carica in tabelle

Monitoraggio delle operazioni di Carica in tabelle

Manutenzione delle tabelle

Richiesta dell'API di manutenzione tabelle

Monitoraggio delle operazioni di manutenzione delle tabelle

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive