Freigeben über

Erweiterte Aktualisierung mit der Power BI REST-API

  • Artikel

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.

Diagramm, das einen asynchronen Aktualisierungsfluss anzeigt.

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, automaticund 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 = transactionalaus, 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 commitModetransactionalist, kann applyRefreshPolicytrue oder falsewerden. Wenn commitModepartialBatchist, wird applyRefreshPolicy von true nicht unterstützt, und applyRefreshPolicy muss auf falsefestgelegt 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 requestIdangeben. 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:

  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.

Im Beispielcode wird die Dienstprinzipalauthentifizierung verwendet.

Verwandte Inhalte