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á. Ve srovnání se standardními operacemi aktualizace poskytuje vylepšená aktualizace rozhraní 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
• GET aktualizace podrobností
• Obnovení zrušení

Poznámka:

• Dříve byla vylepšená aktualizace označována jako asynchronní aktualizace pomocí rozhraní 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. Dlaždice se aktualizují jenom v případech, kdy uživatel přistupuje k sestavě.

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 kolekce. Skupina, datová sada a 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 na uživatele nebo Power BI Embedded
• ID skupiny a ID datové sady, které se mají použít v adrese URL požadavku.
• Obor 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.

Ověřování

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ě .https://api.powerbi.com
• Uživatel nebo aplikace, které mají dostatečná oprávnění k modelu.

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 zkontrolovat requestId 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 je aktuální spuštěná aktualizace a odešle se jiný požadavek, vrátí se stavový 400 Bad Request 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.

Name	Type	Výchozí	Popis
type	Výčet	automatic	Typ zpracování, který se má provést. Typy odpovídají typům příkazů aktualizace TMSL: full, clearValues, calculate, dataOnly, automatic, a defragment. Typ add není podporovaný.
commitMode	Výčet	transactional	Určuje, zda se mají potvrdit objekty v dávkách, nebo pouze po dokončení. Režimy jsou transactional a partialBatch. Při použití partialBatch operace 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 = transactionalpříkazu .
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á MaxParallelism vlastnosti, 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 zpracování celé tabulky nebo tablepartition při zpracování oddílu. Pokud nejsou zadány žádné objekty, celý model se aktualizuje.
applyRefreshPolicy	Logická hodnota	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 commitMode je transactional, applyRefreshPolicy může být true nebo false. Pokud commitMode je hodnota partialBatch, applyRefreshPolicy není true podporována a applyRefreshPolicy musí být nastavena na falsehodnotu .
effectiveDate	Datum	Aktuální datum	Pokud se použije zásada přírůstkové aktualizace, effectiveDate parametr přepíše aktuální datum. Pokud není zadaný, použije se k určení aktuálního dne UTC.

Response

202 Accepted

Odpověď obsahuje Location také pole hlavičky odpovědi, které volajícímu nasměruje na operaci aktualizace, která byla vytvořena a přijata. Jedná se Location o umístění nového prostředku, který požadavek vytvořil, včetně requestId toho, že některé rozšířené operace aktualizace vyžadují. Například v následující odpovědi requestId je poslední identifikátor 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",
        "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"
    }
]

Poznámka:

Power BI může žádosti v krátkém časovém intervalu vypustit. Power BI provede aktualizaci, zařadí další požadavek do fronty a zařadí všechny ostatní. Podle návrhu není možné zadávat dotazy na vyřazené žádosti.

Vlastnosti odpovědi

Name	Typ	Popis
requestId	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	String	OnDemand označuje, že se aktualizace aktivovala interaktivně prostřednictvím portálu Power BI. Scheduled označuje, ž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	String	Datum a čas zahájení aktualizace
endTime	String	Datum a čas ukončení aktualizace
status	String	Completed indikuje, že operace aktualizace byla úspěšně dokončena. Failed označuje, že operace aktualizace selhala. Unknown značí, že stav dokončení nelze určit. S tímto stavem endTime je prázdný. Disabled označuje, že aktualizace byla zakázána selektivní aktualizací. Cancelled značí, že aktualizace byla úspěšně zrušena.
extendedStatus	String	status Rozšíří vlastnost tak, aby poskytovala další informace.

Poznámka:

Ve službě Azure Analysis Services je succeededdokončený status výsledek . 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 $top parametru. 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í hodnotu 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.

Pří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

Úvahy a omezení

Operace aktualizace má následující aspekty a omezení:

Standardní operace aktualizace

• Plánované nebo ruční aktualizace modelu na vyžádání není možné zrušit pomocí DELETE /refreshes/<requestId>.
• Plánované a ruční aktualizace modelu na vyžádání 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 se kapacita pozastaví 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 InProgress maximálně šest hodin. 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 v textu požadavku zadaná jako 0 (výchozí), vrátí se chyba časového limitu.

Pokud retryCount zadáte 1 nebo jiné číslo, zahájí se nová operace aktualizace s pětihodinovým limitem. Pokud tato operace opakování selže, bude služba 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 retryCount parametr. Úspěšné dokončení aktualizace může překročit pět hodin, pokud se operace počáteční aktualizace nezdaří a retryCount určí 1 nebo více.

Pokud například požadujete operaci aktualizace s "retryCount": 1operací a počáteční operace opakování selže čtyři hodiny od času spuštění, 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é zadatpartialBatch.

Ukázka kódu

Ukázku kódu C#, která vám umožní začít, najdete v tématu RestApiSample na GitHubu.

Použití ukázky kódu:

1. Naklonujte nebo stáhněte úložiště.
2. Otevřete řešení RestApiSample.
3. Najděte řádek client.BaseAddress = … a zadejte základní adresu URL.

Ukázka kódu používá ověřování instančního objektu.

Související obsah

• Rozhraní REST API pro aktualizaci datové sady Power BI
• Použití rozhraní REST API Power BI