Administrere lakehouse i Microsoft Fabric med REST API

  • Artikkel

Microsoft Fabric Rest-API-en tilbyr tjenesteendepunkt for CRUD-operasjonen av et stoffelement. Følgende handlinger er tilgjengelige for Lakehouse:

Handling Bekrivelse
Create Oppretter et lakehouse inne i et arbeidsområde. Et SQL Analytics-endepunkt blir også klargjort sammen med lakehouse.
Oppdater Oppdateringer navnet på et lakehouse og SQL Analytics-endepunktet.
Delete Sletter lakehouse og det tilknyttede SQL Analytics-endepunktet.
Hent egenskaper Henter egenskapene til et lakehouse og SQL Analytics-endepunktet.
Listetabeller Vis tabeller i lakehouse.
Tabellinnlasting Oppretter deltatabeller fra CSV og parkettfiler og mapper.
Tabellvedlikehold Bruk bin-compaction, V-Order, og fjerning av unreferenced og gamle filer.

Forutsetning

Microsoft Fabric Rest API definerer et enhetlig endepunkt for operasjoner. Endepunktet er https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items. Plassholderne og {lakehouseId} bør erstattes {workspaceId} med de riktige verdiene når du utsteder kommandoene som er eksemplifisert i denne artikkelen.

Lakehouse CRUD

Bruk følgende API til å utføre oppretting, endringer og fjerning av lakehouse i et arbeidsområde.

Opprett et innsjøhus

Forespørsel:

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

Svar:

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

Oppdater et innsjøhus

Oppdater beskrivelsen, og gi nytt navn til Lakehouse.

Forespørsel:

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

Svar:

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

Få egenskaper for lakehouse

Forespørsel:

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": "hkpobavgthae5kji5cuqxtivcu-dda6npvkyiaeteyrkfkgim53xa-datawarehouse.pbidedicated.windows.net", 
            "id": "0dfbd45a-2c4b-4f91-920a-0bb367826479", 
            "provisioningStatus": "Success" 
        } 
    } 
}

Slette et innsjøhus

Når du sletter et lakehouse, slettes objektmetadataene og dataene. Snarveisreferanser slettes, men dataene beholdes på målet.

Forespørsel:

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

Svar:Tom

Listetabeller i et Lakehouse

Forespørsel:

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

API-en for listetabeller støtter paginering. Angi maxResults per side som parameter for forespørselen, og API-en svarer med fortsettelses-URI-en som kan brukes til å hente neste side med resultater.

Eksempel på paginering

Forespørsel:

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

Last inn i tabeller

Denne API-en viser egenskapene til lakehouse-funksjonen Last til tabeller. Med denne API-en er det mulig å laste inn CSV- og parkettfiler til nye eller eksisterende delta-bord i lakehouse.

Denne API-en er asynkron, så tre trinn kreves:

  1. Last opp filer og mapper til Lakehouses Filer-inndeling ved hjelp av OneLake-API-er.
  2. Send inn belastning til tabell-API-forespørsel.
  3. Spor statusen for operasjonen til den er fullført.

Avsnittene nedenfor antar at filene allerede er lastet opp.

Last inn til tabell-API-forespørsel

Parameteren mode støtter overwrite og append operasjoner. pathType parameter angitt hvis du laster inn enkeltfiler eller alle filer fra den angitte mappen. Begge CSV og parquet støttes som filparameter format .

Dette eksemplet laster opp en CSV-fil med navnet demo.csv til en eksisterende tabell med navnet demo.

Forespørsel:

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

Svarhodet inneholder URI-en for å undersøke statusen for asynkrone operasjoner. URI-en er i plasseringsvariabelen for svarhodet.

Plasseringsvariabelen inneholder en URI som følger: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/32ad6d2a-82bb-420d-bb57-4620c8860373. GUIDen 32ad6d2a-82bb-420d-bb57-4620c8860373 er operasjons-IDen for å spørre statusen for kjøring av belastning til tabelloperasjoner som beskrevet i neste del.

Overvåking av belastning på tabelloperasjoner

Når du har tatt operationId fra svaret på API-forespørselen om innlasting til tabeller, utfører du følgende forespørsel:

Forespørsel:

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

Svar:

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

Mulig operasjonsstatus for innlasting til tabeller:

  • 1 - Operasjonen er ikke startet
  • 2 - Kjører
  • 3 – Vellykket
  • 4 - Mislyktes

Tabellvedlikehold

Denne API-en viser egenskapene til lakehouse-bordvedlikeholdsfunksjonen. Med denne API-en er det mulig å bruke bin-komprimering, V-Order og unreferenced old files cleanup.

Denne API-en er asynkron, så to trinn kreves:

  1. Send inn API-forespørsel om vedlikehold av tabell.
  2. Spor statusen for operasjonen til den er fullført.

API-forespørsel om vedlikehold av tabell

Dette eksemplet utfører en vedlikeholdsjobb for tabeller som bruker V-ordre på en tabell, samtidig som du bruker Z-ordre tipAmount på kolonnen og utfører VACUUM operasjonen med en oppbevaring på sju dager og én time.

Forespørsel:

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

Svarhodet inneholder URI-en for å undersøke statusen for asynkrone operasjoner. URI-en er i plasseringsvariabelen for svarhodet.

Plasseringsvariabelen inneholder en URI som følger: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b. GUIDen f2d65699-dd22-4889-980c-15226deb0e1b er operasjons-ID-en for å spørre statusen for å kjøre vedlikeholdsoperasjoner for tabeller, som beskrevet i neste del.

Overvåke vedlikeholdsoperasjoner for tabell

Når du har tatt operationId fra svaret på API-forespørselen om innlasting til tabeller, utfører du følgende forespørsel:

Forespørsel:

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

Svar:

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

Mulig operasjonsstatus for tabellvedlikehold:

  • NotStarted – jobben er ikke startet
  • InProgress – jobb pågår
  • Fullført – jobben er fullført
  • Mislyktes - jobben mislyktes
  • Avbrutt - jobben er avbrutt
  • Deduped – en forekomst av samme jobbtype kjører allerede, og denne jobbforekomsten hoppes over

Relatert innhold