Erweiterte Aktualisierung mit der Power BI-REST-API

Sie können jede beliebige Programmiersprache, die REST-Aufrufe unterstützt, für Aktualisierungsvorgänge von Semantikmodellen mithilfe der Power BI-REST-API zum Aktualisieren von Datasets verwenden.

Für eine optimierte Aktualisierung bei großen und komplexen partitionierten Modellen wurden traditionell Programmiermethoden unter Verwendung von TOM (Tabular Object Model, tabellarisches Objektmodell), PowerShell-Cmdlets oder TMSL (Tabular Model Scripting Language, Skriptsprache für tabellarische Modelle) eingesetzt. Diese Methoden erfordern jedoch lange bestehende HTTP-Verbindungen, die unzuverlässig sein können.

Die Power BI-REST-API zum Aktualisieren von Datasets kann Aktualisierungsvorgänge von Modellen asynchron ausführen, sodass keine lange bestehenden HTTP-Verbindungen von Clientanwendungen erforderlich sind. Im Vergleich zu Standardaktualisierungsvorgängen bietet die erweiterte Aktualisierung mithilfe der REST-API zusätzliche Anpassungsoptionen und die folgenden Features, die für große Modelle nützlich sind:

• Commits im Batch
• Aktualisierung auf Tabellen- und Partitionsebene
• Anwenden von Richtlinien für die inkrementelle Aktualisierung
• GET von Details zur Aktualisierung
• Abbruch der Aktualisierung

Hinweis

• Früher wurde die erweiterte Aktualisierung als asynchrone Aktualisierung mit REST-API bezeichnet. Eine Standardaktualisierung mit der REST-API zur Datasetaktualisierung wird jedoch prinzipbedingt asynchron ausgeführt.
• Erweiterte Power BI-REST-API-Aktualisierungsvorgänge übernehmen keine automatische Aktualisierung der Kachelcaches. Die Caches der Kacheln werden nur aktualisiert, wenn ein Benutzer auf einen Bericht zugreift.

Basis-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 auf der Grundlage von Parametern an die Basis-URL anfügen. Im folgenden Diagramm stellen Gruppen, Datasets und AktualisierungenSammlungen dar. Gruppe, Dataset und Aktualisierung sind Objekte.

Anforderungen

Sie müssen die folgenden Anforderungen erfüllen, um die REST-API zu verwenden:

• 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 Berechtigungs-Geltungsbereich Dataset.ReadWrite.All.

Die Anzahl der Aktualisierungen ist gemäß den allgemeinen Einschränkungen für API-basierte Aktualisierungen für Pro- ebenso wie für Premium-Modelle beschränkt.

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.
• Die Zielgruppe muss ordnungsgemäß auf https://api.powerbi.com festgelegt sein.
• Es muss von einem Benutzer oder einer Anwendung verwendet werden, der bzw. die über ausreichende Berechtigungen für das Modell verfügt.

Hinweis

Durch REST API-Änderungen werden die aktuell definierten Berechtigungen für Modellaktualisierungen nicht geändert.

POST /refreshes

Verwenden Sie zum Ausführen einer Aktualisierung das POST-Verb für die /refreshes-Sammlung, um der Sammlung 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 bei Bedarf später 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 kann etwa dem folgenden Beispiel ähneln:

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

Hinweis

Der Dienst akzeptiert jeweils nur einen Aktualisierungsvorgang für ein Modell. Wenn aktuell eine Aktualisierung ausgeführt und eine weitere Anforderung übermittelt wird, wird der HTTP-Statuscode 400 Bad Request zurückgegeben.

Parameter

Zum Ausführen eines erweiterten Aktualisierungsvorgangs müssen Sie einen oder mehrere Parameter im Anforderungstext angeben. Über die angegebenen Parameter kann der Standardwert oder ein optionaler Wert angegeben werden. Wenn die Anforderung Parameter angibt, gelten alle anderen Parameter mit ihren Standardwerten für den Vorgang. Wenn die Anforderung keine Parameter angibt, verwenden alle Parameter ihre Standardwerte, und es wird ein Standardaktualisierungsvorgang durchgeführt.

