Vylepšené obnovenie pomocou rozhrania Power BI REST API

Článok
01/10/2024

Pomocou ľubovoľného programovacieho jazyka, ktorý podporuje volania REST, môžete vykonávať sémantické operácie obnovenia modelu pomocou rozhrania REST API obnovenia množiny údajov služby Power BI.

Optimalizované obnovenie pre veľké a zložité rozdelenia modelov sa tradične vyvoláva s programovacími metódami, ktoré používajú TOM (tabuľkový objektový model), rutiny typu cmdlet prostredia PowerShell alebo TMSL (jazyk na skriptovanie tabuľkového modelu). Tieto metódy si však vyžadujú dlhodobé pripojenia HTTP, ktoré môžu byť nespoľahlivé.

Rozhranie REST API obnovenia údajov služby Power BI môže vykonávať operácie obnovenia modelu asynchrónne, takže dlhodobé pripojenia HTTP z klientskych aplikácií nie sú potrebné. V porovnaní so štandardnými operáciami obnovenia poskytuje vylepšené obnovenie s rozhraním REST API viac možností prispôsobenia a nasledujúce funkcie, ktoré sú užitočné pre veľké modely:

Dávkové hlásenia
Obnovenie na úrovni tabuľky a oblasti
Používanie politík prírastkového obnovenia
GET podrobnosti o obnovení
Zrušenie obnovenia

Poznámka

V minulosti sa vylepšené obnovenie nazývalo asynchrónne obnovenie s rozhraním REST API. Štandardné obnovenie, ktoré používa rozhranie REST API Obnoviť množinu údajov, sa však tiež spúšťa asynchrónne podľa svojej prirodzenej povahy.
Vylepšené operácie obnovenia rozhrania REST API služby Power BI neobnovujú automaticky vyrovnávacie pamäte dlaždíc. Vyrovnávacia pamäť dlaždíc sa obnoví iba vtedy, keď používateľ pristupuje k zostave.

Základná URL adresa

Základná URL adresa je v nasledujúcom formáte:

https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes

Zdroje a operácie môžete pripojiť k základnej URL adrese na základe parametrov. V nasledujúcom diagrame sú kolekcie Skupiny, Množiny údajov a Obnovenia. Skupina, Množina údajov a Obnovenie sú objekty.

Diagram that shows asynchronous refresh flow.

Požiadavky

Na používanie rozhrania REST API potrebujete nasledujúce požiadavky:

Sémantický model v službách Power BI Premium, Premium na používateľa alebo Power BI Embedded.
ID skupiny a ID množiny údajov na použitie v URL adrese požiadavky.
Rozsah povolení Dataset.ReadWrite.All .

Počet obnovení je obmedzený podľa všeobecných obmedzení obnovení založených na rozhraniach API pre modely Pro a Premium.

Overovanie

Všetky volania sa musia overiť pomocou platného tokenu ID OAuth 2 spoločnosti Microsoft v hlavičke Authorization. Token musí spĺňať nasledujúce požiadavky:

Buď token používateľa, alebo objekt služby aplikácie.
Nastavte cieľovú skupinu na možnosť https://api.powerbi.comsprávne.
Používa ju používateľ alebo aplikácia, ktorá má v modeli dostatočné povolenia.

Poznámka

Úpravy rozhrania REST API nemenia aktuálne definované povolenia pre obnovenia modelu.

POST/refreshes (POST/obnovenia)

Ak chcete vykonať obnovenie, pomocou položky UVEREJNIŤ sloveso v kolekcii /refreshes pridajte do kolekcie nový objekt obnovenia. Hlavička umiestnenia v odpovedi obsahuje requestId. Keďže operácia je asynchrónne, klientska aplikácia sa môže odpojiť a v prípade potreby použiť metódu requestId na kontrolu stavu neskôr.

Nasledujúci kód zobrazuje vzorovú požiadavku:

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

Text požiadavky môže pripomínať nasledujúci príklad:

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

Poznámka

Služba prijíma pre model iba jednu operáciu obnovenia naraz. Ak sa vyskytne aktuálne spustené obnovenie a odošle sa ďalšia žiadosť, 400 Bad Request vráti sa kód stavu HTTP.

Parametre

Ak chcete vykonať vylepšenú operáciu obnovenia, musíte v tele požiadavky zadať jeden alebo viac parametrov. Zadané parametre môžu určiť predvolenú alebo voliteľnú hodnotu. Keď žiadosť určuje parametre, všetky ostatné parametre sa použijú na operáciu s ich predvolenými hodnotami. Ak žiadosť určuje žiadne parametre, všetky parametre používajú svoje predvolené hodnoty a dôjde k štandardnej operácii obnovenia.

