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

Merk

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

Primær nettadresse

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, datasett og oppdateringer samlinger. Gruppe, Datasett og Oppdater er objekter.

Diagram that shows asynchronous refresh flow.

Forutsetninger

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.
  • Datasett.ReadWrite.All tillatelsesomfang.

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

Autentisering

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.
  • La målgruppen være riktig satt til https://api.powerbi.com.
  • Brukes av en bruker eller et program som har tilstrekkelige tillatelser på modellen.

Merk

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

Merk

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 Default Bekrivelse
type Opplisting automatic Behandlingstypen som skal utføres. Typer justeres etter kommandotypene for TMSL-oppdatering: full, , clearValuescalculate, dataOnly, automaticog defragment. Typen add støttes ikke.
commitMode Opplisting transactional Bestemmer om objekter skal utføres i grupper eller bare når de er fullført. Moduser er transactional og partialBatch. Når du bruker partialBatch oppdateringsoperasjonen, forekommer ikke 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 egenskapen som kan angis i TMSL-kommandoen Sequence 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 inkluderer table når du behandler en hel tabell, eller table når partition du behandler en partisjon. Hvis ingen objekter er angitt, oppdateres hele modellen.
applyRefreshPolicy Boolean 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, applyRefreshPolicy kan være true eller false. Hvis commitMode er partialBatch, applyRefreshPolicy støttes true ikke av, og applyRefreshPolicy må settes til false.
effectiveDate Dato Gjeldende dato Hvis en policy for trinnvis oppdatering brukes, effectiveDate overstyrer parameteren gjeldende dato. Hvis ikke angitt, brukes UTC til å bestemme gjeldende dag.

Response

202 Accepted

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

Merk

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 Bekrivelse
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 angir at oppdateringen ble utløst interaktivt gjennom Power BI-portalen.
Scheduled angir at en tidsplan for modelloppdatering utløste oppdateringen.
ViaApi angir at et API-kall utløste oppdateringen.
ViaEnhancedApi angir 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 angir at oppdateringsoperasjonen er fullført.
Failed angir at oppdateringsoperasjonen mislyktes.
Unknown angir at fullføringstilstanden ikke kan fastslås. Med denne statusen endTime er tom.
Disabled angir at oppdateringen ble deaktivert ved selektiv oppdatering.
Cancelled angir at oppdateringen ble avbrutt.
extendedStatus Streng Utvider status egenskapen for å gi mer informasjon.

Merk

I Azure Analysis Services er succeededdet fullførte status resultatet . 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 å requestIdangi . Hvis operasjonen pågår, status returneres InProgress, 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"
        }
    ]
}

DELETE /refreshes/<requestId>

Hvis du vil avbryte en pågående forbedret oppdateringsoperasjon, bruker du DELETE-verbet på oppdateringsobjektet ved å requestIdangi .

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 manuelle modelloppdateringer ved hjelp DELETE /refreshes/<requestId>av .
  • Planlagte og behovsbetingede manuelle modelloppdateringer støtter ikke å få oppdateringsoperasjonsdetaljer ved hjelp GET /refreshes/<requestId>av .
  • 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 en systemavbrudd oppstår, forblir InProgress statusen for en kontinuerlig forbedret oppdateringsoperasjon 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 modellutkasting, kan du se Modellutkastelse.

Tidsbegrensninger for oppdatering av operasjon

Maksimal tid for én enkelt oppdateringsoperasjon er fem timer. Hvis oppdateringsoperasjonen ikke fullføres innen femtimersgrensen, og retryCount ikke er angitt eller er angitt som 0 (standard) i forespørselsteksten, returneres en tidsavbruddsfeil.

Hvis retryCount angir 1 eller et annet tall, starter en ny oppdateringsoperasjon med en fem timers grense. Hvis denne operasjonen mislykkes, fortsetter tjenesten å prøve oppdateringsoperasjonen på nytt opptil det største antallet nye forsøk som retryCount angir, eller den utvidede tidsgrensen for oppdateringsbehandling på 24 timer fra begynnelsen av den første oppdateringsforespørselen.

Når du planlegger den forbedrede modelloppdateringsløsningen med REST-API-en for oppdatering av datasett, er det viktig å vurdere disse tidsbegrensningene og parameteren retryCount . En vellykket fullføring av oppdatering kan overskride fem timer hvis en første oppdateringsoperasjon mislykkes og retryCount angir 1 eller mer.

Hvis du for eksempel ber om en oppdateringsoperasjon med "retryCount": 1, og den første prøveoperasjonen mislykkes fire timer fra starttidspunktet, starter en ny oppdateringsoperasjon for forespørselen. Hvis den andre oppdateringsoperasjonen lykkes på tre timer, er den totale tiden for vellykket kjøring av oppdateringsforespørselen sju timer.

Hvis oppdateringsoperasjoner regelmessig mislykkes, overskrider femtimers tidsgrensen eller overskrider ønsket driftstid for vellykket oppdatering, bør du vurdere å redusere datamengden 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 parameteren commitMode .

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 oppgi den grunnleggende URL-adressen.

Kodeeksempelet bruker godkjenning av tjenestekontohaver.

Relatert innhold