Dela via

Förbättrad uppdatering med Power BI REST API

  • Artikel

Du kan använda valfritt programmeringsspråk som stöder REST-anrop för att utföra semantiska modelluppdateringsåtgärder med hjälp av REST-API:et för Power BI-uppdateringsdatauppsättning.

Optimerad uppdatering för stora och komplexa partitionerade modeller anropas traditionellt med programmeringsmetoder som använder TOM (tabellobjektmodell), PowerShell-cmdletar eller TMSL (skriptspråk för tabellmodell). Dessa metoder kräver dock långvariga HTTP-anslutningar som kan vara otillförlitliga.

Rest-API:et för Power BI-uppdateringsdatauppsättningen kan utföra modelluppdateringsåtgärder asynkront, så tidskrävande HTTP-anslutningar från klientprogram är inte nödvändiga. Jämfört med standarduppdateringsåtgärder ger förbättrad uppdatering med REST-API:et fler anpassningsalternativ och följande funktioner som är användbara för stora modeller:

  • Batchincheckningar
  • Uppdatering på tabell- och partitionsnivå
  • Tillämpa inkrementella uppdateringsprinciper
  • GET uppdatera information
  • Avbokning av uppdatering

Kommentar

  • Tidigare kallades förbättrad uppdatering för asynkron uppdatering med REST API. Men en standarduppdatering som använder REST-API:et Uppdatera datauppsättning körs också asynkront på grund av dess inneboende natur.
  • Förbättrade power BI REST API-uppdateringsåtgärder uppdaterar inte panelcacheminnen automatiskt. Panelen cachelagrar uppdatering endast när en användare kommer åt en rapport.

Bas-URL

Bas-URL:en har följande format:

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

Du kan lägga till resurser och åtgärder i bas-URL:en baserat på parametrar. I följande diagram är grupper, datauppsättningar och uppdateringar samlingar. Grupp, datauppsättning och uppdatering är objekt.

Diagram that shows asynchronous refresh flow.

Behov

Du behöver följande krav för att använda REST-API:et:

  • En semantisk modell i Power BI Premium, Premium per användare eller Power BI Embedded.
  • Ett grupp-ID och datamängds-ID som ska användas i begärande-URL:en.
  • Dataset.ReadWrite.All behörighetsomfång.

Antalet uppdateringar är begränsat enligt de allmänna begränsningarna för API-baserade uppdateringar för Pro- och Premium-modeller.

Autentisering

Alla anrop måste autentiseras med en giltig Microsoft Entra ID OAuth 2-token i auktoriseringshuvudet. Token måste uppfylla följande krav:

  • Vara antingen en användartoken eller ett huvudnamn för programtjänsten.
  • Låt målgruppen vara korrekt inställd på https://api.powerbi.com.
  • Används av en användare eller ett program som har tillräcklig behörighet för modellen.

Kommentar

REST API-ändringar ändrar inte för närvarande definierade behörigheter för modelluppdateringar.

POST /refreshes

Om du vill göra en uppdatering använder du POST-verbet i samlingen /refreshes för att lägga till ett nytt uppdateringsobjekt i samlingen. Platsrubriken i svaret innehåller requestId. Eftersom åtgärden är asynkron kan ett klientprogram koppla från och använda requestId för att kontrollera statusen senare om det behövs.

Följande kod visar en exempelbegäran:

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

Begärandetexten kan likna följande exempel:

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

Kommentar

Tjänsten accepterar endast en uppdateringsåtgärd i taget för en modell. Om det finns en aktuell uppdatering som körs och en annan begäran skickas returnerar en 400 Bad Request HTTP-statuskod.

Parametrar

Om du vill utföra en förbättrad uppdateringsåtgärd måste du ange en eller flera parametrar i begärandetexten. Angivna parametrar kan ange standardvärdet eller ett valfritt värde. När begäran anger parametrar gäller alla andra parametrar för åtgärden med deras standardvärden. Om begäran inte anger några parametrar använder alla parametrar sina standardvärden och en standarduppdateringsåtgärd utförs.