Name	Zadať	Predvolené	Description
`type`	Enumerácia	`automatic`	Typ spracovania, ktoré sa má vykonať. Typy sú v súlade s typmi príkazov obnovenia TMSL: `full`, `clearValues`, `calculate`, `dataOnly`, `automatic`a `defragment`. Typ `add` nie je podporovaný.
`commitMode`	Enumerácia	`transactional`	Určí, či sa majú objekty potvrdiť v dávkach alebo len v prípade dokončenia. Režimy sú `transactional` a `partialBatch`. Pri použití `partialBatch` operácie obnovenia sa nevyskytuje v rámci jednej transakcie. Každý príkaz je spáchaný individuálne. V prípade zlyhania môže byť model prázdny alebo môže obsahovať iba podmnožinu údajov. Ak chcete chrániť pred zlyhaním a ponechať údaje, ktoré boli v modeli pred začatím operácie, vykonajte operáciu príkazom `commitMode = transactional`.
`maxParallelism`	Int	`10`	Určuje maximálny počet vlákien, ktoré môžu spracovávať príkazy spracovávania paralelne. Táto hodnota je v súlade s vlastnosťou `MaxParallelism` , ktorú možno nastaviť v príkaze TMSL `Sequence` alebo pomocou iných metód.
`retryCount`	Int	`0`	Počet opakovaných pokusov operácie pred zlyhaním.
`objects`	Pole	Celý model	Pole objektov, ktoré sa majú spracovať. Každý objekt zahŕňa `table` pri spracovaní celej tabuľky alebo `table` pri `partition` spracovaní oblasti. Ak nie sú zadané žiadne objekty, celý model sa obnoví.
`applyRefreshPolicy`	Boolean	`true`	Ak je definovaná politika prírastkového obnovenia, určí, či sa má politika použiť. Režimy sú `true` alebo `false`. Ak sa politika nepoužije, celý proces ponechá definície oblastí nezmenené a úplne obnoví všetky oblasti v tabuľke. Ak `commitMode` hodnota je `transactional`, `applyRefreshPolicy` môže byť `true` alebo `false`. Ak `commitMode` hodnota je `partialBatch`, `applyRefreshPolicy` of `true` nie je podporovaná a `applyRefreshPolicy` musí byť nastavená na `false`hodnotu .
`effectiveDate`	Date	Aktuálny dátum	Ak sa použije politika prírastkového obnovenia, `effectiveDate` parameter prepíše aktuálny dátum. Ak parameter nie je zadaný, na určenie aktuálneho dňa sa použije UTC.

Odpoveď

202 Accepted

Odpoveď obsahuje Location aj pole hlavičky odpovede na nasmerovanie volajúceho na operáciu obnovenia, ktorá bola vytvorená a prijatá. je Location umiestnenie nového prostriedku, ktorý žiadosť vytvorila, vrátane requestId časti, ktorú vyžadujú niektoré vylepšené operácie obnovenia. Napríklad v nasledujúcej odpovedi requestId je posledný identifikátor v odpovedi 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 (ZÍSKAŤ/obnovenia)

Sloveso GET v kolekcii /refreshes použite na zoznam historických, aktuálnych a čakajúcich operácií obnovenia.

Telo odpovede môže vyzerať ako v nasledujúcom príklade:

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

Ak by v krátkom čase existovalo príliš veľa žiadostí, služba Power BI môže žiadosti o podporu zrušiť. Power BI vykoná obnovenie, zaradí do frontu ďalšiu požiadavku a vráti všetky ostatné. Podľa návrhu nie je možné dotazovať stav na vynechaných požiadavkách.

Vlastnosti odpovede

Name	Zadať	Description
`requestId`	GUID	Identifikátor žiadosti o obnovenie. Musíte `requestId` dotazovať stav jednotlivých operácií obnovenia alebo zrušiť priebeh operácie obnovenia.
`refreshType`	String	`OnDemand` označuje, že obnovenie sa spustilo interaktívne prostredníctvom portálu služby Power BI. `Scheduled` Označuje, že obnovenie sa spustilo podľa plánu obnovenia modelu. `ViaApi` Označuje, že volanie rozhrania API spustilo obnovenie. `ViaEnhancedApi` Označuje, že volanie rozhrania API spustilo vylepšené obnovenie.
`startTime`	String	Dátum a čas začatia obnovenia.
`endTime`	String	Dátum a čas skončenia obnovenia.
`status`	String	`Completed` označuje úspešné dokončenie operácie obnovenia. `Failed` Označuje zlyhanie operácie obnovenia. `Unknown` označuje, že stav dokončenia nie je možné určiť. Keď je stav prázdny `endTime` . `Disabled` Označuje, že obnovenie bolo zakázané selektívnym obnovením. `Cancelled` označuje, že obnovenie bolo úspešne zrušené.
`extendedStatus`	String	Rozšíri vlastnosť o `status` poskytnutie ďalších informácií.

Poznámka

Dokončený výsledok v službe status Azure Analysis Services je succeeded. Ak migrujete riešenie služby Azure Analysis Services do služby Power BI, možno budete musieť svoje riešenia upraviť.

Obmedzenie počtu vrátených operácií obnovenia

Rozhranie REST API služby Power BI podporuje obmedzenie požadovaného počtu položiek v histórii obnovení pomocou voliteľného $top parametra. Ak parameter nie je zadaný, predvolené sú všetky dostupné položky.

GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}

GET /refreshes/<requestId>

