Del via

Forbedret oppdatering med REST-API-en for Power BI

  • Artikkel

Du kan bruke et hvilket som helst programmeringsspråk som støtter REST-kall til å utføre semantiske modelloppdateringsoperasjoner ved hjelp av REST-API-en for Power BI Refresh Dataset.

Optimalisert oppdatering for store og komplekse partisjonerte modeller aktiveres tradisjonelt med programmeringsmetoder som bruker TOM (tabellobjektmodell), PowerShell-cmdleter eller TMSL (tabellmodellskriptspråk). Disse metodene krever imidlertid langvarige HTTP-tilkoblinger som kan være upålitelige.

REST-API-en for Oppdateringsdatasett for Power BI kan utføre modelloppdateringsoperasjoner asynkront, slik at langvarige HTTP-tilkoblinger fra klientprogrammer ikke er nødvendige. Sammenlignet med standard oppdateringsoperasjoner gir forbedret oppdatering med REST-API-en flere tilpasningsalternativer og følgende funksjoner som er nyttige for store modeller:

  • Satsvise utføringer
  • Oppdatering på tabell- og partisjonsnivå
  • Bruke policyer for trinnvis oppdatering
  • GET oppdateringsdetaljer
  • Oppdater avlysning
  • Tidsavbruddskonfigurasjon

Notat

  • Tidligere ble forbedret oppdatering kalt asynkron oppdatering med REST-API-. En standardoppdatering som bruker REST-API-en for oppdateringsdatasett, kjører imidlertid også asynkront av sin iboende natur.
  • Forbedrede oppdateringsoperasjoner for REST-API for Power BI oppdaterer ikke flisbuffere automatisk. Flisen bufrer bare oppdatering når en bruker får tilgang til en rapport.

Grunnleggende URL-adresse

Den grunnleggende URL-adressen er i følgende format:

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

Du kan tilføye ressurser og operasjoner til den grunnleggende URL-adressen basert på parametere. I diagrammet nedenfor er Grupper, Datasettog Oppdateringersamlinger. Grupper, Datasettog Oppdater er objekter.

diagram som viser asynkron oppdateringsflyt.

Krav

Du trenger følgende krav for å bruke REST-API-en:

  • En semantisk modell i Power BI Premium, Premium per bruker eller Power BI Embedded.
  • En gruppe-ID og datasett-ID som skal brukes i url-adressen for forespørselen.
  • Dataset.ReadWrite.All tillatelsesomfang.

Antall oppdateringer er begrenset i henhold til de generelle begrensningene for API-baserte oppdateringer for Pro- og Premium-modeller.

Godkjenning

Alle kall må godkjennes med et gyldig OAuth 2-token for Microsoft Entra ID i autorisasjonshodet. Tokenet må oppfylle følgende krav:

  • Enten være et brukertoken eller en programtjenestekontohaver.
  • Få målgruppen riktig satt til https://api.powerbi.com.
  • Brukes av en bruker eller et program som har tilstrekkelige tillatelser på modellen.

Notat

REST-API-endringer endrer ikke gjeldende definerte tillatelser for modelloppdateringer.

POST /refreshes

Hvis du vil gjøre en oppdatering, bruker du POST-verbet i /refreshes-samlingen til å legge til et nytt oppdateringsobjekt i samlingen. Plasseringshodet i svaret inkluderer requestId. Fordi operasjonen er asynkron, kan et klientprogram koble fra og bruke requestId til å kontrollere statusen senere om nødvendig.

Følgende kode viser en eksempelforespørsel:

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

Forespørselsteksten kan ligne på følgende eksempel:

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

Notat

Tjenesten godtar bare én oppdateringsoperasjon om gangen for en modell. Hvis det er en gjeldende oppdatering som kjører og en annen forespørsel sendes inn, returneres en 400 Bad Request HTTP-statuskode.

Parametere

Hvis du vil utføre en forbedret oppdateringsoperasjon, må du angi én eller flere parametere i forespørselsteksten. Angitte parametere kan angi standardverdien eller en valgfri verdi. Når forespørselen angir parametere, gjelder alle andre parametere for operasjonen med standardverdiene. Hvis forespørselen ikke angir noen parametere, bruker alle parameterne standardverdiene, og en standard oppdateringsoperasjon utføres.

