Verbeterde vernieuwing met de Power BI REST API

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. Vergeleken 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
• Vernieuw GET-details
• Annulering vernieuwen

Notitie

• Voorheen werd verbeterde verversen asynchrone verversen genoemd met REST API. Een standaard vernieuwingsproces dat gebruikmaakt van de REST API voor het vernieuwen van gegevenssets, wordt echter ook van nature asynchroon uitgevoerd.
• Geoptimaliseerde vernieuwingsbewerkingen van de Power BI REST API vernieuwen tegelcaches niet automatisch. 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 worden Groepen, Gegevenssetsen Vernieuwingenverzamelingen. groep, gegevensset, en verversing zijn objecten.

Eisen

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

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

Authenticatie

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:

• Wees een gebruikerstoken of een applicatieservice-principal.
• Zorg ervoor dat de doelgroep correct is ingesteld 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 gebruiken om de status later te controleren, indien nodig.

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 lopende vernieuwing is en er een andere aanvraag wordt ingediend, wordt er een 400 Bad Request HTTP-statuscode geretourneerd.

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.

Naam	Type	Verstek	Beschrijving
type	Enumeratie	automatic	Het type verwerking dat moet worden uitgevoerd. Typen worden uitgelijnd met de opdrachttypen voor TMSL-vernieuwing: full, clearValues, calculate, dataOnly, automaticen defragment. Het add type wordt niet ondersteund.
commitMode	Enumeratie	transactional	Bepaalt of objecten in batches moeten worden doorgevoerd of alleen wanneer deze zijn voltooid. De modi zijn transactional en partialBatch. Wanneer u partialBatch gebruikt, vindt de vernieuwingsbewerking niet binnen één transactie plaats. 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. Voer de bewerking uit met commitMode = transactionalom de gegevens te beschermen tegen fouten en de gegevens in het model te bewaren voordat de bewerking werd gestart.
maxParallelism	Int	10	Bepaalt het maximum aantal threads dat de verwerkingsopdrachten parallel kan uitvoeren. Deze waarde komt overeen met de eigenschap MaxParallelism die kan worden ingesteld in de OPDRACHT TMSL Sequence of met behulp van andere methoden.
retryCount	Int	0	Aantal keren dat de bewerking opnieuw wordt geprobeerd voordat de bewerking mislukt.
objects	Array	Volledig model	Een matrix met objecten die moeten worden verwerkt. Elk object bevat table bij het verwerken van een hele tabel, of table en partition bij het verwerken van een partitie. Als er geen objecten zijn opgegeven, wordt het hele model vernieuwd.
applyRefreshPolicy	Booleaans	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 commitModetransactionalis, kan applyRefreshPolicy worden true of false. Als commitMode is partialBatch, wordt applyRefreshPolicy van true niet ondersteund en moet applyRefreshPolicy worden ingesteld op false.
effectiveDate	Datum	Huidige datum	Als een beleid voor incrementeel vernieuwen wordt toegepast, overschrijft de parameter effectiveDate de huidige datum. Als dit niet is opgegeven, wordt de huidige dag bepaald met de tijdzoneconfiguratie onder 'Vernieuwen'.

Antwoord

202 Accepted

Het antwoord bevat ook een Location antwoordheaderveld om de aanroeper te laten verwijzen naar de vernieuwingsbewerking die is gemaakt en geaccepteerd. De Location is de locatie van de nieuwe resource die door het verzoek is aangemaakt, inclusief de requestId die nodig is voor sommige verbeterde vernieuwingsbewerkingen. In het volgende antwoord is requestId 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",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "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. Het is standaard niet mogelijk om de status op te vragen van niet-verwerkte aanvragen.

Antwoordeigenschappen

Naam	Type	Beschrijving
requestId	Guid	De id van de vernieuwingsaanvraag. U hebt requestId nodig om een query uit te voeren op de status van een afzonderlijke vernieuwingsbewerking of om een actieve vernieuwingsbewerking te annuleren.
refreshType	Snaar	OnDemand geeft aan dat de vernieuwing 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	Snaar	De datum en tijd waarop het vernieuwen is gestart.
endTime	Snaar	Datum en tijd waarop het vernieuwen eindigt.
status	Snaar	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 is endTime leeg. Disabled geeft aan dat het verversen is uitgeschakeld door selectief verversen. Cancelled geeft aan dat de vernieuwing is geannuleerd.
extendedStatus	Snaar	Vergroot de eigenschap status voor meer informatie.

Notitie

In Azure Analysis Services wordt het voltooide status resultaat succeeded. 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 de requestIdop te geven. Als de bewerking wordt uitgevoerd, retourneert statusInProgress, 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 de 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 modelvernieuwingen die zijn geactiveerd door het selecteren van de knop Vernieuwen in de portal niet annuleren met behulp van DELETE /refreshes/<requestId>.
• Geplande en on-demand modelvernieuwingen die zijn geactiveerd door de knop Vernieuwen in de portal te selecteren, ondersteunen niet 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 de status van een doorlopende vernieuwingsbewerking gedurende maximaal zes uur InProgress. Als de capaciteit binnen zes uur wordt hervat, wordt de vernieuwingsbewerking automatisch hervat. Als de capaciteit pas na meer dan zes uur wordt hervat, kan het vernieuwingsproces een time-outfout genereren. 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 is 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 modelverwijderingvoor 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 retryCount1 of een ander getal opgeeft, 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 opgeeft, of de tijdslimiet voor de verbeterde vernieuwingsverwerking van 24 uur vanaf het begin van de eerste vernieuwingsaanvraag.

Wanneer u uw verbeterde oplossing voor het vernieuwen van modellen plant met behulp van de REST API voor gegevenssetvernieuwing, is het belangrijk om rekening te houden met deze tijdslimieten en de parameter retryCount. Een geslaagde vernieuwing kan meer dan vijf uur duren als een eerste vernieuwingsbewerking mislukt en retryCount1 of meer specificeert.

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 partialBatch opgeven in de parameter commitMode.

Codevoorbeeld

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

Het codevoorbeeld gebruiken:

1. Clonen ofwel downloaden van de repository.
2. Open de RestApiSample-oplossing.
3. Zoek de regel client.BaseAddress = … en geef uw basis-URL op.

Het codevoorbeeld maakt gebruik van service-principalverificatie.

Verwante inhoud

• REST API voor Power BI-gegevensset vernieuwen
• De Power BI REST API's gebruiken