Lakehouse beheren in Microsoft Fabric met REST API

De Microsoft Fabric Rest API biedt een service-eindpunt voor de CRUD-bewerking van een Fabric-item. De volgende acties zijn beschikbaar voor lakehouse:

Vereisten

• Als u de Fabric REST API wilt gebruiken, moet u eerst een Microsoft Entra-token voor fabric-service ophalen. Gebruik dat token vervolgens in de autorisatieheader van de API-aanroep.

• Microsoft Fabric Rest API definieert een geïntegreerd eindpunt voor bewerkingen. Het eindpunt is https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items. De tijdelijke aanduidingen {workspaceId} en {lakehouseId} moeten worden vervangen door de juiste waarden bij het uitgeven van de opdrachten die in dit artikel worden geïllustreerd.

Lakehouse CRUD

Gebruik de volgende API om het lakehouse in een werkruimte te maken, te wijzigen en te verwijderen. Zie de documentatie voor Create Lakehouse REST API voor gedetailleerde API-parameters en aanvraagvoorbeelden.

Een lakehouse maken

Verzoek:

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

Antwoord:

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

Een lakehouse bijwerken

Werk de beschrijving bij en wijzig de naam van Lakehouse.

Verzoek:

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/aaaabbbb-0000-cccc-1111-dddd2222eeee 
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
} 

Antwoord:

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

Lakehouse-eigenschappen ophalen

Verzoek:

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

Antwoord:

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

Een lakehouse verwijderen

Wanneer u een lakehouse verwijdert, worden de metagegevens en gegevens van het object verwijderd. Snelkoppelingsverwijzingen worden verwijderd, maar de gegevens blijven behouden op het doel.

Verzoek:

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

Antwoord:Leeg

Tabellen weergeven in een Lakehouse

Verzoek:

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

Antwoord:

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

De API voor lijsttabellen ondersteunt paginering. Geef maxResults per pagina op als parameter voor de aanvraag en de API reageert met de vervolg-URI die kan worden gebruikt om de volgende pagina met resultaten op te halen.

Voorbeeld van paginering

Verzoek:

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

Antwoord:

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

Laden naar tabellen

Deze API biedt de mogelijkheden van de functie Load to Tables Lakehouse. Met deze API kunt u CSV- en Parquet-bestanden laden naar nieuwe of bestaande Delta Lake-tabellen in lakehouse.

Deze API is asynchroon, dus er zijn drie stappen vereist:

1. Upload bestanden en mappen naar de sectie Bestanden van Lakehouse met behulp van OneLake-API's.
2. Laad de API-aanvraag voor tabellen in.
3. Houd de status van de bewerking bij totdat deze is voltooid.

In de volgende secties wordt ervan uitgegaan dat de bestanden al zijn geüpload.

Api-aanvraag voor tabellen laden

De mode parameter ondersteunt overwrite en append bewerkingen. pathType parameter opgegeven bij het laden van afzonderlijke bestanden of alle bestanden uit de opgegeven map. CSV Beide parquet worden ondersteund als de bestandsparameterformat.

In dit voorbeeld wordt een CSV-bestand met de naam geüpload demo.csv naar een bestaande tabel met de naam demo.

Verzoek:

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

De antwoordheader bevat de URI om de status van de asynchrone bewerkingen te peilen. De URI bevindt zich in de locatievariabele van de antwoordheader.

De locatievariabele bevat een URI als volgt: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/bbbbcccc-1111-dddd-2222-eeee3333ffff De guid bbbbcccc-1111-dddd-2222-eeee3333ffff is de bewerkings-id om een query uit te voeren op de status van het uitvoeren van belasting naar tabellen, zoals beschreven in de volgende sectie.

Load to tables operations bewaken

Nadat u de operationId hebt vastgelegd vanuit het antwoord van de load to tables API-aanvraag, voert u de volgende aanvraag uit:

Verzoek:

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

Antwoord:

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

Mogelijke bewerkingsstatus voor laden in tabellen:

• 1 - Bewerking niet gestart
• 2 - Wordt uitgevoerd
• 3 - Geslaagd
• 4 - Mislukt

Tabelonderhoud

Deze API biedt de mogelijkheden van de lakehouse-tabelonderhoudsfunctie. Met deze API is het mogelijk om bin-compactie, V-Order en niet-gelinkte oude bestanden op te ruimen (vacuum).

Deze API is asynchroon, dus er zijn twee stappen vereist:

1. Dien de API-aanvraag voor tabelonderhoud in.
2. Houd de status van de bewerking bij totdat deze is voltooid.

Api-aanvraag voor tabelonderhoud

In dit voorbeeld wordt een tabelonderhoudstaak uitgevoerd die V-Order toepast op een tabel, terwijl ook Z-Order wordt toegepast op de tipAmount kolom en de VACUUM bewerking wordt uitgevoerd met een bewaarperiode van zeven dagen en één uur.

Verzoek:

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

De antwoordheader bevat de URI om de status van de asynchrone bewerkingen te peilen. De URI bevindt zich in de locatievariabele van de antwoordheader.

De locatievariabele bevat een URI als volgt: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/ccccdddd-2222-eeee-3333-ffff4444aaaa De guid ccccdddd-2222-eeee-3333-ffff4444aaaa is de bewerkings-id om een query uit te voeren op de status van actieve tabelonderhoudsbewerkingen, zoals beschreven in de volgende sectie.

Onderhoudsbewerkingen voor tabellen bewaken

Nadat u operationId hebt vastgelegd vanuit het antwoord van de load to tables API-aanvraag, voert u de volgende aanvraag uit:

Verzoek:

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

Antwoord:

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

Mogelijke bewerkingsstatus voor tabelonderhoud:

• NotStarted - Taak niet gestart
• InProgress - Taak wordt uitgevoerd
• Voltooid - Taak voltooid
• Mislukt - Taak is mislukt
• Geannuleerd - Taak geannuleerd
• Ontdubbeld: er wordt al een exemplaar van hetzelfde taaktype uitgevoerd en dit taakexemplaren worden overgeslagen

Gerelateerde inhoud

• Laden naar de functie Tables Lakehouse.
• Gebruik de functie voor tabelonderhoud voor het beheren van deltatabellen in Fabric.
• Optimalisatie van Delta Lake-tabellen en V-Order.