Gestire lakehouse in Microsoft Fabric con l'API REST
L'API REST di Microsoft Fabric fornisce l'endpoint di servizio per il funzionamento CRUD di un elemento di Fabric. Per lakehouse sono disponibili le azioni seguenti:
| Azione | Descrizione |
|---|---|
| Creazione | Crea una lakehouse all'interno di un'area di lavoro. Viene eseguito anche il provisioning di un endpoint di analisi SQL insieme alla lakehouse. |
| Aggiornamento | Aggiornamenti il nome di una lakehouse e dell'endpoint di analisi SQL. |
| Eliminazione | 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 le tabelle nella lakehouse. |
| Caricamento tabelle | Crea tabelle differenziali da file e cartelle CSV e parquet. |
| Manutenzione tabelle | Applicare la compattazione bin, l'ordine V e la rimozione di file non referenziati e obsoleti. |
Prerequisiti
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 exemplificati 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 una 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 una lakehouse
Aggiornare la descrizione e rinominare 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": "hkpobavgthae5kji5cuqxtivcu-dda6npvkyiaeteyrkfkgim53xa-datawarehouse.pbidedicated.windows.net",
"id": "0dfbd45a-2c4b-4f91-920a-0bb367826479",
"provisioningStatus": "Success"
}
}
}
Eliminare una lakehouse
Quando si elimina una lakehouse, i metadati e i dati dell'oggetto vengono eliminati. I riferimenti di scelta rapida vengono eliminati, ma i dati vengono mantenuti nella destinazione.
Richiesta:
DELETE https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}
Risposta:Vuoto
Elencare le 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 tabelle elenco supporta l'impaginazione. Specificare maxResults per pagina come parametro per la richiesta e 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"
}
]
}
Caricare nelle tabelle
Questa API illustra le funzionalità della funzionalità Load to Tables lakehouse. Con questa API, è possibile caricare file CSV e parquet in tabelle delta lake nuove o esistenti nella lakehouse.
Questa API è asincrona, quindi sono necessari tre passaggi:
- Caricare file e cartelle nella sezione File di Lakehouse usando le API OneLake.
- Inviare il caricamento alla richiesta API tabelle.
- Tenere traccia dello stato dell'operazione fino al completamento.
Le sezioni seguenti presuppongono che i file siano già stati caricati.
Richiesta API Load to tables (Carica nelle tabelle)
Il mode parametro supporta overwrite le operazioni e append .
pathType parametro specificato se si caricano singoli file o tutti i file dalla cartella specificata.
Sia CSV che parquet sono supportati come parametro di 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 di caricamento nelle tabelle, come descritto nella sezione successiva.
Monitoraggio delle operazioni di caricamento nelle tabelle
Dopo aver acquisito operationId dalla risposta della richiesta API load to tables, 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 il caricamento nelle tabelle:
- 1 - Operazione non avviata
- 2 - Esecuzione
- 3 - Esito positivo
- 4 - Operazione non riuscita
Manutenzione tabelle
Questa API illustra le funzionalità della funzionalità di manutenzione della tabella Lakehouse. Con questa API è possibile applicare la compattazione bin, l'ordine V e la pulizia dei 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 della tabella che applica V-Order a una tabella, applicando allo stesso tempo Z Order alla tipAmount colonna 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 della tabella, come descritto nella sezione successiva.
Monitoraggio delle operazioni di manutenzione delle tabelle
Dopo aver acquisito operationId dalla risposta della richiesta API load to tables, 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
- Completato - Processo completato
- Non riuscito - Processo non riuscito
- Annullata - Processo annullato
- Deduplicato: un'istanza dello stesso tipo di processo è già in esecuzione e questa istanza del processo viene ignorata
Contenuto correlato
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per