Vylepšené obnovenie pomocou rozhrania Power BI REST API

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é obnovenia s rozhraním REST API ďalšie možnosti 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
• Konfigurácia časového limitu

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ú Groups, Množiny údajov a Obnovenia kolekcie. skupiny množiny údajov a obnovenie sú objektmi.

Požiadavky

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

• Sémantický model v službe 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í pre 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 https://api.powerbi.comsprávne.
• Používa ju používateľ alebo aplikácia, ktorá má v modeli dostatočné povolenia.

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ť 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,
    "timeout": "02:00:00",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

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.

Odpoveď

202 Accepted

Odpoveď obsahuje aj pole Location hlavičky odpovede na nasmerovanie volajúceho na operáciu obnovenia, ktorá bola vytvorená a prijatá. The Location is the location of the new resource the request created, which includes the requestId that some enhanced refresh operations require. Napríklad v nasledujúcej odpovedi je requestId posledným identifikátorom v 87f31ef7-1e3a-4006-9b0b-191693e79e9eodpovede .

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",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Vlastnosti odpovede

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 parametra $top. 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 requestId. Ak prebieha operácia, status vráti 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ť prebiehajúce vylepšené obnovenie, použite sloveso DELETE v objekte obnovenia určením 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 obnovenia modelu na požiadanie, ktoré sa spustili výberom tlačidla obnovenia na portáli pomocou DELETE /refreshes/<requestId>.
• Plánované obnovenia modelu a obnovenia na požiadanie, ktoré sa spustili výberom tlačidla obnovenia na portáli, nepodporujú získavanie podrobností o operácii obnovenia pomocou 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 sa kapacita pozastaví 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 vyradenia modelov.

Časové limity obnovenia operácie

Ak je zadaná retryCount operácia obnovenia, môže obsahovať viacero pokusov. Každý pokus má predvolený časový limit 5 hodín, ktorý je možné upraviť pomocou parametra timeout. Celkové trvanie obnovenia vrátane opakovaní nesmie presiahnuť 24 hodín.

Ak retryCount určuje číslo, nová operácia obnovenia sa spustí s časovým limitom. Služba túto operáciu opakuje, kým buď neuspeje, nedosiahne limit retryCount alebo nedosiahne maximálny počet 24 hodín od prvého pokusu.

timeout môžete skrátiť, aby bolo možné rýchlejšie zisťovanie zlyhaní z dôvodu rýchlejšieho zisťovania zlyhaní alebo predĺžiť jeho trvanie za predvolených 5 hodín, aby bolo možné vykonať zložitejšie obnovenia údajov.

Pri plánovaní obnovenia sémantického modelu pomocou rozhrania REST API na obnovenie množiny údajov zvážte časové limity a parameter Počet opätovných pokusov. Obnovenie môže prekročiť časový limit v prípade zlyhania počiatočného pokusu a nastavenie Počet opätovných pokusov je nastavené na hodnotu 1 alebo viac. Ak požiadate o obnovenie pomocou príkazu "RetryCount": 1 a prvý pokus zlyhá po 4 hodinách, spustí sa druhý pokus. Ak sa to podarí za 3 hodiny, celkový čas obnovenia je 7 hodín.

Ak operácie obnovenia pravidelne zlyhajú, prekročia č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. V parametri commitMode môžete tiež zadať časťBatch.

Ukážka kódu

Ukážku kódu jazyka C# získate v téme restApiSample v službe GitHub.

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

1. Klonovať alebo stiahnuť odkladací priestor.
2. Otvorte riešenie RestApiSample.
3. Vyhľadajte client.BaseAddress = … riadka a zadajte svoju základnú URL adresu.

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

Súvisiaci obsah

• obnovenie množiny údajov služby Power BI pomocou rozhrania REST API
• používanie rozhraní REST API služby Power BI