Share via

Verbeterde vernieuwing met de Power BI REST API

  • Artikel

U kunt elke programmeertaal gebruiken die REST-aanroepen ondersteunt om semantische bewerkingen voor het vernieuwen van modellen uit te voeren met behulp van de REST API voor Power BI Refresh Dataset.

Geoptimaliseerd vernieuwen voor grote en complexe gepartitioneerde modellen wordt traditioneel aangeroepen met programmeermethoden die gebruikmaken van TOM (Tabular Object Model), PowerShell-cmdlets of TMSL (Tabular Model Scripting Language). Voor deze methoden zijn echter langlopende HTTP-verbindingen vereist die onbetrouwbaar kunnen zijn.

De REST API voor Power BI Refresh Dataset kan modelvernieuwingsbewerkingen asynchroon uitvoeren, zodat langlopende HTTP-verbindingen van clienttoepassingen niet nodig zijn. In vergelijking met standaardvernieuwingsbewerkingen biedt verbeterde vernieuwing met de REST API meer aanpassingsopties en de volgende functies die nuttig zijn voor grote modellen:

  • Batchgewijze doorvoeringen
  • Vernieuwen op tabel- en partitieniveau
  • Beleid voor incrementeel vernieuwen toepassen
  • GET details vernieuwen
  • Annulering vernieuwen

Notitie

  • Voorheen werd verbeterde vernieuwing asynchrone vernieuwing met REST API genoemd. Een standaardvernieuwing die gebruikmaakt van de REST API voor gegevensset vernieuwen, wordt echter ook asynchroon uitgevoerd op basis van de inherente aard.
  • Verbeterde vernieuwingsbewerkingen voor Power BI REST API vernieuwen niet automatisch tegelcaches. Tegel wordt alleen vernieuwd wanneer een gebruiker een rapport opent.

Basis-URL

De basis-URL heeft de volgende indeling:

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

U kunt resources en bewerkingen toevoegen aan de basis-URL op basis van parameters. In het volgende diagram zijn groepen, gegevenssets en vernieuwingen verzamelingen. Groep, gegevensset en vernieuwen zijn objecten.

Diagram that shows asynchronous refresh flow.

Vereisten

U hebt de volgende vereisten nodig om de REST API te gebruiken:

  • Een semantisch model in Power BI Premium, Premium per gebruiker of Power BI Embedded.
  • Een groeps-id en gegevensset-id die moeten worden gebruikt in de aanvraag-URL.
  • Dataset.ReadWrite.All permission scope.

Het aantal vernieuwingen is beperkt volgens de algemene beperkingen voor op API gebaseerde vernieuwingen voor Pro- en Premium-modellen.

Verificatie

Alle aanroepen moeten worden geverifieerd met een geldig OAuth 2-token van Microsoft Entra ID in de autorisatieheader. Het token moet voldoen aan de volgende vereisten:

  • Een gebruikerstoken of een service-principal voor toepassingen zijn.
  • Laat de doelgroep juist instellen op https://api.powerbi.com.
  • Worden gebruikt door een gebruiker of toepassing met voldoende machtigingen voor het model.

Notitie

REST API-wijzigingen wijzigen momenteel gedefinieerde machtigingen voor modelvernieuwingen niet.

POST/vernieuwingen

Als u een vernieuwing wilt uitvoeren, gebruikt u de POST-bewerking in de verzameling /refreshes om een nieuw vernieuwingsobject toe te voegen aan de verzameling. De locatieheader in het antwoord bevat de requestId. Omdat de bewerking asynchroon is, kan een clienttoepassing de verbinding verbreken en de requestId status zo nodig controleren.

De volgende code toont een voorbeeldaanvraag:

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

De hoofdtekst van de aanvraag lijkt mogelijk op het volgende voorbeeld:

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

Notitie

De service accepteert slechts één vernieuwingsbewerking tegelijk voor een model. Als er een huidige actieve vernieuwing is en er een andere aanvraag wordt ingediend, retourneert een 400 Bad Request HTTP-statuscode.

Parameters

Als u een verbeterde vernieuwingsbewerking wilt uitvoeren, moet u een of meer parameters opgeven in de aanvraagbody. Opgegeven parameters kunnen de standaardwaarde of een optionele waarde opgeven. Wanneer de aanvraag parameters opgeeft, zijn alle andere parameters van toepassing op de bewerking met hun standaardwaarden. Als de aanvraag geen parameters opgeeft, gebruiken alle parameters hun standaardwaarden en wordt er een standaardvernieuwingsbewerking uitgevoerd.

