Erweiterte Aktualisierung mit der Power BI REST-API
Sie können jede Programmiersprache verwenden, die REST-Aufrufe für semantische Modellaktualisierungsvorgänge unterstützt, indem Sie die REST-API für Power BI-Aktualisierungsdatensatz verwenden.
Die optimierte Aktualisierung für große und komplexe partitionierte Modelle wird traditionell mit Programmiermethoden aufgerufen, die TOM (Tabellarisches Objektmodell), PowerShell-Cmdlets oder TMSL (Tabular Model Scripting Language) verwenden. Diese Methoden erfordern jedoch lang andauernde HTTP-Verbindungen, die unzuverlässig sein können.
Das Power BI Refresh Dataset REST API kann asynchrone Modellaktualisierungsvorgänge erlauben, sodass langanhaltende HTTP-Verbindungen von Clientanwendungen nicht erforderlich sind. Im Vergleich zu Standardaktualisierungsvorgängen bietet die erweiterte Aktualisierung dank der REST-API zusätzliche Anpassungsoptionen und die folgenden Features, die für große Modelle nützlich sind:
- Batchcommits
- Aktualisierung auf Tabellen- und Partitionsebene
- Anwenden von Richtlinien für die inkrementelle Aktualisierung
GET
für Aktualisierungsdetails- Abbruch der Aktualisierung
- Zeitlimitkonfiguration
Anmerkung
- Bisher wurde die erweiterte Aktualisierung als asynchrone Aktualisierung mit REST-API bezeichnet. Eine Standardaktualisierung, die die REST-API "Refresh Dataset" verwendet, wird jedoch auch asynchron von ihrer Natur aus ausgeführt.
- Mit den erweiterten Power BI-REST-API-Aktualisierungsvorgängen werden Kachelcaches nicht automatisch aktualisiert. Kachelcaches werden nur dann aktualisiert, wenn Benutzende auf einen Bericht zugreifen.
Stamm-URL
Die Basis-URL weist das folgende Format auf:
https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes
Sie können Ressourcen und Vorgänge basierend auf Parametern an die Basis-URL anfügen. Im folgenden Diagramm stellen Gruppen, Datasets und Aktualisierungen Sammlungen dar. Gruppe, Dataset und Aktualisierung sind Objekte.
Anforderungen
Sie benötigen die folgenden Anforderungen für die Verwendung der REST-API:
- Ein Semantikmodell in Power BI Premium, einer Premium-Einzelbenutzerlizenz oder Power BI Embedded.
- Eine Gruppen-ID und Dataset-ID, die in der Anforderungs-URL verwendet werden soll.
- Den Berechtigungsbereich Dataset.ReadWrite.All.
Die Anzahl der Aktualisierungen ist je nach den allgemeinen Einschränkungen für API-basierte Aktualisierungen für Pro- und Premium-Modelle begrenzt.
Authentifizierung
Alle Aufrufe müssen mit einem gültigen Microsoft Entra ID OAuth 2-Token im Autorisierungsheader authentifiziert werden. Das Token muss die folgenden Anforderungen erfüllen:
- Es muss entweder ein Benutzertoken oder ein Anwendungsdienstprinzipal sein.
- Es muss ordnungsgemäß auf
https://api.powerbi.com
festgelegt sein. - Es muss von einem Benutzer oder einer Anwendung mit ausreichenden Berechtigungen für das Modell verwendet werden.
Anmerkung
REST-API-Änderungen ändern derzeit definierte Berechtigungen für Modellaktualisierungen nicht.
POST /refreshes
Um eine Aktualisierung auszuführen, verwenden Sie das POST-Verb in der /refreshes-Auflistung, um der Auflistung ein neues Aktualisierungsobjekt hinzuzufügen. Der Location-Header in der Antwort enthält die requestId
. Da der Vorgang asynchron ist, kann eine Clientanwendung die Verbindung trennen und die requestId
verwenden, um den Status später bei Bedarf zu überprüfen.
Der folgende Code zeigt eine Beispielanforderung:
POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes
Der Anforderungstext könnte dem folgenden Beispiel ähneln:
{
"type": "Full",
"commitMode": "transactional",
"maxParallelism": 2,
"retryCount": 2,
"timeout": "02:00:00",
"objects": [
{
"table": "DimCustomer",
"partition": "DimCustomer"
},
{
"table": "DimDate"
}
]
}
Anmerkung
Der Dienst akzeptiert jeweils nur einen Aktualisierungsvorgang für ein Modell. Wenn eine laufende Aktualisierung ausgeführt wird und eine andere Anforderung gesendet wird, wird ein HTTP-Statuscode 400 Bad Request
zurückgegeben.
Parameter
Um einen erweiterten Aktualisierungsvorgang auszuführen, müssen Sie einen oder mehrere Parameter im Anforderungstext angeben. Angegebene Parameter können den Standardwert oder einen optionalen Wert angeben. Wenn die Anforderung Parameter angibt, gelten alle anderen Parameter für den Vorgang mit ihren Standardwerten. Wenn die Anforderung keine Parameter angibt, verwenden alle Parameter ihre Standardwerte, und ein Standardaktualisierungsvorgang tritt auf.
Name | Typ | Standard | Beschreibung |
---|---|---|---|
type |
Enum | automatic |
Der Typ der Verarbeitung, die durchgeführt werden soll. Typen entsprechen den TMSL-Aktualisierungsbefehlstypen: full , clearValues , calculate , dataOnly , automatic und defragment . Der add Typ wird nicht unterstützt. |
commitMode |
Enum | transactional |
Bestimmt, ob Objekte in Batches oder erst nach Abschluss committet werden sollen. Die Modi sind transactional und partialBatch . Bei Verwendung partialBatch erfolgt der Aktualisierungsvorgang nicht innerhalb einer Transaktion. Jeder Befehl wird einzeln committet. Wenn ein Fehler auftritt, ist das Modell möglicherweise leer oder enthält nur eine Teilmenge der Daten. Führen Sie den Vorgang mit commitMode = transactional aus, um sich vor Ausfällen zu schützen und die Daten, die sich vor Beginn des Vorgangs im Modell befanden, beizubehalten. |
maxParallelism |
Int | 10 |
Bestimmt die maximale Anzahl von Threads, die die Verarbeitungsbefehle parallel ausführen können. Dieser Wert stimmt mit der MaxParallelism -Eigenschaft überein, die im TMSL-Sequence -Befehl oder mithilfe anderer Methoden festgelegt werden kann. |
retryCount |
Int | 0 |
Anzahl der Wiederholungen des Vorgangs, bevor er fehlschlägt. |
objects |
Array | Gesamtes Model | Ein Array von Objekten, die verarbeitet werden sollen. Jedes Objekt enthält table beim Verarbeiten einer gesamten Tabelle oder table und partition bei der Verarbeitung einer Partition. Wenn keine Objekte angegeben werden, wird das gesamte Modell aktualisiert. |
applyRefreshPolicy |
Boolean | true |
Gibt an, ob die Richtlinie angewendet werden soll, wenn eine Richtlinie für die inkrementelle Aktualisierung definiert ist. Die Modi sind true oder false . Wenn die Richtlinie nicht angewendet wird, lässt der vollständige Prozess die Partitionsdefinitionen unverändert und aktualisiert alle Partitionen in der Tabelle vollständig. Wenn commitMode transactional ist, kann applyRefreshPolicy true oder false werden. Wenn commitMode partialBatch ist, wird applyRefreshPolicy von true nicht unterstützt, und applyRefreshPolicy muss auf false festgelegt werden. |
effectiveDate |
Date | Aktuelles Datum | Wenn eine inkrementelle Aktualisierungsrichtlinie angewendet wird, überschreibt der parameter effectiveDate das aktuelle Datum. Wenn nicht angegeben, wird der aktuelle Tag mithilfe der Zeitzonenkonfiguration unter "Aktualisieren"bestimmt. |
timeout |
Zeichenfolge | 05:00:00 (5 Stunden) | Wenn ein timeout angegeben ist, entspricht jeder Datenaktualisierungsversuch für das semantische Modell diesem Timeout. Eine einzelne Aktualisierungsanforderung kann mehrere Versuche enthalten, wenn retryCount angegeben ist, was dazu führen kann, dass die gesamte Aktualisierungsdauer das angegebene Timeout überschreitet. Wenn Sie beispielsweise eine timeout von 1 Stunde mit einem retryCount von 2 festlegen, kann dies zu einer Gesamtaktualisierungsdauer von bis zu 3 Stunden führen. Benutzer können die timeout anpassen, um die Aktualisierungsdauer für eine schnellere Fehlererkennung zu verkürzen oder sie über die standardmäßigen 5 Stunden für komplexere Datenaktualisierungen hinaus zu erweitern. Die Gesamtaktualisierungsdauer, einschließlich Wiederholungen, kann jedoch 24 Stunden nicht überschreiten. |
Antwort
202 Accepted
Die Antwort enthält außerdem ein Location
-Antwortheaderfeld, um den Aufrufer an den Aktualisierungsvorgang zu verweisen, der erstellt und akzeptiert wurde. Die Location
ist der Speicherort der neuen Ressource, die durch die Anforderung erstellt wurde, einschließlich der requestId
, die für einige erweiterte Aktualisierungsvorgänge erforderlich ist. In der folgenden Antwort ist requestId
beispielsweise der letzte Bezeichner in der Antwort 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
Verwenden Sie das GET-Verb für die /refreshes-Sammlung, um bisherige, aktuelle und ausstehende Aktualisierungsvorgänge aufzulisten.
Der Antworttext kann wie im folgenden Beispiel aussehen:
[
{
"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"
}
]
Anmerkung
Power BI kann Anforderungen löschen, wenn zu viele Anforderungen in kurzer Zeit vorhanden sind. Power BI führt eine Aktualisierung durch, stellt die nächste Anforderung in die Warteschlange ein und löscht alle anderen. Von vornherein können Sie den Status von abgelehnten Anfragen nicht abfragen.
Antworteigenschaften
Name | Typ | Beschreibung |
---|---|---|
requestId |
GUID | Der Bezeichner der Aktualisierungsanforderung. Um den Status eines einzelnen Aktualisierungsvorgangs zu ermitteln oder einen laufenden Aktualisierungsvorgang abzubrechen, müssen Sie requestId abfragen. |
refreshType |
Zeichenfolge | OnDemand gibt an, dass die Aktualisierung interaktiv über das Power BI-Portal ausgelöst wurde.Scheduled gibt an, dass ein Modellaktualisierungszeitplan die Aktualisierung ausgelöst hat. ViaApi gibt an, dass ein API-Aufruf die Aktualisierung ausgelöst hat. ViaEnhancedApi gibt an, dass ein API-Aufruf eine erweiterte Aktualisierung ausgelöst hat. |
startTime |
Zeichenfolge | Datum und Uhrzeit des Aktualisierungsstarts. |
endTime |
Zeichenfolge | Datum und Uhrzeit des Aktualisierungsendes. |
status |
Zeichenfolge | Completed gibt an, dass der Aktualisierungsvorgang erfolgreich abgeschlossen wurde. Failed gibt an, dass der Aktualisierungsvorgang fehlgeschlagen ist. Unknown gibt an, dass der Abschlusszustand nicht bestimmt werden kann. Mit diesem Status ist endTime leer. Disabled gibt an, dass die Aktualisierung durch eine selektive Aktualisierung deaktiviert wurde. Cancelled gibt an, dass die Aktualisierung erfolgreich abgebrochen wurde. |
extendedStatus |
Zeichenfolge | Erweitert die status -Eigenschaft, um weitere Informationen bereit zu stellen. |
Anmerkung
In Azure Analysis Services ist das abgeschlossene status
-Ergebnis succeeded
. Wenn Sie eine Azure Analysis Services-Lösung zu Power BI migrieren, müssen Sie Ihre Lösungen möglicherweise ändern.
Begrenzen der Anzahl zurückgegebener Aktualisierungsvorgänge
Die Power BI-REST-API unterstützt das Einschränken der angeforderten Anzahl von Einträgen im Aktualisierungsverlauf mithilfe des optionalen $top
-Parameters. Wenn kein Wert angegeben wird, werden standardmäßig alle verfügbaren Einträge verwendet.
GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}
GET /refreshes/<requestId>
Um den Status eines Aktualisierungsvorgangs zu überprüfen, verwenden Sie das GET-Verb für das Aktualisierungsobjekt, indem Sie die requestId
angeben. Beim Ausführen des Vorgangs gibt status
wie im Antworttext im folgenden Beispiel InProgress
zurück:
{
"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>
Soll ein aktuell ausgeführter erweiterter Aktualisierungsvorgang abgebrochen werden, verwenden Sie das DELETE-Verb für das Aktualisierungsobjekt, indem Sie die requestId
angeben.
Beispiel:
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
Überlegungen und Einschränkungen
Der Aktualisierungsvorgang weist die folgenden Überlegungen und Einschränkungen auf:
Standardaktualisierungsvorgänge
- Sie können geplante Aktualisierungen oder On-Demand-Modellaktualisierungen, die durch das Auswählen der Schaltfläche „Aktualisieren“ im Portal mit
DELETE /refreshes/<requestId>
ausgelöst wurden, nicht abbrechen. - Geplante und On-Demand-Modellaktualisierungen, die durch Auswählen der Schaltfläche „Aktualisieren“ im Portal ausgelöst wurden, unterstützen das Abrufen von Aktualisierungsvorgangsdetails mithilfe von
GET /refreshes/<requestId>
nicht. - „Details abrufen“ und „Abbrechen“ sind neue Vorgänge, die nur für erweiterte Aktualisierungen zur Verfügung stehen. Die Standardaktualisierung unterstützt diese Vorgänge nicht.
Power BI Embedded
Wenn die Kapazität im Power BI-Portal manuell angehalten oder mithilfe von PowerShell pausiert wird, oder ein Systemausfall auftritt, bleibt der Status eines laufenden erweiterten Aktualisierungsvorgangs maximal sechs Stunden lang auf InProgress
. Wenn die Kapazität innerhalb von sechs Stunden wiederhergestellt wird, wird der Aktualisierungsvorgang automatisch fortgesetzt. Wird die Kapazität erst nach mehr als sechs Stunden fortgesetzt, gibt der Aktualisierungsvorgang möglicherweise einen Zeitüberschreitungsfehler zurück. Anschließend müssen Sie den Aktualisierungsvorgang neu starten.
Semantikmodellentfernung
Power BI verwendet dynamische Speicherverwaltung, um den Kapazitätsspeicher zu optimieren. Wenn das Modell während eines Aktualisierungsvorgangs aus dem Arbeitsspeicher entfernt wird, kann der folgende Fehler angezeigt werden:
{
"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"
}
]
}
Die Lösung besteht darin, den Aktualisierungsvorgang erneut auszuführen. Weitere Informationen zur dynamischen Speicherverwaltung und zum Entfernen von Modellen finden Sie unter Entfernen von Modellen.
Zeitlimits für Aktualisierungsvorgänge
Ein Aktualisierungsvorgang kann mehrere Versuche umfassen, wenn retryCount
angegeben ist. Jeder Versuch verfügt über ein Standardtimeout von 5 Stunden, das mithilfe des timeout
Parameters angepasst werden kann. Die Gesamtaktualisierungsdauer, einschließlich Wiederholungen, darf 24 Stunden nicht überschreiten.
Wenn retryCount
eine Zahl angibt, beginnt ein neuer Aktualisierungsvorgang mit dem festgelegten Zeitlimit. Der Dienst wiederholt diesen Vorgang, bis er erfolgreich ist, das retryCount
-Limit erreicht oder das Maximum von 24 Stunden nach dem ersten Versuch erreicht.
Sie können die timeout
anpassen, um die Aktualisierungsdauer für eine schnellere Fehlererkennung zu verkürzen oder sie über die standardmäßigen 5 Stunden für komplexere Datenaktualisierungen hinaus zu erweitern.
Berücksichtigen Sie beim Planen der Aktualisierung des Semantikmodells mit der Rest-API „Refresh Dataset“ Zeitlimits und den Parameter „retryCount“. Eine Aktualisierung kann das Zeitlimit überschreiten, wenn der anfängliche Versuch fehlschlägt und „retryCount“ auf 1 oder einen größeren Wert festgelegt ist. Wenn Sie eine Aktualisierung mit "retryCount": 1 anfordern und der erste Versuch nach 4 Stunden fehlschlägt, beginnt ein zweiter Versuch. Wenn dies in 3 Stunden erfolgreich ist, beträgt die Gesamtzeit für die Aktualisierung 7 Stunden.
Wenn Aktualisierungsvorgänge regelmäßig fehlschlagen, das Timeout-Zeitlimit überschreiten oder die gewünschte erfolgreiche Aktualisierungszeit überschreiten, sollten Sie erwägen, die Datenmenge zu verringern, die von der Datenquelle aktualisiert wird. Sie können die Aktualisierung in mehrere Anforderungen aufteilen, z. B. eine Anforderung für jede Tabelle. Sie können im Parameter „commitMode“ auch „partialBatch“ angeben.
Codebeispiel
Ein C#-Codebeispiel für die ersten Schritte finden Sie unter RestApiSample- auf GitHub.
So verwenden Sie den Beispielcode:
- Klonen Sie das Repository, oder laden Sie es herunter.
- Öffnen Sie die RestApiSample-Lösung.
- Suchen Sie die Zeile
client.BaseAddress = …
, und geben Sie Ihre Basis-URL an.
Im Beispielcode wird die Dienstprinzipalauthentifizierung verwendet.