Továbbfejlesztett frissítés a Power BI REST API-val
Bármely olyan programozási nyelvet használhat, amely támogatja a REST-hívásokat szemantikai modellfrissítési műveletek végrehajtásához a Power BI Refresh Dataset REST API használatával.
A nagy és összetett particionált modellek optimalizált frissítését hagyományosan tom (táblázatos objektummodell), PowerShell-parancsmagok vagy TMSL (táblázatos modellszkriptnyelv) használó programozási módszerekkel hívjuk meg. Ezek a módszerek azonban hosszú ideig futó HTTP-kapcsolatokat igényelnek, amelyek megbízhatatlanok lehetnek.
A Power BI Refresh Dataset REST API aszinkron módon hajthatja végre a modellfrissítési műveleteket, így az ügyfélalkalmazásokból származó, hosszú ideig futó HTTP-kapcsolatokra nincs szükség. A standard frissítési műveletekhez képest a REST API-val bővített frissítés több testreszabási lehetőséget és a nagy modellek számára hasznos alábbi funkciókat biztosítja:
- Kötegelt véglegesítések
- Tábla- és partíciószintű frissítés
- Növekményes frissítési szabályzatok alkalmazása
-
GET
frissítés részletei - Frissítés lemondása
- Időtúllépés konfigurálása
Jegyzet
- Korábban a továbbfejlesztett frissítést aszinkron frissítésnek hívták a REST API. Az adathalmaz rest API-t használó standard frissítés azonban aszinkron módon is fut a természetéből adódóan.
- A bővített Power BI REST API-frissítési műveletek nem frissítik automatikusan a csempék gyorsítótárait. A térocachék csak akkor frissülnek, ha egy felhasználó hozzáfér egy jelentéshez.
Alap URL-cím
Az alap URL-cím formátuma a következő:
https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes
Az erőforrásokat és műveleteket paraméterek alapján hozzáfűzheti az alap URL-címhez. Az alábbi ábrán Csoportok, Adathalmazokés Frissítésekgyűjtemények. Csoport, Adathalmazés Frissítésobjektumok.
Követelmények
A REST API használatához a következő követelmények szükségesek:
- Szemantikai modell a Power BI Premiumban, prémium felhasználónként vagy Power BI Embeddedben.
- A kérelem URL-címében használandó csoportazonosító és adatkészlet-azonosító.
- Dataset.ReadWrite.All jogosultsági szint.
A frissítések száma a Pro- és Premium-modellek API-alapú frissítéseinek általános korlátozásai szerint korlátozott.
Hitelesítés
Minden hívásnak hitelesítenie kell magát egy érvényes Microsoft Entra ID OAuth 2 tokennel az Authorization fejlécben. A tokennek meg kell felelnie a következő követelményeknek:
- Legyen felhasználói jogkivonat vagy alkalmazási szolgáltatási főfelhasználó.
- Állítsa a célközönséget helyesen
https://api.powerbi.com
értékre. - Olyan felhasználó vagy alkalmazás használhatja, amely rendelkezik a modellre vonatkozó megfelelő engedélyekkel.
Jegyzet
A REST API-módosítások nem módosítják a modellfrissítések jelenleg definiált engedélyeit.
POST /frissítések
Frissítéshez a /refreshes gyűjtemény POST parancsával adjon hozzá egy új frissítési objektumot a gyűjteményhez. A válasz Location fejléce tartalmazza a requestId
. Mivel a művelet aszinkron, az ügyfélalkalmazások leválaszthatják a kapcsolatot, és szükség esetén a requestId
segítségével ellenőrizhetik az állapotot.
Az alábbi kód egy mintakérést mutat be:
POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes
A kérelem törzse a következő példához hasonlíthat:
{
"type": "Full",
"commitMode": "transactional",
"maxParallelism": 2,
"retryCount": 2,
"timeout": "02:00:00",
"objects": [
{
"table": "DimCustomer",
"partition": "DimCustomer"
},
{
"table": "DimDate"
}
]
}
Jegyzet
A szolgáltatás egyszerre csak egy frissítési műveletet fogad el egy modellhez. Ha egy aktuális frissítés fut, és egy másik kérés is el van küldve, egy 400 Bad Request
HTTP-állapotkód jelenik meg.
Paraméterek
Továbbfejlesztett frissítési művelet végrehajtásához meg kell adnia egy vagy több paramétert a kérelem törzsében. A megadott paraméterek megadhatják az alapértelmezett vagy nem kötelező értéket. Amikor a kérelem paramétereket ad meg, az összes többi paraméter az alapértelmezett értékekkel érvényes a műveletre. Ha a kérés nem ad meg paramétereket, az összes paraméter az alapértelmezett értékeket használja, és egy szabványos frissítési művelet történik.
Név | Típus | Alapértelmezett | Leírás |
---|---|---|---|
type |
Enumeráció | automatic |
A végrehajtandó feldolgozás típusa. A típusok a TMSL frissítési parancstípusaihoz igazodnak: full , clearValues , calculate , dataOnly , automatic és defragment . A add típus nem támogatott. |
commitMode |
Enum | transactional |
Meghatározza, hogy kötegekben vagy csak akkor véglegesítse az objektumokat, ha befejeződött. A módok transactional és partialBatch . A partialBatch használatakor a frissítési művelet nem egy tranzakción belül történik. Az egyes parancsok külön-külön kerülnek elkötelezésre. Hiba esetén előfordulhat, hogy a modell üres, vagy csak az adatok egy részhalmazát tartalmazza. A hiba elleni védelem érdekében és a modellben a művelet megkezdése előtt tárolt adatok megőrzése érdekében hajtsa végre a műveletet commitMode = transactional . |
maxParallelism |
Int | 10 |
Meghatározza azoknak a szálaknak a maximális számát, amelyek párhuzamosan futtathatják a feldolgozási parancsokat. Ez az érték a TMSL Sequence parancsban vagy más metódusok használatával beállítható MaxParallelism tulajdonsághoz igazodik. |
retryCount |
Int | 0 |
Hányszor próbálkozik újra a művelet a sikertelenség előtt. |
objects |
Tömb | Teljes modell | Feldolgozandó objektumok tömbje. Minden objektum table tartalmaz egy teljes tábla feldolgozásakor, vagy table és partition egy partíció feldolgozásakor. Ha nincs megadva objektum, a teljes modell frissül. |
applyRefreshPolicy |
Boole-algebrai | true |
Ha növekményes frissítési szabályzat van definiálva, meghatározza, hogy alkalmazza-e a szabályzatot. A módok true vagy false . Ha a szabályzat nincs alkalmazva, a teljes folyamat változatlanul hagyja a partíciódefiníciókat, és teljes mértékben frissíti a tábla összes partícióját. Ha commitMode transactional , applyRefreshPolicy lehet true vagy false . Ha commitMode partialBatch , applyRefreshPolicy a true nem támogatott, és applyRefreshPolicy -et false -re kell beállítani. |
effectiveDate |
Dátum | Aktuális dátum | Növekményes frissítési szabályzat alkalmazása esetén a effectiveDate paraméter felülírja az aktuális dátumot. Ha nincs megadva, az aktuális nap az időzóna-konfigurációval lesz meghatározva "Frissítés"alatt. |
timeout |
karakterlánc | 05:00:00 (5 óra) | Ha timeout van megadva, a szemantikai modell minden adatfrissítési kísérlete ehhez az időtúllépéshez igazodik. Egyetlen frissítési kérelem több kísérletet is tartalmazhat, ha retryCount van megadva, ami miatt a teljes frissítési időtartam túllépheti a megadott időtúllépést. Például, ha a timeout értéke 1 óra és a retryCount értéke 2, az akár 3 órás teljes frissítési időtartamot is eredményezhet. A felhasználók módosíthatják a timeout , hogy lerövidítse a frissítés időtartamát a gyorsabb hibaészlelés érdekében, vagy hosszabbítsa meg az alapértelmezett 5 órát az összetettebb adatfrissítések esetében. A frissítés teljes időtartama, beleértve az újrapróbálkozásokat is, nem haladhatja meg a 24 órát. |
Válasz
202 Accepted
A válasz tartalmaz egy Location
válaszfejléc mezőt is, amely a hívót a létrehozott és elfogadott frissítési műveletre mutatja. A Location
a kérelem által létrehozott új erőforrás helye, amely magában foglalja azokat a requestId
, amelyeket bizonyos továbbfejlesztett frissítési műveletek igényelnek. Az alábbi válaszban például requestId
a válasz 87f31ef7-1e3a-4006-9b0b-191693e79e9e
utolsó azonosítója.
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 /refreshs
A /refreshes gyűjtemény GET parancsával listázhatja a korábbi, az aktuális és a függőben lévő frissítési műveleteket.
A válasz törzse a következő példához hasonlóan nézhet ki:
[
{
"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"
}
]
Jegyzet
A Power BI elvetheti a kérelmeket, ha rövid időn belül túl sok kérés van. A Power BI elvégzi a frissítést, várólistára állítja a következő kérést, és elveti az összes többit. Terv szerint nem kérdezheti le az elvetett kérelmek állapotát.
Válasz jellemzői
Név | Típus | Leírás |
---|---|---|
requestId |
Guid | A frissítési kérelem azonosítója. Az egyes frissítési műveletek állapotának lekérdezéséhez vagy folyamatban lévő frissítési művelet megszakításához requestId kell. |
refreshType |
Karakterlánc |
OnDemand jelzi, hogy a frissítés interaktívan aktiválódott a Power BI portálon keresztül.Scheduled azt jelzi, hogy egy modellfrissítési ütemezés aktiválta a frissítést. ViaApi azt jelzi, hogy egy API-hívás aktiválta a frissítést. ViaEnhancedApi azt jelzi, hogy egy API-hívás továbbfejlesztett frissítést váltott ki. |
startTime |
karakterlánc | A frissítés kezdete és időpontja. |
endTime |
Sztring | A frissítés befejezésének dátuma és időpontja. |
status |
Karakterlánc |
Completed azt jelzi, hogy a frissítési művelet sikeresen befejeződött. Failed azt jelzi, hogy a frissítési művelet sikertelen volt. Unknown azt jelzi, hogy a befejezési állapot nem határozható meg. Ezzel az állapottal endTime üres. A Disabled azt jelzi, hogy a frissítés szelektív letiltása történt. Cancelled jelzi, hogy a frissítés sikeresen megszakadt. |
extendedStatus |
Húr | Bővíti a status tulajdonságot, hogy további információt nyújtson. |
Jegyzet
Az Azure Analysis Servicesben a befejezett status
eredmény succeeded
. Ha migrál egy Azure Analysis Services-megoldást a Power BI-ba, előfordulhat, hogy módosítania kell a megoldásait.
A visszaadott frissítési műveletek számának korlátozása
A Power BI REST API támogatja a frissítési előzményekben kért bejegyzések számának korlátozását az opcionális $top
paraméter használatával. Ha nincs megadva, alapértelmezés szerint az összes elérhető bejegyzés.
GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}
GET /refreshes/<requestId>
A frissítési művelet állapotának ellenőrzéséhez használja a GET parancsot a frissítési objektumon a requestId
megadásával. Ha a művelet folyamatban van, status
InProgress
ad vissza, ahogyan az alábbi példaválasz törzsében látható:
{
"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>
Folyamatban lévő bővített frissítési művelet megszakításához használja a DELETE parancsot a frissítési objektumon a requestId
megadásával.
Például
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
Szempontok és korlátozások
A frissítési művelet a következő szempontokat és korlátozásokat tartalmazza:
Standard frissítési műveletek
- A portál frissítés gombjának
DELETE /refreshes/<requestId>
használatával aktivált ütemezett vagy igény szerinti modellfrissítések nem szakíthatók meg. - A portál frissítés gombjának kiválasztásával aktivált ütemezett és igény szerinti modellfrissítések nem támogatják a frissítési művelet részleteinek lekérését
GET /refreshes/<requestId>
. - A részletek lekérése és a Mégse funkció csak a továbbfejlesztett frissítéshez használható új műveletek. A standard frissítés nem támogatja ezeket a műveleteket.
Power BI Embedded
Ha a kapacitást manuálisan szünetelteti a Power BI portálon vagy a PowerShell használatával, vagy rendszerkimaradás történik, a folyamatban lévő továbbfejlesztett frissítési művelet állapota legfeljebb hat órán keresztül InProgress
marad. Ha a kapacitás hat órán belül újraindul, a frissítési művelet automatikusan folytatódik. Ha a kapacitás több mint hat óra elteltével folytatódik, a frissítési művelet időtúllépési hibát eredményezhet. Ezután újra kell indítania a frissítési műveletet.
Szemantikai modell kizárása
A Power BI dinamikus memóriakezelést használ a kapacitásmemória optimalizálásához. Ha a modell egy frissítési művelet során ki van távolítva a memóriából, a következő hiba fordulhat elő:
{
"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"
}
]
}
A megoldás a frissítési művelet újrafuttatása. A dinamikus memóriakezelésről és a modellkivonásról további információt a Modell kivonásicímű témakörben talál.
A frissítési művelet időkorlátjai
A frissítési művelet több kísérletet is tartalmazhat, ha retryCount
van megadva. Minden kísérlethez 5 óra alapértelmezett időtúllépés tartozik, amely a timeout
paraméterrel módosítható. A frissítés teljes időtartama, beleértve az újrapróbálkozásokat is, nem haladhatja meg a 24 órát.
Ha retryCount
egy számot ad meg, egy új frissítési művelet az időtúllépési korláttal kezdődik. A szolgáltatás mindaddig újrapróbálkozza ezt a műveletet, amíg nem sikerül, el nem éri a retryCount
korlátot, vagy eléri az első kísérlettől kezdve a 24 órás maximumot.
Módosíthatja a timeout
, hogy lerövidítse a frissítés időtartamát a gyorsabb hibaészlelés érdekében, vagy hosszabbítsa meg az alapértelmezett 5 órát az összetettebb adatfrissítések esetében.
Ha a szemantikai modell frissítését a Refresh Dataset REST API-val tervezi, vegye figyelembe az időkorlátokat és az újrapróbálkozási szám paramétert. A frissítés túllépheti az időtúllépést, ha a kezdeti kísérlet meghiúsul, és az újrapróbálkozási szám értéke 1 vagy több. Ha "retryCount" típusú frissítést kér: 1, és az első kísérlet 4 óra után meghiúsul, megkezdődik egy második kísérlet. Ha ez 3 órán belül sikerül, a frissítés teljes ideje 7 óra.
Ha a frissítési műveletek rendszeresen sikertelenek, túllépik az időtúllépési időkorlátot, vagy túllépik a kívánt sikeres frissítési művelet időtartamát, érdemes lehet csökkenteni az adatforrásból frissítendő adatok mennyiségét. A frissítést több kérelemre is feloszthatja, például az egyes táblákra vonatkozó kéréseket. A commitMode paraméterben a partialBatch paramétert is megadhatja.
Kódminta
A kezdéshez egy C# kódminta található a GitHubon RestApiSample néven.
A kódminta használata:
- Klónozza vagy töltse le az adattárat.
- Nyissa meg a RestApiSample-megoldást.
- Keresse meg a sort
client.BaseAddress = …
, és adja meg a alap URL-címét.
A kódminta szolgáltatásnév-azonosító hitelesítést használ.