Vylepšená aktualizace pomocí rozhraní REST API Power BI
Pomocí rozhraní REST API pro aktualizaci datové sady Power BI můžete použít libovolný programovací jazyk, který podporuje volání REST pro sémantické operace aktualizace modelu.
Optimalizovaná aktualizace pro velké a složité dělené modely se tradičně vyvolává pomocí programovacích metod, které používají TOM (tabulkový objektový model), rutiny PowerShellu nebo TMSL (jazyk skriptování tabulkového modelu). Tyto metody však vyžadují dlouhotrvající připojení HTTP, která mohou být nespolehlivé.
Rozhraní REST API pro aktualizaci datové sady Power BI může provádět operace aktualizace modelu asynchronně, takže dlouhotrvající připojení HTTP z klientských aplikací nejsou nutná. V porovnání se standardními operacemi aktualizace poskytuje rozšířené aktualizace s rozhraním REST API další možnosti přizpůsobení a následující funkce, které jsou užitečné pro velké modely:
- Dávkové potvrzení
- Aktualizace na úrovni tabulky a oddílu
- Použití zásad přírůstkové aktualizace
- podrobnosti o aktualizaci
GET - Obnovení zrušeného procesu
Poznámka
- Dříve se vylepšená aktualizace nazývala asynchronní aktualizace s rozhraním REST API. Standardní aktualizace, která používá rozhraní REST API pro aktualizaci datové sady, se ale také spouští asynchronně podle své podstaty.
- Rozšířené operace aktualizace rozhraní REST API Power BI automaticky neaktualizují mezipaměti dlaždic. Vykreslení dlaždic se obnovují jen když uživatel přistupuje k reportu.
Základní adresa URL
Základní adresa URL je v následujícím formátu:
https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes
Na základě parametrů můžete k základní adrese URL připojit prostředky a operace. V následujícím diagramu jsou skupiny , datové sady a aktualizace kolekcemi . Skupina, datová sadaa Aktualizace jsou objekty.
Požadavky
K používání rozhraní REST API potřebujete následující požadavky:
- Sémantický model v Power BI Premium, Premium pro uživatele nebo Power BI Embedded.
- ID skupiny a ID datové sady, které se mají použít v adrese URL požadavku.
- Rozsah oprávnění Dataset.ReadWrite.All.
Počet aktualizací je omezený na obecná omezení pro aktualizace založené na rozhraní API pro modely Pro a Premium.
Autentizace
Všechna volání se musí ověřit pomocí platného tokenu Microsoft Entra ID OAuth 2 v hlavičce Autorizace. Token musí splňovat následující požadavky:
- Buď token uživatele, nebo instanční objekt aplikace.
- Nastavte cílovou skupinu správně na
https://api.powerbi.com. - Může být používán uživatelem nebo aplikací, které mají dostatečná oprávnění pro práci s modelem.
Poznámka
Úpravy rozhraní REST API nemění aktuálně definovaná oprávnění pro aktualizace modelu.
POST /refreshes
Pokud chcete provést aktualizaci, použijte příkaz POST v kolekci /refreshes a přidejte do kolekce nový obnovovací objekt. Hlavička Umístění v odpovědi obsahuje requestId. Vzhledem k tomu, že operace je asynchronní, klientská aplikace se může odpojit a v případě potřeby pomocí requestId zkontrolovat stav později.
Následující kód ukazuje ukázkový požadavek:
POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes
Text požadavku může vypadat podobně jako v následujícím příkladu:
{
"type": "Full",
"commitMode": "transactional",
"maxParallelism": 2,
"retryCount": 2,
"objects": [
{
"table": "DimCustomer",
"partition": "DimCustomer"
},
{
"table": "DimDate"
}
]
}
Poznámka
Služba přijímá pro model pouze jednu operaci aktualizace najednou. Pokud existuje aktuální spuštěná aktualizace a odešle se jiný požadavek, vrátí 400 Bad Request stavový kód HTTP.
Parametry
Chcete-li provést rozšířenou operaci aktualizace, je nutné zadat jeden nebo více parametrů v textu požadavku. Zadané parametry mohou určovat výchozí nebo volitelnou hodnotu. Když požadavek určuje parametry, všechny ostatní parametry platí pro operaci s jejich výchozími hodnotami. Pokud požadavek nezadá žádné parametry, všechny parametry používají výchozí hodnoty a dojde ke standardní operaci aktualizace.
| Jméno | Typ | Výchozí | Popis |
|---|---|---|---|
type |
Enum | automatic |
Typ zpracování, který se má provést. Typy odpovídají typům příkazů aktualizace TMSL: full, clearValues, calculate, dataOnly, automatica defragment. Typ add není podporovaný. |
commitMode |
Výčet | transactional |
Určuje, zda se objekty mají schvalovat v dávkách nebo až po dokončení. Režimy jsou transactional a partialBatch. Při použití partialBatch k operaci aktualizace nedojde v rámci jedné transakce. Každý příkaz se potvrdí jednotlivě. Pokud dojde k selhání, model může být prázdný nebo může obsahovat jenom podmnožinu dat. Chcete-li zajistit ochranu před selháním a zachovat data, která byla v modelu před zahájením operace, spusťte operaci pomocí commitMode = transactional. |
maxParallelism |
Int | 10 |
Určuje maximální počet vláken, která mohou paralelně spouštět příkazy pro zpracování. Tato hodnota odpovídá vlastnosti MaxParallelism, kterou lze nastavit v příkazu TMSL Sequence nebo pomocí jiných metod. |
retryCount |
Int | 0 |
Počet opakování operace před selháním |
objects |
Pole | Celý model | Pole objektů, které se mají zpracovat. Každý objekt zahrnuje table při zpracování celé tabulky, nebo table, partition při zpracování oddílu. Pokud nejsou zadány žádné objekty, celý model se aktualizuje. |
applyRefreshPolicy |
Booleovský | true |
Pokud je definována zásada přírůstkové aktualizace, určuje, jestli se má zásada použít. Režimy jsou true nebo false. Pokud se zásada nepoužije, celý proces ponechá definice oddílů beze změny a plně aktualizuje všechny oddíly v tabulce. Pokud je commitModetransactional, applyRefreshPolicy může být true nebo false. Pokud je commitModepartialBatch, není podporováno applyRefreshPolicy u true a applyRefreshPolicy musí být nastaveno na false. |
effectiveDate |
Datum | Aktuální datum | Pokud se použije zásada přírůstkové aktualizace, parametr effectiveDate přepíše aktuální datum. Pokud není zadaný, určuje se aktuální den pomocí konfigurace časového pásma v části Aktualizovat. |
Odpověď
202 Accepted
Odpověď obsahuje také pole hlavičky odpovědi Location, které volajícího nasměruje na vytvořenou a přijatou operaci aktualizace.
Location je umístění nového prostředku vytvořeného požadavkem, který zahrnuje requestId, které vyžadují některé rozšířené operace aktualizace. Například v následující odpovědi je requestId posledním identifikátorem v odpovědi 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
Pomocí příkazu GET v kolekci /refreshes můžete zobrazit seznam historických, aktuálních a čekajících operací aktualizace.
Text odpovědi může vypadat jako v následujícím příkladu:
[
{
"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"
}
]
Poznámka
Power BI může žádosti zahodit, pokud jich je příliš mnoho během krátké doby. Power BI provede aktualizaci, zařadí další požadavek do fronty a všechny ostatní zamítne. Záměrně se nelze dotazovat na stav vyřazených žádostí.
Vlastnosti odpovědi
| Jméno | Typ | Popis |
|---|---|---|
requestId |
Identifikátor GUID | Identifikátor žádosti o aktualizaci. Potřebujete requestId zadat dotaz na stav jednotlivých operací aktualizace nebo zrušit probíhající operaci aktualizace. |
refreshType |
Řetězec |
OnDemand značí, že se aktualizace aktivovala interaktivně prostřednictvím portálu Power BI.Scheduled značí, že plán aktualizace modelu aktivoval aktualizaci. ViaApi označuje, že volání rozhraní API aktivovalo aktualizaci. ViaEnhancedApi označuje, že volání rozhraní API aktivovalo vylepšenou aktualizaci. |
startTime |
Řetězec | Datum a čas zahájení aktualizace |
endTime |
Řetězec | Datum a čas ukončení aktualizace |
status |
Řetězec |
Completed označuje, že operace aktualizace byla úspěšně dokončena. Failed značí, že operace aktualizace selhala. Unknown označuje, že stav dokončení nelze určit. U tohoto stavu je endTime prázdný. Disabled označuje, že aktualizace byla zakázána selektivní aktualizací. Cancelled značí, že aktualizace byla úspěšně zrušena. |
extendedStatus |
Řetězec | Rozšiřuje vlastnost status, aby poskytovala další informace. |
Poznámka
Ve službě Azure Analysis Services je dokončený výsledek statussucceeded. Pokud migrujete řešení Azure Analysis Services do Power BI, budete možná muset upravit svá řešení.
Omezení počtu vrácených operací aktualizace
Rozhraní REST API Power BI podporuje omezení požadovaného počtu položek v historii aktualizace pomocí volitelného parametru $top. Pokud není zadáno, výchozí hodnota je všechny dostupné položky.
GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}
GET /refreshes/<requestId>
Chcete-li zkontrolovat stav operace aktualizace, použijte příkaz GET u objektu aktualizace zadáním requestId. Pokud operace probíhá, status vrátí InProgress, jako v následujícím příkladu textu odpovědi:
{
"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>
Chcete-li zrušit probíhající rozšířenou operaci aktualizace, použijte příkaz DELETE u objektu aktualizace zadáním requestId.
Například
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
Důležité informace a omezení
Operace aktualizace má následující aspekty a omezení:
Standardní operace aktualizace
- Naplánované nebo vyžádané aktualizace modelu, které se aktivovaly, nemůžete zrušit výběrem tlačítka aktualizace na portálu pomocí
DELETE /refreshes/<requestId>. - Plánované aktualizace modelu a aktualizace na vyžádání aktivované výběrem tlačítka aktualizace na portálu nepodporují získání podrobností o operaci aktualizace pomocí
GET /refreshes/<requestId>. - Získání podrobností a Zrušení jsou nové operace pouze pro rozšířenou aktualizaci. Standardní aktualizace tyto operace nepodporuje.
Power BI Embedded
Pokud je kapacita pozastavená ručně na portálu Power BI nebo pomocí PowerShellu nebo dojde k výpadku systému, stav jakékoli probíhající rozšířené operace aktualizace zůstane po dobu maximálně šesti hodin InProgress. Pokud se kapacita obnoví do šesti hodin, operace aktualizace se automaticky obnoví. Pokud se kapacita obnoví po déle než šesti hodinách, operace aktualizace může vrátit chybu časového limitu. Potom je nutné operaci aktualizace restartovat.
Vyřazení sémantického modelu
Power BI používá dynamickou správu paměti k optimalizaci paměti kapacity. Pokud se model během operace aktualizace vyřadí z paměti, může se vrátit následující chyba:
{
"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"
}
]
}
Řešením je znovu spustit operaci aktualizace. Další informace o správě dynamické paměti a vyřazení modelu najdete v tématu vyřazení modelu.
Časové limity operací aktualizace
Maximální doba pro jednu operaci aktualizace je pět hodin. Pokud se operace aktualizace úspěšně nedokončí během pětihodinového limitu a retryCount není zadána nebo je zadána jako 0 (výchozí) v textu požadavku, vrátí se chyba časového limitu.
Pokud retryCount určuje 1 nebo jiné číslo, zahájí se nová operace aktualizace s pětihodinovým limitem. Pokud tato operace opakování selže, služba bude pokračovat v opakování operace aktualizace až do maximálního počtu opakování, které retryCount určuje, nebo rozšířeného časového limitu zpracování aktualizace 24 hodin od začátku prvního požadavku na aktualizaci.
Při plánování vylepšeného řešení aktualizace modelu pomocí rozhraní REST API pro aktualizaci datové sady je důležité vzít v úvahu tyto časové limity a parametr retryCount. Úspěšné dokončení aktualizace může překročit pět hodin, pokud selže operace počáteční aktualizace a retryCount určuje 1 nebo více.
Pokud například požadujete operaci aktualizace s "retryCount": 1a počáteční operace opakování selže čtyři hodiny od času zahájení, zahájí se druhá operace aktualizace pro tento požadavek. Pokud je tato druhá operace aktualizace úspěšná za tři hodiny, celková doba úspěšného spuštění žádosti o aktualizaci je sedm hodin.
Pokud operace aktualizace pravidelně selžou, překročí 5hodinový časový limit nebo překročí požadovanou dobu úspěšné operace aktualizace, zvažte snížení množství dat, která se aktualizují ze zdroje dat. Aktualizaci můžete rozdělit na několik požadavků, například požadavek na každou tabulku. V parametru commitMode můžete také zadat partialBatch.
Ukázka kódu
Ukázku kódu jazyka C#, která vám umožní začít, najdete v tématu restApiSample na GitHubu.
Použití ukázky kódu:
- Naklonujte nebo stáhněte úložiště.
- Otevřete řešení RestApiSample.
- Najděte řádku
client.BaseAddress = …a poskytněte vaši základní adresu URL .
Ukázka kódu používá ověřování pomocí objektu služby.