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 detaljer
  • Annullering av omladdning
  • Timeout-konfiguration

Not

  • Tidigare kallades förbättrad uppdatering 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 plattcachar automatiskt. Kachelcacher uppdateras 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ättningaroch Uppdateringarsamlingar. Group, Datasetoch Refresh är objekt.

diagram som visar asynkront uppdateringsflöde.

Krav

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 en applikationstjänsthuvudansvarig.
  • Se till att målgruppen är 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.

Not

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

POST /uppdateringar

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

Notera

Tjänsten accepterar endast en uppdateringsåtgärd i taget för en modell. Om det finns en pågående uppdatering och en annan begäran skickas in returneras 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 Typ Förvalt Beskrivning
type Enum automatic Vilken typ av bearbetning som ska utföras. Typerna överensstämmer med TMSL-uppdateringskommandotyperna: full, clearValues, calculate, dataOnly, automaticoch defragment. Den add typen stöds inte.
commitMode Räkna upp transactional Avgör om objekt ska sparas i batchar eller endast när de är fullständigt. Lägena är transactional och partialBatch. När du använder partialBatch sker uppdateringsåtgärden inte inom en transaktion. Varje kommando godkänns 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 kommandot TMSL Sequence eller med hjälp av andra metoder.
retryCount Int 0 Antal gånger operationen försöker igen innan den misslyckas.
objects Array Hela modellen En matris med objekt som ska bearbetas. Varje objekt innehåller table vid bearbetning av en hel tabell, eller table och partition vid bearbetning av en partition. Om inga objekt anges uppdateras hela modellen.
applyRefreshPolicy Boolesk 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 transactionalkan applyRefreshPolicy vara true eller false. Om commitMode är partialBatchstöds inte applyRefreshPolicy 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 inte anges bestäms den aktuella dagen med hjälp av tidszonskonfigurationen under "Uppdatera".
timeout Sträng 05:00:00 (5 timmar) Om en timeout anges följer varje datauppdateringsförsök på den semantiska modellen den tidsgränsen. En enskild uppdateringsbegäran kan innehålla flera försök om retryCount anges, vilket kan göra att den totala uppdateringstiden överskrider den angivna tidsgränsen. Om du till exempel anger en timeout på 1 timme med en retryCount på 2 kan det resultera i en total uppdateringstid på upp till 3 timmar. Användare kan justera timeout för att förkorta uppdateringstiden för snabbare felidentifiering eller utöka den utöver standardvärdet 5 timmar för mer komplexa datauppdateringar. Den totala uppdateringstiden, inklusive återförsök, får dock inte överstiga 24 timmar.

Svar

202 Accepted

Svaret innehåller också ett Location svarshuvudfält som pekar anroparen på uppdateringsåtgärden som skapades och accepterades. Den Location är platsen för den nya resursen som begäran skapade, vilket inkluderar den requestId som vissa förbättrade uppdateringsåtgärder kräver. I följande svar är requestId 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",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Not

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 Typ Beskrivning
requestId Guide Identifieraren för uppdateringsbegäran. Du behöver requestId för att fråga efter status för enskilda uppdateringar eller avbryta en pågående uppdateringsåtgärd.
refreshType Sträng 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 Sträng Datum och tid för uppdateringsstart.
endTime Sträng Datum och tid för uppdateringsslut.
status Sträng 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 är endTime tom.
Disabled anger att uppdateringen inaktiverades av selektiv uppdatering.
Cancelled anger att uppdateringen avbröts.
extendedStatus Sträng Utökar egenskapen status för att ge mer information.

Not

I Azure Analysis Services är det slutförda status resultatet succeeded. 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:et 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 ange requestId. Om åtgärden pågår returnerar statusInProgress, som i följande exempel på svarstext:

{
    "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/<begäranID>

Om du vill avbryta en pågående förbättrad uppdatering använder du DELETE-verbet på uppdateringsobjektet genom att ange requestId.

Till 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

Överväganden och begränsningar

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

Standarduppdateringsåtgärder

  • Du kan inte avbryta schemalagda eller på begäran-modelluppdateringar som utlöstes genom att välja uppdateringsknappen i portalen med hjälp av DELETE /refreshes/<requestId>.
  • Schemalagda och på begäran-modelluppdateringar som utlöstes genom att välja uppdateringsknappen i portalen har inte stöd för att få information om uppdateringsåtgärden med hjälp av GET /refreshes/<requestId>.
  • 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 uppdatering InProgress i 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.

Borttagning 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. För mer information om dynamisk minneshantering och modellavhysning, se Modellborttagning.

Tidsgränser för uppdateringsåtgärd

En uppdateringsåtgärd kan innehålla flera försök om retryCount anges. Varje försök har en standardtimeout på 5 timmar, vilket kan justeras med hjälp av parametern timeout. Den totala uppdateringstiden, inklusive återförsök, får inte överstiga 24 timmar.

Om retryCount anger ett tal börjar en ny uppdateringsåtgärd med tidsgränsen. Tjänsten försöker utföra åtgärden igen tills den antingen lyckas, når gränsen för retryCount eller når maxgränsen på 24 timmar från det första försöket.

Du kan justera timeout för att förkorta uppdateringstiden för snabbare felidentifiering eller utöka den utöver standardvärdet 5 timmar för mer komplexa datauppdateringar.

När du planerar din semantiska modelluppdatering med REST API för uppdateringsdatauppsättning bör du överväga tidsgränser och parametern retryCount. En uppdatering kan överskrida tidsgränsen om det första försöket misslyckas och omförsöksantalet är inställt på 1 eller mer. Om du begär en uppdatering med "retryCount": 1 och det första försöket misslyckas efter 4 timmar börjar ett andra försök. Om detta lyckas om 3 timmar är den totala tiden för uppdateringen 7 timmar.

Om uppdateringsåtgärder regelbundet misslyckas, överskrider tidsgränsen eller överskrider önskad lyckad uppdateringsåtgärdstid bör 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