Administrer et søhus med REST API'en

Denne artikel gennemgår almindelige scenarier for at administrere et lakehouse programmatisk med Microsoft Fabric REST API. Hver sektion viser HTTP-anmodningen og svaret for en specifik opgave, så du kan tilpasse mønsteret til dine automatiseringsscripts eller applikationer.

For den fulde specifikation — inklusive alle parametre, nødvendige tilladelser, anmodningsskemaer og fejlkoder — se Lakehouse REST API-referencen.

Prerequisites

• Få et Microsoft Entra-token til Fabric-tjenesten og inkluder det i Authorization headeren på hver anmodning.
• Erstat {workspaceId} og {lakehouseId} i eksemplerne nedenfor med dine egne værdier.

Opret, opdater og slet et sommerhus ved søen

Følgende eksempler viser, hvordan man provisionerer et nyt lakehouse, omdøber det, henter dets egenskaber (inklusive det auto-provisionerede SQL-analyse-endpoint) og sletter det. For den fulde parameterliste og yderligere eksempler (såsom at oprette et skema-aktiveret lakehouse eller oprette med en definition), se Lakehouse Items API-referencen.

Opret et lakehouse

For at oprette et søhus i et arbejdsområde, send en POST-anmodning med visningsnavnet. Fabric stiller automatisk et SQL-analyse-endpoint til rådighed ved siden af lakehouset.

Request

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

Svar

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

Opdater et lakehouse

For at omdøbe et søhus eller opdatere dets beskrivelse, send en PATCH-anmodning med de nye værdier.

Request

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

Svar

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

Hent lakehouse-egenskaber

Hent lakehouse-metadata, inklusive OneLake-stierne og SQL-analyse-endpoint-forbindelsesstrengen.

Request

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

Svar

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

Slet et lakehouse

Sletning af et søhus fjerner dets metadata og data. Genveje fjernes, men dataene ved genvejsmålet bevares.

Request

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

Svar

Responskroppen er tom.

Opfør bordene i et søhus

For at hente alle Delta-tabeller i et lakehouse — for eksempel for at bygge et datakatalog eller validere en udrulning — brug List Tables-endpointet. For den fulde parameterliste, se Tables API-referencen.

Request

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

Svar

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

List Tables API understøtter paginering. Som en forespørgselsparameter maxResults for at styre sidestørrelsen. Svaret indeholder et continuationUri opkald for at hente næste side.

Paginering gennem en stor tabelliste

Request

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

Svar

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

Indlæs en fil i en Delta-tabel

For at konvertere CSV- eller Parquet-filer til Delta-tabeller uden at skrive Spark-kode, brug Load Table API'en. Dette er den programmatiske ækvivalent til funktionen Load to Tables på Lakehouses hjemmeside. For den fulde parameterliste, se Load Table API-referencen.

Operationen er asynkron. Følg disse trin:

1. Upload filer til lakehouse Files-sektionen ved at bruge OneLake API'er.
2. Indsend belastningsanmodningen.
3. Poll operationens status, indtil den er fuldført.

Følgende eksempler antager, at filerne allerede er uploadet.

Indsend belastningsanmodningen

Dette eksempel indlæser en CSV-fil med navnet demo.csv i en tabel med navnet demo, overskriver eksisterende data. Sæt mode til Append for at tilføje rækker i stedet. Sæt pathType til Folder at indlæse alle filer i en mappe.

Request

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

Svaret inkluderer ikke et lig. I stedet indeholder headeren en URI, Location som du bruger til at polle operationens status. URI følger dette mønster:

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

Poll load operations-status

Brug fra headeren operationId til at tjekke Location fremskridt:

Request

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

Svar

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

Mulig handlingsstatus for indlæsning i tabeller:

• 1 – Handlingen er ikke startet
• 2 – kører
• 3 – gennemført
• 4 - Mislykkedes

Kør bordvedligeholdelse på en Delta-tabel

For at optimere Delta-tabeller — ved at anvende bin-kompaktion, V-Order, Z-Order eller VACUUM — uden at bruge Lakehouse Explorer, brug Table Maintenance API. Dette er den programmatiske ækvivalent til tabelvedligeholdelsesfunktionen. For den fulde parameterliste, se Table Maintenance API-referencen.

Operationen er asynkron. Følg disse trin:

1. Indsend anmodningen om bordvedligeholdelse.
2. Poll operationens status, indtil den er fuldført.

Indsend anmodningen om bordvedligeholdelse

Dette eksempel anvender V-Order optimering og Z-Order på kolonnen tipAmount og kører VACUUM med en retentionsperiode på syv dage og en time.

Request

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

Svaret inkluderer ikke et lig. Headeren Location indeholder en URI, du bruger til at polle operationens status:

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

Kør-endpointet er lakehouse-scoped, men job-instance polling bruger designet det generiske item job-endpoint (/items/{itemId}/jobs/instances/{jobInstanceId})

Poll tabellen vedligeholdelsesstatus

Brug fra headeren operationId til at tjekke Location jobstatus:

Request

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

Denne polling-rute bruger items bevidst i stedet for lakehouses.

Svar

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

Mulig handlingsstatus for tabelvedligeholdelse:

• NotStarted – Jobbet er ikke startet
• InProgress – igangværende job
• Fuldført - jobbet er fuldført
• Mislykket - jobbet mislykkedes
• Annulleret - job annulleret
• Deduped – Der kører allerede en forekomst af samme jobtype, og denne jobforekomst springes over

Relateret indhold

• Lakehouse REST API-reference
• Indlæsning til tabeller
• Brug tabelvedligeholdelsesfunktionen til at administrere delta-tabeller i Fabric
• Tabeloptimering af Delta Lake og V-Order
• Fabric REST API quickstart