Name	type	Standard	BESCHREIBUNG
type	Enum	automatic	Der auszuführende Verarbeitungstyp. Typen werden an den TMSL-Aktualisierungsbefehlstypen ausgerichtet: full, clearValues, calculate, dataOnly, automatic und defragment. Der Typ add wird nicht unterstützt.
commitMode	Enumeration	transactional	Bestimmt, ob Objekte in Batches oder erst nach Abschluss committet werden sollen. Die Modi sind transactional und partialBatch. Bei Verwendung von partialBatch findet der Aktualisierungsvorgang nicht innerhalb einer Transaktion statt. 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 Fehlern zu schützen und die Daten beizubehalten, die sich vor dem Beginn des Vorgangs im Modell befanden.
maxParallelism	Int	10	Bestimmt die maximale Anzahl von Threads, die die Verarbeitungsbefehle parallel ausführen können. Dieser Wert orientiert sich an der MaxParallelism-Eigenschaft, die im TMSL-Befehl Sequence oder mit anderen Methoden festgelegt werden kann.
retryCount	Int	0	Gibt an, wie oft der Vorgang wiederholt wird, bevor ein Fehler ausgegeben wird.
objects	Array	Gesamtes Model	Ein Array zu verarbeitender Objekte. Jedes Objekt enthält table, wenn eine gesamte Tabelle verarbeitet wird, oder table und partition, wenn eine Partition verarbeitet wird. Wenn keine Objekte angegeben werden, wird das gesamte Modell aktualisiert.
applyRefreshPolicy	Boolean	true	Bestimmt, wenn eine Richtlinie für die inkrementelle Aktualisierung definiert ist, ob die Richtlinie angewendet werden soll. Die Modi sind true oder false. Wenn die Richtlinie nicht angewendet wird, belässt der gesamte Prozess die Partitionsdefinitionen unverändert und aktualisiert alle Partitionen in der Tabelle vollständig. Wenn commitModetransactional ist, kann applyRefreshPolicytrue oder false sein. Wenn commitModepartialBatch ist, wird applyRefreshPolicy von true nicht unterstützt und applyRefreshPolicy muss auf false festgelegt werden.
effectiveDate	Date	Aktuelles Datum	Wenn eine Richtlinie für die inkrementelle Aktualisierung angewendet wird, überschreibt der effectiveDate-Parameter das aktuelle Datum. Bei einer fehlenden Angabe wird UTC verwendet, um den aktuellen Tag zu ermitteln.

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 könnte wie das folgende 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",
        "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"
    }
]

Hinweis

Power BI kann Anforderungen löschen, wenn in kurzer Zeit zu viele Anforderungen eingehen. Power BI führt eine Aktualisierung durch, stellt die nächste Anforderung in die Warteschlange ein und löscht alle anderen. Standardmäßig können Sie den Status für gelöschte Anforderungen nicht abfragen.

Antworteigenschaften

Name	Typ	Beschreibung
requestId	Guid	Dies ist der Bezeichner der Aktualisierungsanforderung. Sie benötigen requestId, um den Status eines einzelnen Aktualisierungsvorgangs abzufragen oder einen gerade ausgeführten Aktualisierungsvorgang abzubrechen.
refreshType	String	OnDemand gibt an, dass die Aktualisierung interaktiv über das Power BI-Portal ausgelöst wurde. Scheduled gibt an, dass die Aktualisierung durch einen Zeitplan für die Modellaktualisierung ausgelöst wurde. ViaApi gibt an, dass die Aktualisierung durch einen API-Aufruf ausgelöst wurde. ViaEnhancedApi gibt an, dass eine erweiterte Aktualisierung durch einen API-Aufruf ausgelöst wurde.
startTime	String	Datum und Uhrzeit des Aktualisierungsbeginns.
endTime	String	Datum und Uhrzeit des Aktualisierungsendes.
status	String	Completed gibt an, dass der Aktualisierungsvorgang erfolgreich abgeschlossen wurde. Failed gibt an, dass bei der Aktualisierung ein Fehler aufgetreten ist. Unknown gibt an, dass der Abschlusszustand nicht bestimmt werden kann. Bei 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	String	Erweitert die status-Eigenschaft, um weitere Informationen bereit zu stellen.

Hinweis

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 Beschränken der angeforderten Anzahl von Einträgen im Aktualisierungsverlauf mithilfe des Parameters $top. 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>

Wenn Sie den Status eines Aktualisierungsvorgangs überprüfen möchten, verwenden Sie das GET-Verb für das Aktualisierungsobjekt, indem Sie die requestId angeben. Wenn der Vorgang aktuell ausgeführt wird, gibt statusInProgress zurück, wie im Antworttext im folgenden Beispiel:

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

Für den Aktualisierungsvorgang gelten die folgenden Überlegungen und Einschränkungen:

Standardaktualisierungsvorgänge

