Forbedret opdatering med Power BI REST API

  • Artikel

Du kan bruge et hvilket som helst programmeringssprog, der understøtter REST-kald, til at udføre semantiske modelopdateringshandlinger ved hjælp af REST API'en til opdatering af datasæt i Power BI.

Optimeret opdatering af store og komplekse partitionerede modeller kaldes traditionelt med programmeringsmetoder, der bruger TOM (Tabellarisk objektmodel), PowerShell-cmdlet'er eller TMSL (Tabular Model Scripting Language). Disse metoder kræver dog langvarige HTTP-forbindelser, der kan være upålidelige.

REST API'en til opdatering af Power BI-datasæt kan udføre modelopdateringshandlinger asynkront, så langvarige HTTP-forbindelser fra klientprogrammer er ikke nødvendige. Sammenlignet med standardopdateringshandlinger giver forbedret opdatering med REST-API'en flere tilpasningsindstillinger og følgende funktioner, der er nyttige for store modeller:

  • Batchafgjorte bekræftelser
  • Opdatering af tabel- og partitionsniveau
  • Anvendelse af politikker for trinvis opdatering
  • GET oplysninger om opdatering
  • Annullering af opdatering

Bemærk

  • Tidligere blev udvidet opdatering kaldt asynkron opdatering med REST API. En standardopdatering, der bruger REST API'en Refresh Dataset, kører dog også asynkront på grund af dens iboende karakter.
  • Forbedrede power BI REST API-opdateringshandlinger opdaterer ikke feltcacher automatisk. Feltet cachelagrer kun opdatering, når en bruger får adgang til en rapport.

Basiswebadresse

URL-basisadressen har følgende format:

https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes

Du kan føje ressourcer og handlinger til den grundlæggende URL-adresse baseret på parametre. I følgende diagram er grupper, datasæt og opdateringer samlinger. Gruppér, Datasæt og Opdater er objekter.

Diagram that shows asynchronous refresh flow.

Krav

Du skal bruge følgende krav for at bruge REST-API'en:

  • En semantisk model i Power BI Premium, Premium pr. bruger eller Power BI Embedded.
  • Et gruppe-id og datasæt-id, der skal bruges i anmodningens URL-adresse.
  • Dataset.ReadWrite.All tilladelsesområde.

Antallet af opdateringer er begrænset i henhold til de generelle begrænsninger for API-baserede opdateringer til Pro- og Premium-modeller.

Godkendelse

Alle kald skal godkendes med et gyldigt Microsoft Entra ID OAuth 2-token i godkendelsesheaderen. Tokenet skal opfylde følgende krav:

  • Være enten et brugertoken eller en programtjenesteprincipal.
  • Angiv målgruppen korrekt til https://api.powerbi.com.
  • Bruges af en bruger eller et program, der har tilstrækkelige tilladelser til modellen.

Bemærk

REST API-ændringer ændrer ikke de aktuelt definerede tilladelser for modelopdateringer.

POST/opdateringer

Hvis du vil foretage en opdatering, skal du bruge VERBet POST i samlingen /refreshes til at føje et nyt opdateringsobjekt til samlingen. Overskriften Placering i svaret indeholder requestId. Da handlingen er asynkron, kan et klientprogram afbryde forbindelsen og bruge requestId til at kontrollere statussen senere, hvis det er nødvendigt.

Følgende kode viser en eksempelanmodning:

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

Anmodningens brødtekst kan ligne følgende eksempel:

{
    "type": "Full",
    "commitMode": "transactional",
    "maxParallelism": 2,
    "retryCount": 2,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Bemærk

Tjenesten accepterer kun én opdateringshandling ad gangen for en model. Hvis der er en aktuel kørende opdatering, og der sendes en anden anmodning, returneres en 400 Bad Request HTTP-statuskode.

Parametre

Hvis du vil udføre en udvidet opdateringshandling, skal du angive en eller flere parametre i anmodningens brødtekst. Angivne parametre kan angive standarden eller en valgfri værdi. Når anmodningen angiver parametre, gælder alle andre parametre for handlingen med deres standardværdier. Hvis anmodningen ikke angiver nogen parametre, bruger alle parametre deres standardværdier, og der udføres en standardopdateringshandling.

Name Skriv Standard Beskrivelse
type Enum automatic Den type behandling, der skal udføres. Typerne justeres i forhold til TMSL-kommandotyperne for opdatering: full, clearValues, calculate, dataOnlyautomaticog defragment. Typen add understøttes ikke.
commitMode Enum transactional Bestemmer, om objekter skal bekræftes i batches, eller om de kun skal udføres, når de er fuldført. Tilstande er transactional og partialBatch. Når du bruger partialBatch opdateringshandlingen, sker der ikke inden for én transaktion. Hver kommando udføres individuelt. Hvis der er en fejl, kan modellen være tom eller kun indeholde et undersæt af dataene. Hvis du vil beskytte mod fejl og bevare de data, der var i modellen, før handlingen startede, skal du udføre handlingen med commitMode = transactional.
maxParallelism Int 10 Bestemmer det maksimale antal tråde, der kan køre behandlingskommandoerne parallelt. Denne værdi justeres i forhold til den MaxParallelism egenskab, der kan angives i TMSL-kommandoen Sequence eller ved hjælp af andre metoder.
retryCount Int 0 Det antal gange, handlingen forsøger igen, før der mislykkes.
objects Matrix Hele modellen En matrix af objekter, der skal behandles. Hvert objekt omfatter table , når en hel tabel behandles, eller table når partition en partition behandles. Hvis der ikke er angivet nogen objekter, opdateres hele modellen.
applyRefreshPolicy Boolean true Hvis der er defineret en politik for trinvis opdatering, bestemmer, om politikken skal anvendes. Tilstande er true eller false. Hvis politikken ikke anvendes, forbliver partitionsdefinitionerne uændrede under hele processen, og alle partitioner i tabellen opdateres fuldt ud.

Hvis commitMode er transactional, applyRefreshPolicy kan være true eller false. Hvis commitMode er partialBatch, applyRefreshPolicytrue understøttes ikke, og applyRefreshPolicy skal angives til false.
effectiveDate Dato Dags dato Hvis der anvendes en politik for trinvis opdatering, effectiveDate tilsidesætter parameteren den aktuelle dato. Hvis den ikke er angivet, bruges UTC til at bestemme den aktuelle dag.

Response

202 Accepted

Svaret indeholder også et Location svarheaderfelt for at pege kalderen på den opdateringshandling, der blev oprettet og accepteret. Location er placeringen af den nye ressource, som anmodningen har oprettet, hvilket omfatter den requestId , som nogle forbedrede opdateringshandlinger kræver. I følgende svar requestId er f.eks. det sidste id i svaret 87f31ef7-1e3a-4006-9b0b-191693e79e9e.

x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e

HENT/opdateringer

Brug verbet GET i samlingen /refreshes til at angive historiske, aktuelle og ventende opdateringshandlinger.

Svarets brødtekst kan se ud som i følgende eksempel:

[
    {
        "requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T02:06:57.1838734Z",
        "endTime": "2020-12-07T02:07:00.4929675Z",
        "status": "Completed",
        "extendedStatus": "Completed"
    },
    {
        "requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "refreshType": "ViaEnhancedApi",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Bemærk

Power BI kan droppe anmodninger, hvis der er for mange anmodninger på kort tid. Power BI udfører en opdatering, sætter den næste anmodning i kø og dropper alle andre. Tilsigtet kan du ikke forespørge om status for mistede anmodninger.

Svaregenskaber

Name Skriv Description
requestId Guid Id'et for opdateringsanmodningen. Du skal requestId forespørge om status for individuel opdateringshandling eller annullere en igangværende opdateringshandling.
refreshType String OnDemand angiver, at opdateringen blev udløst interaktivt via Power BI-portalen.
Scheduled angiver, at en tidsplan for modelopdatering udløste opdateringen.
ViaApi angiver, at et API-kald udløste opdateringen.
ViaEnhancedApi angiver, at et API-kald udløste en forbedret opdatering.
startTime String Dato og klokkeslæt for opdateringsstart.
endTime String Dato og klokkeslæt for opdateringsafslutning.
status String Completed angiver, at opdateringshandlingen er fuldført.
Failed angiver, at opdateringshandlingen mislykkedes.
Unknown angiver, at fuldførelsestilstanden ikke kan bestemmes. Med denne status endTime er tom.
Disabled angiver, at opdateringen blev deaktiveret af selektiv opdatering.
Cancelled angiver, at opdateringen blev annulleret.
extendedStatus String Forøger egenskaben for status at give flere oplysninger.

Bemærk

I Azure Analysis Services er succeededdet fuldførte status resultat . Hvis du overfører en Azure Analysis Services-løsning til Power BI, skal du muligvis ændre dine løsninger.

Begræns antallet af returnerede opdateringshandlinger

Power BI REST API understøtter begrænsning af det ønskede antal poster i opdateringshistorikken ved hjælp af den valgfri $top parameter. Hvis den ikke er angivet, er standarden alle tilgængelige poster.

GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}

GET/refreshes/<requestId>

Hvis du vil kontrollere status for en opdateringshandling, skal du bruge verbet GET på opdateringsobjektet ved at angive requestId. Hvis handlingen er i gang, status returneres InProgresssom i følgende eksempel på svarbrødtekst:

{
    "startTime": "2020-12-07T02:06:57.1838734Z",
    "endTime": "2020-12-07T02:07:00.4929675Z",
    "type": "Full",
    "status": "InProgress",
    "currentRefreshType": "Full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "InProgress"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "InProgress"
        }
    ]
}