Navn Type Standard Beskrivelse
type Opplisting automatic Behandlingstypen som skal utføres. Typer justeres etter kommandotypene for TMSL-oppdatering: full, clearValues, calculate, dataOnly, automaticog defragment. Den add typen støttes ikke.
commitMode Opplisting transactional Bestemmer om objekter skal utføres i grupper eller bare når de er fullført. Modi er transactional og partialBatch. Når du bruker partialBatch skjer ikke oppdateringsoperasjonen innenfor én transaksjon. Hver kommando utføres enkeltvis. Hvis det oppstår en feil, kan modellen være tom eller bare inneholde et delsett av dataene. Hvis du vil beskytte mot feil og beholde dataene som var i modellen før operasjonen startet, utfører du operasjonen med commitMode = transactional.
maxParallelism Int 10 Bestemmer maksimalt antall tråder som kan kjøre behandlingskommandoene parallelt. Denne verdien justeres etter MaxParallelism egenskap som kan angis i TMSL-Sequence-kommandoen eller ved hjelp av andre metoder.
retryCount Int 0 Antall ganger operasjonen utføres på nytt før den mislykkes.
objects Matrise Hele modellen En matrise med objekter som skal behandles. Hvert objekt inneholder table når du behandler en hel tabell, eller table og partition når du behandler en partisjon. Hvis ingen objekter er angitt, oppdateres hele modellen.
applyRefreshPolicy Boolsk true Hvis en policy for trinnvis oppdatering er definert, bestemmer du om policyen skal brukes. Moduser er true eller false. Hvis policyen ikke brukes, lar hele prosessen partisjonsdefinisjonene være uendret, og alle partisjoner oppdateres fullstendig i tabellen.

Hvis commitMode er transactional, kan applyRefreshPolicy være true eller false. Hvis commitMode er partialBatch, støttes ikke applyRefreshPolicy av true, og applyRefreshPolicy må settes til false.
effectiveDate Daddel Gjeldende dato Hvis en policy for trinnvis oppdatering brukes, overstyrer effectiveDate-parameteren gjeldende dato. Hvis ikke angitt, bestemmes gjeldende dag ved hjelp av tidssonekonfigurasjon under Oppdater.
timeout Streng 05:00:00 (5 timer) Hvis en timeout er angitt, følger hvert dataoppdateringsforsøk på den semantiske modellen denne tidsavbruddet. En enkelt oppdateringsforespørsel kan inneholde flere forsøk hvis retryCount er angitt, noe som kan føre til at den totale oppdateringsvarigheten overskrider det angitte tidsavbruddet. Hvis du for eksempel angir en timeout på 1 time med en retryCount på 2, kan det føre til en total varighet på opptil 3 timer. Brukere kan justere timeout for å forkorte oppdateringsvarigheten for raskere feilgjenkjenning eller utvide den utover standard fem timer for mer komplekse dataoppdateringer. Den totale oppdateringsvarigheten, inkludert nye forsøk, kan imidlertid ikke overstige 24 timer.

Svar

202 Accepted

Svaret inkluderer også et Location svarhodefelt for å peke innringeren til oppdateringsoperasjonen som ble opprettet og godtatt. Den Location er plasseringen til den nye ressursen forespørselen opprettet, som inkluderer requestId som noen forbedrede oppdateringsoperasjoner krever. I følgende svar er for eksempel requestId den siste identifikatoren 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 /oppdater

Bruk GET-verbet i /refreshes-samlingen til å vise historiske, gjeldende og ventende oppdateringsoperasjoner.

Svarteksten kan se ut som 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"
    }
]

Notat

Power BI kan droppe forespørsler hvis det er for mange forespørsler på kort tid. Power BI gjør en oppdatering, setter den neste forespørselen i kø og slipper alle andre. Etter utforming kan du ikke spørre om status for tapte forespørsler.

Svaregenskaper

Navn Type Beskrivelse
requestId Guid Identifikatoren for oppdateringsforespørselen. Du må requestId spørre etter status for individuell oppdateringsoperasjon eller avbryte en pågående oppdateringsoperasjon.
refreshType Streng OnDemand indikerer at oppdateringen ble utløst interaktivt gjennom Power BI-portalen.
Scheduled indikerer at en modelloppdateringsplan utløste oppdateringen.
ViaApi indikerer at et API-kall utløste oppdateringen.
ViaEnhancedApi indikerer at et API-kall utløste en forbedret oppdatering.
startTime Streng Dato og klokkeslett for oppdateringsstart.
endTime Streng Dato og klokkeslett for oppdateringsslutt.
status Streng Completed indikerer at oppdateringsoperasjonen er fullført.
Failed indikerer at oppdateringsoperasjonen mislyktes.
Unknown indikerer at fullføringstilstanden ikke kan fastslås. Med denne statusen er endTime tom.
Disabled indikerer at oppdateringen ble deaktivert ved selektiv oppdatering.
Cancelled indikerer at oppdateringen ble avbrutt.
extendedStatus Streng Utvider status-egenskapen for å gi mer informasjon.

Notat

I Azure Analysis Services er det fullførte status resultatet succeeded. Hvis du overfører en Azure Analysis Services-løsning til Power BI, må du kanskje endre løsningene dine.

Begrens antall oppdateringsoperasjoner som returneres