• Sie können geplante oder bedarfsgesteuerte manuelle Modellaktualisierungen nicht mithilfe von DELETE /refreshes/<requestId> abbrechen.
• Geplante und bedarfsbasierte manuelle Modellaktualisierungen bieten keine Unterstützung für das Abrufen von Details zum Aktualisierungsvorgang mithilfe von GET /refreshes/<requestId>.
• „Details abrufen“ und „Abbrechen“ sind neue Vorgänge, die nur für erweiterte Aktualisierungen zur Verfügung stehen. Standardaktualisierungen unterstützen diese Vorgänge nicht.

Power BI Embedded

Wenn die Kapazität manuell im Power BI-Portal oder mithilfe von PowerShell angehalten wird oder ein Systemausfall auftritt, bleibt der Status eines laufenden erweiterten Aktualisierungsvorgangs maximal sechs Stunden lang InProgress. Wenn die Kapazität innerhalb von sechs Stunden fortgesetzt wird, wird auch der Aktualisierungsvorgang automatisch fortgesetzt. Wird die Kapazität erst nach mehr als sechs Stunden fortgesetzt, gibt der Aktualisierungsvorgang möglicherweise einen Timeoutfehler zurück. In diesem Fall müssen Sie den Aktualisierungsvorgang neu starten.

Semantikmodellabweisung

Power BI verwendet die dynamische Speicherverwaltung, um den Kapazitätsspeicher zu optimieren. Wenn das Modell während eines Aktualisierungsvorgangs aus dem Arbeitsspeicher entfernt wird, wird möglicherweise der folgende Fehler zurückgegeben:

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

Die maximale Zeitspanne für einen einzelnen Aktualisierungsvorgang beträgt fünf Stunden. Wenn der Aktualisierungsvorgang innerhalb des Fünf-Stunden-Limits nicht erfolgreich abgeschlossen und retryCount nicht angegeben oder im Anforderungstext mit 0 (dem Standardwert) angegeben ist, wird ein Timeoutfehler zurückgegeben.

Wenn retryCount1 oder eine andere Zahl angibt, wird ein neuer Aktualisierungsvorgang mit einem Limit von fünf Stunden gestartet. Wenn dieser Wiederholungsvorgang fehlschlägt, wiederholt der Dienst den Aktualisierungsvorgang bis zur größten Anzahl von Wiederholungen, die in retryCount angegeben wurde, oder bis zum Erreichen des Zeitlimits für die Verarbeitung von erweiterten Aktualisierungen von 24 Stunden ab dem Beginn der ersten Aktualisierungsanforderung.

Wenn Sie Ihre Lösung für die erweiterte Modellaktualisierung mit der REST-API zur Aktualisierung von Datasets planen, müssen diese Zeitlimits und der retryCount-Parameter beachtet werden. Ein erfolgreicher Aktualisierungsabschluss kann fünf Stunden überschreiten, wenn ein anfänglicher Aktualisierungsvorgang fehlschlägt und retryCount1 oder mehr angibt.

Wenn Sie beispielsweise einen Aktualisierungsvorgang mit "retryCount": 1 anfordern und der anfängliche Wiederholungsvorgang vier Stunden nach der Startzeit fehlschlägt, beginnt ein zweiter Aktualisierungsvorgang für diese Anforderung. Wenn dieser zweite Aktualisierungsvorgang in drei Stunden erfolgreich ausgeführt wird, beträgt die Gesamtdauer für die erfolgreiche Ausführung der Aktualisierungsanforderung sieben Stunden.

Wenn Aktualisierungsvorgänge regelmäßig fehlschlagen, das Zeitlimit von fünf Stunden überschreiten oder die gewünschte Zeit für erfolgreiche Aktualisierungen überschreiten, sollten Sie die Menge der Daten reduzieren, die aus der Datenquelle aktualisiert werden. Sie können die Aktualisierung in mehrere Anforderungen aufteilen, z. B. eine Anforderung für jede Tabelle. Sie können im Parameter commitMode darüber hinaus partialBatch angeben.

Codebeispiel

Ein C#-Codebeispiel für Ihren Einstieg finden Sie im RestApiSample auf GitHub.

So verwenden Sie das Codebeispiel:

1. Klonen Sie das Repository, oder laden Sie es herunter.
2. Öffnen Sie die RestApiSample-Lösung.
3. Suchen Sie die Zeile client.BaseAddress = …, und geben Sie Ihre Basis-URL an.

Das Codebeispiel verwendet die Dienstprinzipal-Authentifizierung.

Zugehöriger Inhalt

• Power BI-REST-API für Datasetaktualisierungen
• Verwenden der Power BI-REST-APIs