Condividi tramite

Gestire una lakehouse con l'API REST

Questo articolo illustra gli scenari comuni per la gestione di un lakehouse a livello di codice con l'API REST Microsoft Fabric. Ogni sezione mostra la richiesta HTTP e la risposta per un'attività specifica, in modo da poter adattare il modello agli script o alle applicazioni di automazione.

Per la specifica completa, inclusi tutti i parametri, le autorizzazioni necessarie, gli schemi di richiesta e i codici di errore, vedere le informazioni di riferimento sull'API REST Lakehouse.

Prerequisiti

Creare, aggiornare ed eliminare una lakehouse

Gli esempi seguenti illustrano come effettuare il provisioning di un nuovo lakehouse, rinominarlo, recuperarne le proprietà (incluso l'endpoint di analisi SQL con provisioning automatico) ed eliminarlo. Per l'elenco completo dei parametri e altri esempi ,ad esempio la creazione di una lakehouse abilitata per lo schema o la creazione con una definizione, vedere le informazioni di riferimento sull'API Lakehouse Items.

Creare un lakehouse

Per creare una lakehouse in un'area di lavoro, inviare una richiesta POST con il nome visualizzato. Fabric effettua automaticamente il provisioning di un endpoint di analisi SQL insieme alla lakehouse.

Richiedi

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses
{ 
    "displayName": "demo"
}

risposta

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

Aggiornare un lakehouse

Per rinominare una lakehouse o aggiornarne la descrizione, inviare una richiesta PATCH con i nuovi valori.

Richiedi

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
}

risposta

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

Ottenere le proprietà del lakehouse

Recuperare i metadati del lakehouse, inclusi i percorsi di OneLake e la stringa di connessione dell'endpoint di analisi SQL.

Richiedi

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

La cancellazione di un lakehouse rimuove i relativi metadati e dati. I collegamenti vengono rimossi, ma i dati nella destinazione del collegamento vengono mantenuti.

Richiedi

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

risposta

Il corpo della risposta è vuoto.

Elencare le tabelle in una lakehouse

Per recuperare tutte le tabelle Delta in un lakehouse, utilizzare l'endpoint List Tables, ad esempio per compilare un catalogo dei dati o convalidare una distribuzione. Per l'elenco completo dei parametri, vedere le informazioni di riferimento sull'API Tabelle.

Richiedi

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 la paginazione. Passare maxResults come parametro di query per controllare le dimensioni della pagina. La risposta include un continuationUri che puoi utilizzare per recuperare la pagina successiva.

Impaginazione tramite un elenco di tabelle di grandi dimensioni

Richiedi

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 un file in una tabella Delta

Per convertire file CSV o Parquet in tabelle Delta senza scrivere codice Spark, usare l'API Load Table. Si tratta dell'equivalente programmatico della funzionalità Carica in tabelle nella home page di Lakehouse. Per l'elenco completo dei parametri, vedere le informazioni di riferimento sull'API Load Table.

L'operazione è asincrona. Segui questi passaggi:

  1. Caricare i file nella sezione Lakehouse Files usando le API OneLake.
  2. Inviare la richiesta di caricamento.
  3. Monitorare lo stato dell'operazione fino al suo completamento.

Gli esempi seguenti presuppongono che i file siano già caricati.

Inviare la richiesta di caricamento

In questo esempio viene caricato un file CSV denominato demo.csv in una tabella denominata demo, sovrascrivendo i dati esistenti. Imposta mode su Append, invece, per aggiungere righe. Impostare pathType su Folder per caricare tutti i file in una cartella.

Richiedi

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

La risposta non include un corpo. L'intestazione Location contiene invece un URI usato per eseguire il polling dello stato dell'operazione. L'URI segue questo modello:

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

Sondare lo stato dell'operazione di caricamento

Utilizza il operationId dall'intestazione Location per controllare il progresso.

Richiedi

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

risposta

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

Possibili stati dell'operazione per il caricamento nelle tabelle:

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

Eseguire la manutenzione delle tabelle in una tabella Delta

Per ottimizzare le tabelle Delta, applicando bin-compaction, V-Order, Z-Order o VACUUM, senza usare Lakehouse Explorer, usare l'API Manutenzione tabelle. Si tratta dell'equivalente a livello di codice della funzionalità di manutenzione della tabella. Per l'elenco completo dei parametri, vedere le informazioni di riferimento sull'API Manutenzione tabelle.

L'operazione è asincrona. Segui questi passaggi:

  1. Inviare la richiesta di manutenzione della tabella.
  2. Monitorare lo stato dell'operazione fino al suo completamento.

Inviare la richiesta di manutenzione della tabella

L'esempio applica l'ottimizzazione V-Order e Z-Order sulla colonna tipAmount ed esegue VACUUM con un periodo di conservazione di sette giorni e un'ora.

Richiedi

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/jobs/TableMaintenance/instances
{
    "executionData": {
        "tableName": "{table_name}",
        "schemaName": "{schema_name}",
        "optimizeSettings": {
            "vOrder": true,
            "zOrderBy": [
                "tipAmount"
            ]
        },
        "vacuumSettings": {
            "retentionPeriod": "7:01:00:00"
        }
    }
}

La risposta non include un corpo. L'intestazione Location contiene un URI che utilizzi per verificare lo stato dell'operazione.

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

L'endpoint di esecuzione è su ambito lakehouse, ma il polling dell'istanza del processo utilizza l'endpoint generico dell'elemento di processo (/items/{itemId}/jobs/instances/{jobInstanceId}) per progettazione.

Importante

L'impostazione di un periodo di conservazione inferiore a sette giorni influisce sul viaggio in tempo delta e può causare errori di lettura o danneggiamento delle tabelle se gli snapshot o i file di cui non è stato eseguito il commit sono ancora in uso. Per questo motivo, la manutenzione delle tabelle sia nella Fabric UI che nelle API REST rifiuta per impostazione predefinita i periodi di conservazione inferiori a sette giorni. Per consentire un intervallo più breve, impostare su spark.databricks.delta.retentionDurationCheck.enabledfalse nelle impostazioni dell'area di lavoro, quindi i processi di manutenzione della tabella usano tale configurazione durante l'esecuzione.

Monitorare lo stato di manutenzione della tabella

Usare il operationId dall'intestazione Location per controllare lo stato del processo.

Richiedi

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

Questa route di polling usa items intenzionalmente anziché lakehouses.

risposta

{
    "id": "{operationId}",
    "itemId": "431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7",
    "jobType": "TableMaintenance",
    "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 - Lavoro 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 saltata

Contenuto correlato

  • Last updated on