REST-API-en for Power BI støtter begrensning av det forespurte antallet oppføringer i oppdateringsloggen ved hjelp av den valgfrie $top-parameteren. Hvis ikke angitt, er standardoppføringene alle tilgjengelige oppføringer.

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

HENt /oppdater/<requestId>

Hvis du vil kontrollere statusen for en oppdateringsoperasjon, bruker du GET-verbet på oppdateringsobjektet ved å angi requestId. Hvis operasjonen pågår, returnerer statusInProgress, som i følgende eksempel på svartekst:

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

SLETT /oppdater/<requestId>

Hvis du vil avbryte en forbedret oppdateringsoperasjon som pågår, bruker du DELETE-verbet på oppdateringsobjektet ved å angi 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

Hensyn og begrensninger

Oppdateringsoperasjonen har følgende vurderinger og begrensninger:

Standard oppdateringsoperasjoner

  • Du kan ikke avbryte planlagte eller behovsbetingede modelloppdateringer som ble utløst ved å velge oppdateringsknappen i portalen ved hjelp av DELETE /refreshes/<requestId>.
  • Planlagte og behovsbetingede modelloppdateringer som ble utløst ved å velge oppdateringsknappen i portalen, støtter ikke å få oppdateringsoperasjonsdetaljer ved hjelp av GET /refreshes/<requestId>.
  • Få detaljer, og Avbryt er bare nye operasjoner for forbedret oppdatering. Standardoppdatering støtter ikke disse operasjonene.

Power BI Embedded

Hvis kapasiteten er midlertidig stanset manuelt i Power BI-portalen eller ved hjelp av PowerShell, eller et systemavbrudd oppstår, forblir statusen for en kontinuerlig forbedret oppdateringsoperasjon InProgress i maksimalt seks timer. Hvis kapasiteten gjenopptas innen seks timer, gjenopptas oppdateringsoperasjonen automatisk. Hvis kapasiteten gjenopptas etter mer enn seks timer, kan oppdateringsoperasjonen returnere en tidsavbruddsfeil. Deretter må du starte oppdateringsoperasjonen på nytt.

Utestengelse av semantisk modell

Power BI bruker dynamisk minnebehandling til å optimalisere kapasitetsminnet. Hvis modellen utestenges fra minnet under en oppdateringsoperasjon, kan følgende feil returneres:

{
    "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 å kjøre oppdateringsoperasjonen på nytt. Hvis du vil lære mer om dynamisk minnebehandling og modellutkastelse, kan du se Modellutkastelse.

Tidsbegrensninger for oppdatering av operasjon

En oppdateringsoperasjon kan inneholde flere forsøk hvis retryCount er angitt. Hvert forsøk har et standard tidsavbrudd på 5 timer, som kan justeres ved hjelp av timeout-parameteren. Den totale oppdateringsvarigheten, inkludert nye forsøk, må ikke overstige 24 timer.

Hvis retryCount angir et tall, starter en ny oppdateringsoperasjon med tidsavbruddsgrensen. Tjenesten starter denne operasjonen på nytt til den enten lykkes, når retryCount grensen, eller når maksimumsgrensen på 24 timer fra det første forsøket.

Du kan justere timeout for å forkorte oppdateringsvarigheten for raskere feilgjenkjenning eller utvide den utover standard fem timer for mer komplekse dataoppdateringer.

Når du planlegger semantisk modelloppdatering med REST-API-en for oppdatering av datasett, bør du vurdere tidsbegrensninger og parameteren RetryCount. En oppdatering kan overskride tidsavbruddet hvis det første forsøket mislykkes, og antall forsøk på nytt er satt til 1 eller flere. Hvis du ber om en oppdatering med «retryCount»: 1, og det første forsøket mislykkes etter 4 timer, begynner et nytt forsøk. Hvis dette lykkes om 3 timer, er den totale tiden for oppdateringen 7 timer.

Hvis oppdateringsoperasjoner regelmessig mislykkes, overskrider tidsbegrensningen for tidsavbrudd eller overskrider ønsket driftstid for vellykket oppdatering, bør du vurdere å redusere mengden data som oppdateres fra datakilden. Du kan dele oppdateringer i flere forespørsler, for eksempel en forespørsel for hver tabell. Du kan også angi partialBatch i commitMode-parameteren.

Kodeeksempel

Hvis du vil ha et C#-kodeeksempel for å komme i gang, kan du se RestApiSample på GitHub.

Slik bruker du kodeeksempelet:

  1. Klon eller last ned repo.
  2. Åpne RestApiSample-løsningen.
  3. Finn linjen client.BaseAddress = …, og angi den grunnleggende URL-adressen.

Kodeeksempelet bruker godkjenning av tjenestekontohaver.

Relatert innhold