Namn Type Standardvärde beskrivning
type Enum automatic Vilken typ av bearbetning som ska utföras. Typerna överensstämmer med TMSL-uppdateringskommandotyperna: full, clearValues, calculate, dataOnly, automaticoch defragment. Typen add stöds inte.
commitMode Enum transactional Avgör om objekt ska checkas in i batchar eller bara när de är klara. Lägen är transactional och partialBatch. När du använder partialBatch uppdateringsåtgärden sker inte inom en transaktion. Varje kommando checkas in individuellt. Om det uppstår ett fel kan modellen vara tom eller bara innehålla en delmängd av data. För att skydda mot fel och behålla de data som fanns i modellen innan åtgärden startade kör du åtgärden med commitMode = transactional.
maxParallelism Int 10 Avgör det maximala antalet trådar som kan köra bearbetningskommandona parallellt. Det här värdet överensstämmer med egenskapen MaxParallelism som kan anges i TMSL-kommandot Sequence eller med hjälp av andra metoder.
retryCount Int 0 Antal gånger åtgärden försöker igen innan den misslyckas.
objects Matris Hela modellen En matris med objekt som ska bearbetas. Varje objekt inkluderar table när en hel tabell bearbetas eller tablepartition när en partition bearbetas. Om inga objekt anges uppdateras hela modellen.
applyRefreshPolicy Booleskt true Om en inkrementell uppdateringsprincip har definierats avgör du om principen ska tillämpas. Lägen är true eller false. Om principen inte tillämpas lämnar den fullständiga processen partitionsdefinitionerna oförändrade och uppdaterar alla partitioner i tabellen fullständigt.

Om commitMode är transactional, applyRefreshPolicy kan vara true eller false. Om commitMode är partialBatchstöds applyRefreshPolicy inte av true och applyRefreshPolicy måste anges till false.
effectiveDate Datum Aktuellt datum Om en inkrementell uppdateringsprincip tillämpas åsidosätter parametern effectiveDate det aktuella datumet. Om det inte anges används UTC för att fastställa den aktuella dagen.

Response

202 Accepted

Svaret innehåller också ett Location svarshuvudfält som pekar anroparen på uppdateringsåtgärden som skapades och accepterades. Location är platsen för den nya resursen som begäran skapades, vilket inkluderar den requestId som vissa förbättrade uppdateringsåtgärder kräver. I följande svar requestId är till exempel den sista identifieraren 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

GET/refreshes

Använd GET-verbet i samlingen /refreshes för att visa historiska, aktuella och väntande uppdateringsåtgärder.

Svarstexten kan se ut som i följande exempel:

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

Kommentar

Power BI kan ta bort begäranden om det finns för många begäranden på kort tid. Power BI gör en uppdatering, köar nästa begäran och släpper alla andra. Du kan inte fråga efter status för borttagna begäranden.

Svarsegenskaper

Namn Type Beskrivning
requestId GUID Identifieraren för uppdateringsbegäran. Du måste requestId fråga efter status för enskilda uppdateringar eller avbryta en pågående uppdateringsåtgärd.
refreshType String OnDemand anger att uppdateringen utlöstes interaktivt via Power BI-portalen.
Scheduled anger att ett modelluppdateringsschema utlöste uppdateringen.
ViaApi anger att ett API-anrop utlöste uppdateringen.
ViaEnhancedApi anger att ett API-anrop utlöste en förbättrad uppdatering.
startTime String Datum och tid för uppdateringsstart.
endTime String Datum och tid för uppdateringsslut.
status String Completed anger att uppdateringsåtgärden har slutförts.
Failed anger att uppdateringsåtgärden misslyckades.
Unknown anger att slutförandetillståndet inte kan fastställas. Med den här statusen endTime är den tom.
Disabled anger att uppdateringen inaktiverades av selektiv uppdatering.
Cancelled anger att uppdateringen avbröts.
extendedStatus String Utökar egenskapen status för att ge mer information.

Kommentar

I Azure Analysis Services är succeededdet slutförda status resultatet . Om du migrerar en Azure Analysis Services-lösning till Power BI kan du behöva ändra dina lösningar.

Begränsa antalet returnerade uppdateringsåtgärder

Power BI REST API stöder begränsning av det begärda antalet poster i uppdateringshistoriken med hjälp av den valfria $top parametern. Om det inte anges är standardvärdet alla tillgängliga poster.

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