Name Type Standaard Beschrijving
type Opsomming automatic Het type verwerking dat moet worden uitgevoerd. Typen worden uitgelijnd met de opdrachttypen tmSL-vernieuwing: , , , , en defragmentautomatic. dataOnlycalculateclearValuesfull Het add type wordt niet ondersteund.
commitMode Opsomming transactional Bepaalt of objecten in batches moeten worden doorgevoerd of alleen wanneer deze zijn voltooid. Modi zijn transactional en partialBatch. Wanneer u partialBatch de vernieuwingsbewerking gebruikt, vindt deze niet plaats binnen één transactie. Elke opdracht wordt afzonderlijk doorgevoerd. Als er een fout opgetreden is, is het model mogelijk leeg of bevat het alleen een subset van de gegevens. Als u wilt beschermen tegen fouten en de gegevens wilt bewaren die zich in het model bevond voordat de bewerking werd gestart, voert u de bewerking uit met commitMode = transactional.
maxParallelism Int 10 Bepaalt het maximum aantal threads dat de verwerkingsopdrachten parallel kan uitvoeren. Deze waarde wordt uitgelijnd met de MaxParallelism eigenschap die kan worden ingesteld in de TMSL-opdracht Sequence of met behulp van andere methoden.
retryCount Int 0 Aantal keren dat de bewerking opnieuw wordt geprobeerd voordat de bewerking mislukt.
objects Matrix Volledig model Een matrix met objecten die moeten worden verwerkt. Elk object bevat table bij het verwerken van een hele tabel of partitiontable bij het verwerken van een partitie. Als er geen objecten zijn opgegeven, wordt het hele model vernieuwd.
applyRefreshPolicy Booleaanse waarde true Als een beleid voor incrementeel vernieuwen is gedefinieerd, bepaalt u of het beleid moet worden toegepast. Modi zijn true of false. Als het beleid niet wordt toegepast, blijven partitiedefinities ongewijzigd en worden alle partities in de tabel volledig vernieuwd.

Als commitMode dat het is transactional, applyRefreshPolicy kan het zijn true of false. Als commitMode dat het is partialBatch, applyRefreshPolicytrue van wordt niet ondersteund en applyRefreshPolicy moet worden ingesteld op false.
effectiveDate Datum Huidige datum Als een beleid voor incrementeel vernieuwen wordt toegepast, overschrijft de effectiveDate parameter de huidige datum. Als dit niet is opgegeven, wordt UTC gebruikt om de huidige dag te bepalen.

Respons

202 Accepted

Het antwoord bevat ook een Location antwoordheaderveld om de aanroeper te laten verwijzen naar de vernieuwingsbewerking die is gemaakt en geaccepteerd. Dit Location is de locatie van de nieuwe resource die de aanvraag heeft gemaakt, waaronder de requestId vereiste verbeterde vernieuwingsbewerkingen. In het volgende antwoord requestId is bijvoorbeeld de laatste id in het antwoord 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

Gebruik de GET-bewerking in de verzameling /refreshes om historische, huidige en in behandeling zijnde vernieuwingsbewerkingen weer te geven.

De hoofdtekst van het antwoord ziet er mogelijk uit zoals in het volgende voorbeeld:

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

Notitie

Power BI kan aanvragen verwijderen als er te veel aanvragen in een korte periode zijn. Power BI voert een vernieuwing uit, zet de volgende aanvraag in de wachtrij en verwijdert alle andere. Standaard kunt u geen querystatus uitvoeren op verwijderde aanvragen.

Responseigenschappen

Name Type Description
requestId Guid De id van de vernieuwingsaanvraag. U moet requestId een query uitvoeren op de status van een afzonderlijke vernieuwingsbewerking of een actieve vernieuwingsbewerking annuleren.
refreshType String OnDemand geeft aan dat het vernieuwen interactief is geactiveerd via de Power BI-portal.
Scheduled geeft aan dat een schema voor modelvernieuwing de vernieuwing heeft geactiveerd.
ViaApi geeft aan dat een API-aanroep de vernieuwing heeft geactiveerd.
ViaEnhancedApi geeft aan dat een API-aanroep een verbeterde vernieuwing heeft geactiveerd.
startTime String De datum en tijd waarop het vernieuwen is gestart.
endTime String De datum en tijd waarop het vernieuwen is beëindigd.
status String Completed geeft aan dat de vernieuwingsbewerking is voltooid.
Failed geeft aan dat de vernieuwingsbewerking is mislukt.
Unknown geeft aan dat de voltooiingsstatus niet kan worden bepaald. Met deze status endTime is deze leeg.
Disabled geeft aan dat de vernieuwing is uitgeschakeld door selectief vernieuwen.
Cancelled geeft aan dat het vernieuwen is geannuleerd.
extendedStatus String Vergroot de status accommodatie om meer informatie te verstrekken.

Notitie

In Azure Analysis Services is succeededhet voltooide status resultaat. Als u een Azure Analysis Services-oplossing migreert naar Power BI, moet u mogelijk uw oplossingen wijzigen.

Het aantal geretourneerde vernieuwingsbewerkingen beperken

De Power BI REST API biedt ondersteuning voor het beperken van het aangevraagde aantal vermeldingen in de vernieuwingsgeschiedenis met behulp van de optionele $top parameter. Als dit niet is opgegeven, is de standaardwaarde alle beschikbare vermeldingen.

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

