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.

aszinkron frissítési folyamatot bemutató diagram.

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/aaaabbbb-0000-cccc-1111-dddd2222eeee/datasets/bbbbcccc-1111-dddd-2222-eeee3333ffff/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`	Enumeráció	`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 `MaxParallelism` parancsban vagy más metódusok használatával beállítható `Sequence` 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`	logikai	`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 `commitModetransactional`, `applyRefreshPolicy` lehet `true` vagy `false`. Ha `commitModepartialBatch`, `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 ccccdddd-2222-eeee-3333-ffff4444aaaautolsó azonosítója.

x-ms-request-id: ccccdddd-2222-eeee-3333-ffff4444aaaa
Location: https://api.powerbi.com/v1.0/myorg/groups/aaaabbbb-0000-cccc-1111-dddd2222eeee/datasets/bbbbcccc-1111-dddd-2222-eeee3333ffff/refreshes/ccccdddd-2222-eeee-3333-ffff4444aaaa

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": "ddddeeee-3333-ffff-4444-aaaa5555bbbb",
        "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`	karakterlánc	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`	karakterlánc	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 requestIdmegadásával. Ha a művelet folyamatban van, statusInProgressad 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 requestIdmegadásával.

Például

DELETE https://api.powerbi.com/v1.0/myorg/groups/aaaabbbb-0000-cccc-1111-dddd2222eeee/datasets/bbbbcccc-1111-dddd-2222-eeee3333ffff/refreshes/ddddeeee-3333-ffff-4444-aaaa5555bbbb

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.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-01-08

Továbbfejlesztett frissítés a Power BI REST API-val

Alap URL-cím

Követelmények

Hitelesítés

POST /frissítések

Paraméterek

Válasz

GET /refreshs

Válasz jellemzői

A visszaadott frissítési műveletek számának korlátozása

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

Szempontok és korlátozások

Standard frissítési műveletek

Power BI Embedded

Szemantikai modell kizárása

A frissítési művelet időkorlátjai

Kódminta

Kapcsolódó tartalom

Visszajelzés

További források