GET /refreshes/<requestId>

Om du vill kontrollera status för en uppdateringsåtgärd använder du GET-verbet på uppdateringsobjektet genom att requestIdange . Om åtgärden pågår status returnerar InProgress, som i följande exempelsvarstext:

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

Om du vill avbryta en pågående förbättrad uppdateringsåtgärd använder du DELETE-verbet på uppdateringsobjektet genom att requestIdange .

Exempel:

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

Beaktanden och begränsningar

Uppdateringsåtgärden har följande överväganden och begränsningar:

Standarduppdateringsåtgärder

  • Du kan inte avbryta schemalagda eller manuella modelluppdateringar på begäran med hjälp DELETE /refreshes/<requestId>av .
  • Schemalagda och manuella modelluppdateringar på begäran stöder inte uppdateringsåtgärdsinformation med hjälp GET /refreshes/<requestId>av .
  • Hämta information och Avbryt är bara nya åtgärder för förbättrad uppdatering. Standarduppdateringen stöder inte dessa åtgärder.

Power BI Embedded

Om kapaciteten pausas manuellt i Power BI-portalen eller med hjälp av PowerShell, eller om ett systemstopp inträffar, förblir statusen för pågående förbättrad uppdateringsåtgärd i InProgress högst sex timmar. Om kapaciteten återupptas inom sex timmar återupptas uppdateringsåtgärden automatiskt. Om kapaciteten återupptas efter mer än sex timmar kan uppdateringsåtgärden returnera ett timeoutfel. Sedan måste du starta om uppdateringsåtgärden.

Avhysning av semantisk modell

Power BI använder dynamisk minneshantering för att optimera kapacitetsminnet. Om modellen tas bort från minnet under en uppdateringsåtgärd kan följande fel returneras:

{
    "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 är att köra uppdateringsåtgärden igen. Mer information om dynamisk minneshantering och modellavhysning finns i Modellavhysning.

Tidsgränser för uppdateringsåtgärd

Den maximala tiden för en enskild uppdateringsåtgärd är fem timmar. Om uppdateringsåtgärden inte har slutförts inom femtimmarsgränsen och retryCount inte har angetts eller anges som 0 (standard) i begärandetexten returneras ett timeout-fel.

Om retryCount anger 1 eller ett annat tal startar en ny uppdateringsåtgärd med en gräns på fem timmar. Om den här återförsöksåtgärden misslyckas fortsätter tjänsten att försöka uppdatera igen upp till det största antalet återförsök som retryCount anger, eller den utökade tidsgränsen för uppdateringsbearbetning på 24 timmar från början av den första uppdateringsbegäran.

När du planerar din förbättrade modelluppdateringslösning med REST-API:et Uppdatera datauppsättning är det viktigt att tänka på dessa tidsgränser och parametern retryCount . En lyckad uppdatering kan överstiga fem timmar om en inledande uppdatering misslyckas och retryCount anger 1 eller mer.

Om du till exempel begär en uppdateringsåtgärd med "retryCount": 1, och den första återförsöksåtgärden misslyckas fyra timmar från starttiden, påbörjas en andra uppdateringsåtgärd för den begäran. Om den andra uppdateringsåtgärden lyckas på tre timmar är den totala tiden för lyckad körning av uppdateringsbegäran sju timmar.

Om uppdateringsåtgärder regelbundet misslyckas, överskrider tidsgränsen på fem timmar eller överskrider önskad lyckad uppdateringsåtgärd kan du överväga att minska mängden data som uppdateras från datakällan. Du kan dela upp uppdateringen i flera begäranden, till exempel en begäran för varje tabell. Du kan också ange partialBatch i parametern commitMode .

Kodexempel

Ett C#-kodexempel för att komma igång finns i RestApiSample på GitHub.

Så här använder du kodexemplet:

  1. Klona eller ladda ned lagringsplatsen.
  2. Öppna RestApiSample-lösningen.
  3. Leta upp raden client.BaseAddress = … och ange din bas-URL.

Kodexemplet använder autentisering med tjänstens huvudnamn.

Relaterat innehåll