GET /refreshes/<requestId>

Als u de status van een vernieuwingsbewerking wilt controleren, gebruikt u de GET-bewerking voor het vernieuwingsobject door het requestIdop te geven. Als de bewerking wordt uitgevoerd, retourneert InProgressdeze, status zoals in de volgende voorbeeldtekst van het antwoord:

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

Als u een uitgebreide vernieuwingsbewerking wilt annuleren, gebruikt u de bewerking DELETE in het vernieuwingsobject door het requestIdop te geven.

Bijvoorbeeld:

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

Overwegingen en beperkingen

De vernieuwingsbewerking heeft de volgende overwegingen en beperkingen:

Standaardvernieuwingsbewerkingen

  • U kunt geplande of on-demand handmatige modelvernieuwing niet annuleren met behulp van DELETE /refreshes/<requestId>.
  • Geplande en on-demand handmatige modelvernieuwing biedt geen ondersteuning voor het ophalen van details van vernieuwingsbewerkingen met behulp van GET /refreshes/<requestId>.
  • Details ophalen en Annuleren zijn alleen nieuwe bewerkingen voor verbeterde vernieuwing. Standaardvernieuwing biedt geen ondersteuning voor deze bewerkingen.

Power BI Embedded

Als de capaciteit handmatig wordt onderbroken in de Power BI-portal of met behulp van PowerShell, of als er een systeemstoring optreedt, blijft InProgress de status van een doorlopende vernieuwingsbewerking maximaal zes uur bestaan. Als de capaciteit binnen zes uur wordt hervat, wordt de vernieuwingsbewerking automatisch hervat. Als de capaciteit na langer dan zes uur wordt hervat, kan de vernieuwingsbewerking een time-outfout retourneren. Vervolgens moet u de vernieuwingsbewerking opnieuw starten.

Semantische modelverwijdering

Power BI maakt gebruik van dynamisch geheugenbeheer om capaciteitsgeheugen te optimaliseren. Als het model tijdens een vernieuwingsbewerking uit het geheugen wordt verwijderd, kan de volgende fout worden geretourneerd:

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

De oplossing is om de vernieuwingsbewerking opnieuw uit te voeren. Zie Modelverwijdering voor meer informatie over dynamisch geheugenbeheer en modelverwijdering.

Tijdslimieten voor vernieuwingsbewerkingen

De maximale tijdsduur voor één vernieuwingsbewerking is vijf uur. Als de vernieuwingsbewerking niet binnen de limiet van vijf uur is voltooid en retryCount niet is opgegeven of is opgegeven als 0 (de standaardinstelling) in de aanvraagbody, wordt er een time-outfout geretourneerd.

Als retryCount u een ander nummer opgeeft 1 , wordt een nieuwe vernieuwingsbewerking met een limiet van vijf uur gestart. Als deze bewerking voor opnieuw proberen mislukt, blijft de service de vernieuwingsbewerking opnieuw uitvoeren tot het grootste aantal nieuwe pogingen dat retryCount aangeeft, of de tijdslimiet voor de verbeterde vernieuwingsverwerking van 24 uur vanaf het begin van de eerste vernieuwingsaanvraag.

Wanneer u uw verbeterde oplossing voor modelvernieuwing plant met de REST API voor gegevensset vernieuwen, is het belangrijk om rekening te houden met deze tijdslimieten en de retryCount parameter. Een geslaagde vernieuwing kan langer zijn dan vijf uur als een initiële vernieuwingsbewerking mislukt en retryCount of meer opgeeft 1 .

Als u bijvoorbeeld een vernieuwingsbewerking aanvraagt met "retryCount": 1en de eerste bewerking voor opnieuw proberen vier uur na de begintijd mislukt, wordt een tweede vernieuwingsbewerking voor die aanvraag gestart. Als deze tweede vernieuwingsbewerking in drie uur slaagt, is de totale tijd voor een geslaagde uitvoering van de vernieuwingsaanvraag zeven uur.

Als vernieuwingsbewerkingen regelmatig mislukken, de tijdslimiet van vijf uur overschrijden of de gewenste geslaagde vernieuwingsbewerkingstijd overschrijden, kunt u overwegen om de hoeveelheid gegevens die worden vernieuwd uit de gegevensbron te verminderen. U kunt vernieuwen splitsen in meerdere aanvragen, bijvoorbeeld een aanvraag voor elke tabel. U kunt ook opgeven partialBatch in de commitMode parameter.

Voorbeeld van code

Zie RestApiSample op GitHub voor een voorbeeld van C#-code om u op weg te helpen.

Het codevoorbeeld gebruiken:

  1. Kloon of download de opslagplaats.
  2. Open de RestApiSample-oplossing.
  3. Zoek de regel client.BaseAddress = … en geef uw basis-URL op.

In het codevoorbeeld wordt verificatie van de service-principal gebruikt.

Gerelateerde inhoud