Del via

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 forbedrede med REST API'en flere tilpasningsmuligheder 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
  • Timeoutkonfiguration

Seddel

  • 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.

Grundlæggende URL-adresse

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ætog opdateringersamlinger. , Datasætog Opdater er objekter.

diagram, der viser asynkront opdateringsflow.

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 tilladelsesomfang.

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.

Seddel

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 status 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,
    "timeout": "02:00:00",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Seddel

Tjenesten accepterer kun én opdateringshandling ad gangen for en model. Hvis der er en aktuel igangvæ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.

Navn Slags Standard Beskrivelse
type Optæller automatic Den type behandling, der skal udføres. Typerne justeres i forhold til TMSL-opdateringskommandotyperne: full, clearValues, calculate, dataOnly, automaticog defragment. Den add type understøttes ikke.
commitMode Optæller 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 sker opdateringshandlingen 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 egenskaben MaxParallelism, der kan angives i kommandoen TMSL-Sequence eller ved hjælp af andre metoder.
retryCount Int 0 Det antal gange, handlingen forsøger igen, før der mislykkes.
objects Array Hele modellen En matrix af objekter, der skal behandles. Hvert objekt omfatter table, når en hel tabel behandles, eller table og partition, når der behandles en partition. Hvis der ikke er angivet nogen objekter, opdateres hele modellen.
applyRefreshPolicy Boolesk 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, kan applyRefreshPolicy være true eller false. Hvis commitMode er partialBatch, understøttes applyRefreshPolicy af true ikke, og applyRefreshPolicy skal angives til false.
effectiveDate Dato Dags dato Hvis der anvendes en politik for trinvis opdatering, tilsidesætter parameteren effectiveDate den aktuelle dato. Hvis den ikke er angivet, bestemmes den aktuelle dag ved hjælp af tidszonekonfigurationen under 'Opdater'.
timeout Streng 05:00:00 (5 timer) Hvis der er angivet en timeout, overholder hvert forsøg på opdatering af data på den semantiske model denne timeout. En enkelt opdateringsanmodning kan omfatte flere forsøg, hvis retryCount er angivet, hvilket kan medføre, at den samlede opdateringsvarighed overskrider den angivne timeout. Hvis du f.eks. angiver en timeout på 1 time med en retryCount på 2, kan det resultere i en samlet opdateringsvarighed på op til 3 timer. Brugerne kan justere timeout for at forkorte opdateringsvarigheden for hurtigere registrering af fejl eller udvide den ud over standarden på 5 timer for mere komplekse dataopdateringer. Den samlede opdateringsvarighed, herunder nye forsøg, må dog ikke overstige 24 timer.

Svar

202 Accepted

Svaret indeholder også et Location felt med svarheaderen for at pege kalderen på den opdateringshandling, der blev oprettet og accepteret. Den Location er placeringen af den nye ressource, som anmodningen oprettede, hvilket omfatter de requestId, som nogle forbedrede opdateringshandlinger kræver. I følgende svar er requestId 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",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Seddel

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.

Egenskaber for svar

Navn Slags Beskrivelse
requestId Guid Id'et for opdateringsanmodningen. Du skal requestId for at forespørge om status for individuel opdateringshandling eller annullere en igangværende opdateringshandling.
refreshType Streng 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 Streng Dato og klokkeslæt for opdateringsstart.
endTime Streng Dato og klokkeslæt for opdateringsafslutning.
status Streng Completed angiver, at opdateringshandlingen blev fuldført.
Failed angiver, at opdateringshandlingen mislykkedes.
Unknown angiver, at fuldførelsestilstanden ikke kan bestemmes. Med denne status er endTime tom.
Disabled angiver, at opdateringen blev deaktiveret af selektiv opdatering.
Cancelled angiver, at opdateringen blev annulleret.
extendedStatus Streng Forøger egenskaben status for at give flere oplysninger.

Seddel

I Azure Analysis Services er det fuldførte status resultat succeeded. 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, returnerer statusInProgresssom 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.

For 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 modelopdateringer eller opdateringer efter behov, der blev udløst, ved at vælge knappen Opdater på portalen ved hjælp af DELETE /refreshes/<requestId>.
  • Planlagte og on-demand-modelopdateringer, der blev udløst ved at vælge opdateringsknappen på portalen, understøtter ikke hentning af oplysninger om opdateringshandlinger ved hjælp af GET /refreshes/<requestId>.
  • 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 status for en igangværende udvidet opdateringshandling InProgress 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

En opdateringshandling kan omfatte flere forsøg, hvis retryCount er angivet. Hvert forsøg har en standardtimeout på 5 timer, som kan justeres ved hjælp af parameteren timeout. Den samlede opdateringsvarighed, herunder nye forsøg, må ikke overstige 24 timer.

Hvis retryCount angiver et tal, starter en ny opdateringshandling med timeoutgrænsen. Tjenesten udfører handlingen igen, indtil den enten lykkes, når grænsen for retryCount eller når maksimum på 24 timer fra det første forsøg.

Du kan justere timeout for at forkorte opdateringsvarigheden for hurtigere registrering af fejl eller udvide den til mere end standard fem timer for mere komplekse dataopdateringer.

Når du planlægger din semantiske modelopdatering med REST API'en Opdater datasæt, skal du overveje tidsgrænser og parameteren retryCount. En opdatering kan overskride timeout, hvis det første forsøg mislykkes, og forsøgCount er angivet til 1 eller mere. Hvis du anmoder om en opdatering med "retryCount": 1, og det første forsøg mislykkes efter 4 timer, begynder et andet forsøg. Hvis dette lykkes om 3 timer, er den samlede tid for opdateringen 7 timer.

Hvis opdateringshandlinger jævnligt mislykkes, overskrider timeouttidsgrænsen eller overskrider den ønskede tid for den ønskede opdateringshandling, 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 url-adressen til .

Kodeeksemplet bruger godkendelse af tjenesteprincipal.

Relateret indhold