Ak chcete skontrolovať stav operácie obnovenia, použite sloveso GET v objekte obnovenia zadaním hodnoty requestId. Ak prebieha operácia, status vráti hodnotu InProgress, ako v nasledujúcom príklade tela odpovede:

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

Ak chcete zrušiť pokročilú operáciu obnovenia prebiehajúceho obnovenia, použite sloveso DELETE v objekte obnovenia zadaním hodnoty requestId.

Naprí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é informácie a obmedzenia

Operácia obnovenia má nasledujúce dôležité informácie a obmedzenia:

Štandardné operácie obnovenia

Nie je možné zrušiť plánované obnovenia modelu alebo manuálne obnovenia modelu na požiadanie pomocou funkcie DELETE /refreshes/<requestId>.
Plánované manuálne obnovenia modelu a obnovenia na požiadanie nepodporujú získavanie podrobností o operácii obnovenia pomocou funkcie GET /refreshes/<requestId>.
Podrobnosti a Zrušiť sú nové operácie len na vylepšené obnovenie. Štandardné obnovenie nepodporuje tieto operácie.

Power BI Embedded

Ak je kapacita pozastavená manuálne na portáli služby Power BI alebo pomocou prostredia PowerShell alebo nastane výpadok systému, stav prebiehajúcich rozšírených operácií obnovenia zostáva InProgress maximálne šesť hodín. Ak sa kapacita obnoví do šiestich hodín, operácia obnovenia sa automaticky obnoví. Ak sa kapacita obnoví po dlhšej ako šesť hodín, operácia obnovenia môže vrátiť chybu časového limitu. Potom musíte operáciu obnovenia reštartovať.

Vyradenie sémantických modelov

Power BI používa na optimalizáciu pamäte kapacitu dynamickú správu pamäte. Ak je model počas operácie obnovenia vyradený z pamäte, môže sa vrátiť nasledujúca 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"
        }
    ]
}

Riešením je opätovné spustenie operácie obnovenia. Ďalšie informácie o dynamickej správe pamäte a vyradení modelu nájdete v téme Vyradenie modelu.

Časové limity obnovenia operácie

Maximálna dĺžka času jednej operácie obnovenia je päť hodín. Ak sa operácia obnovenia úspešne nedokončí v rámci päťhodinového limitu a retryCount nie je zadaná alebo je v tele požiadavky zadaná ako 0 (predvolená), vráti sa chyba časového limitu.

Ak retryCount určujete 1 alebo iné číslo, spustí sa nová operácia obnovenia s päťhodinovým limitom. Ak táto operácia opakovania zlyhá, služba bude pokračovať v opätovnom obnovení operácie až do najväčšieho počtu opakovaní, ktorý retryCount určuje, alebo do upresneného časového limitu na spracovanie obnovenia 24 hodín od začiatku prvej žiadosti o obnovenie.

Keď plánujete svoje vylepšené riešenie obnovenia modelu pomocou rozhrania REST API Obnoviť množinu údajov, je dôležité vziať do úvahy tieto časové limity a retryCount parameter. Úspešné dokončenie obnovenia môže presiahnuť päť hodín, ak zlyhá počiatočná operácia obnovenia a retryCount určí 1 alebo viac.

Ak napríklad požiadate o operáciu obnovenia s "retryCount": 1a počiatočná operácia opätovného pokusu zlyhá štyri hodiny od času začatia, spustí sa druhá operácia obnovenia tejto žiadosti. Ak je druhá operácia obnovenia úspešná za tri hodiny, celkový čas úspešného vykonania žiadosti o obnovenie je sedem hodín.

Ak operácie obnovenia pravidelne zlyhajú, prekročia päťhodinový časový limit alebo prekročia požadovaný čas úspešnej operácie obnovenia, zvážte zníženie množstva údajov, ktoré sa obnovujú zo zdroja údajov. Obnovenie môžete rozdeliť na viaceré požiadavky, napríklad žiadosť pre každú tabuľku. Môžete tiež zadať partialBatch v parametri commitMode .

Ukážka kódu

Ukážku kódu jazyka C# získate v téme RestApiSample v GitHube.

Ak chcete použiť ukážku kódu:

Klonovať alebo stiahnuť odkladací priestor.
Otvorte riešenie RestApiSample.
Nájdite riadok client.BaseAddress = … a zadajte svoju základnú URL adresu.

Ukážka kódu používa overovanie objektom služby.

Vylepšené obnovenie pomocou rozhrania Power BI REST API

Základná URL adresa

Požiadavky

Overovanie

POST/refreshes (POST/obnovenia)

Parametre

Odpoveď

GET /refreshes (ZÍSKAŤ/obnovenia)

Vlastnosti odpovede

Obmedzenie počtu vrátených operácií obnovenia

GET /refreshes/<requestId>

DELETE/refreshes/<requestId>

Dôležité informácie a obmedzenia

Štandardné operácie obnovenia

Power BI Embedded

Vyradenie sémantických modelov

Časové limity obnovenia operácie

Ukážka kódu

Súvisiaci obsah

Ďalšie zdroje informácií