DELETE/refreshes/<requestId>

Hvis du vil annullere en igangværende udvidet opdateringshandling, skal du bruge verbet DELETE på opdateringsobjektet ved at angive requestId.

Eksempel

DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac

Overvejelser og begrænsninger

Opdateringshandlingen har følgende overvejelser og begrænsninger:

Standardopdateringshandlinger

  • Du kan ikke annullere planlagte eller manuelle modelopdateringer efter behov ved hjælp DELETE /refreshes/<requestId>af .
  • Planlagte og on-demand manuelle modelopdateringer understøtter ikke hentning af oplysninger om opdateringshandlinger ved hjælp GET /refreshes/<requestId>af .
  • Hent detaljer, og Annuller er kun nye handlinger til forbedret opdatering. Standardopdatering understøtter ikke disse handlinger.

Power BI Embedded

Hvis kapaciteten afbrydes midlertidigt manuelt på Power BI-portalen eller ved hjælp af PowerShell, eller der opstår et systemafbrydelse, forbliver InProgress status for en igangværende udvidet opdateringshandling i højst seks timer. Hvis kapaciteten genoptages inden for seks timer, genoptages opdateringshandlingen automatisk. Hvis kapaciteten genoptages efter mere end seks timer, kan opdateringshandlingen returnere en timeoutfejl. Du skal derefter genstarte opdateringshandlingen.

Fjernelse af semantisk model

Power BI bruger dynamisk hukommelsesstyring til at optimere kapacitetshukommelsen. Hvis modellen fjernes fra hukommelsen under en opdateringshandling, returneres følgende fejl muligvis:

{
    "messages": [
        {
            "code": "0xC11C0020",
            "message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
            "type": "Error"
        }
    ]
}

Løsningen er at køre opdateringshandlingen igen. Hvis du vil vide mere om dynamisk hukommelsesstyring og fjernelse af model, skal du se Fjernelse af model.

Tidsgrænser for opdateringshandlinger

Den maksimale mængde tid for en enkelt opdateringshandling er fem timer. Hvis opdateringshandlingen ikke fuldføres inden for grænsen på fem timer og retryCount ikke er angivet eller er angivet som 0 (standarden) i anmodningens brødtekst, returneres der en timeoutfejl.

Hvis retryCount angiver 1 eller et andet tal, starter en ny opdateringshandling med en grænse på fem timer. Hvis denne forsøgshandling mislykkes, fortsætter tjenesten med at forsøge opdateringshandlingen igen op til det største antal forsøg, der retryCount angiver, eller den udvidede tidsgrænse for behandling af opdateringer på 24 timer fra starten af den første opdateringsanmodning.

Når du planlægger din forbedrede modelopdateringsløsning med REST API'en Opdater datasæt, er det vigtigt at overveje disse tidsgrænser og parameteren retryCount . En vellykket fuldførelse af opdateringen kan overstige fem timer, hvis en indledende opdatering mislykkes og retryCount angiver 1 eller mere.

Hvis du f.eks. anmoder om en opdateringshandling med "retryCount": 1, og den første forsøgshandling mislykkes fire timer fra starttidspunktet, starter en anden opdateringshandling for den pågældende anmodning. Hvis den anden opdateringshandling lykkes om tre timer, er den samlede tid for vellykket udførelse af opdateringsanmodningen syv timer.

Hvis opdateringshandlinger jævnligt mislykkes, overskrider tidsgrænsen på fem timer eller overskrider den ønskede vellykkede opdateringstid, kan du overveje at reducere mængden af data, der opdateres fra datakilden. Du kan opdele opdatering i flere anmodninger, f.eks. en anmodning for hver tabel. Du kan også angive partialBatch i parameteren commitMode .

Kodeeksempel

Hvis du vil have et C#-kodeeksempel for at komme i gang, skal du se RestApiSample på GitHub.

Sådan bruger du kodeeksemplet:

  1. Klon eller download lageret.
  2. Åbn RestApiSample-løsningen.
  3. Find linjen client.BaseAddress = … , og angiv din grundlæggende URL-adresse.

Kodeeksemplet bruger godkendelse af tjenesteprincipal.

Relateret indhold