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

  • Cikk

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 végzett továbbfejlesztett frissítés további testreszabási lehetőségeket és a nagy modellekhez hasznos alábbi funkciókat nyújt:

  • 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

Feljegyzés

  • Korábban a bővített frissítést aszinkron frissítésnek nevezték a REST API-val. 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 csempegyorsítótárak csak akkor frissülnek, ha egy felhasználó hozzáfér egy jelentéshez.

Kiindulási 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 a Csoportok, az Adatkészletek és a Frissítések gyűjtemények. A csoportosítás, az adatkészlet és a frissítés objektumok.

Diagram that shows asynchronous refresh flow.

Követelmények

A REST API használatához a következő követelmények szükségesek:

  • Szemantikai modell a Power BI Premiumban, felhasználónkénti Premium vagy Power BI Embeddedben.
  • A kérelem URL-címében használandó csoportazonosító és adatkészlet-azonosító.
  • Dataset.ReadWrite.All engedély hatóköre.

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 jogkivonattal az Engedélyezés fejlécben. A jogkivonatnak meg kell felelnie a következő követelményeknek:

  • Legyen felhasználói jogkivonat vagy alkalmazásszolgáltatás-tag.
  • Állítsa be a célközönséget helyesen a következőre https://api.powerbi.com: .
  • Olyan felhasználó vagy alkalmazás használhatja, amely rendelkezik a modellre vonatkozó megfelelő engedélyekkel.

Feljegyzés

A REST API-módosítások nem módosítják a modellfrissítések jelenleg definiált engedélyeit.

POST /refreshs

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álaszBan a Hely fejléc tartalmazza a requestId. Mivel a művelet aszinkron, az ügyfélalkalmazások leválaszthatják a kapcsolatot, és szükség requestId esetén később 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,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Feljegyzés

A szolgáltatás egyszerre csak egy frissítési műveletet fogad el egy modellhez. Ha folyamatban van egy aktuális frissítés, é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 Enum 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 és partialBatcha transactional . A frissítési művelet használata partialBatch nem egy tranzakción belül történik. Az egyes parancsok külön-külön lesznek véglegesve. 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éséhez hajtsa végre a műveletet a következővel 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 MaxParallelism érték a TMSL Sequence parancsban vagy más metódusok használatával beállítható 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 magában foglalja table egy teljes tábla feldolgozását, vagy partitiontable egy partíció feldolgozását. 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 a következők: 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 igen transactional, applyRefreshPolicy lehet true vagy false. Ha commitMode igen partialBatch, applyRefreshPolicy az értéke true nem támogatott, és applyRefreshPolicy a következőre kell állítani: false.
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 UTC az aktuális nap meghatározására szolgál.

Válasz

202 Accepted

A válasz tartalmaz egy Location válaszfejmezőt is, amely a hívót a létrehozott és elfogadott frissítési műveletre mutatja. A Location kérelem által létrehozott új erőforrás helye, amely magában foglalja a requestId továbbfejlesztett frissítési műveletekhez szükséges helyet. Az alábbi válaszban requestId például a válasz 87f31ef7-1e3a-4006-9b0b-191693e79e9eutolsó 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",
        "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"
    }
]

Feljegyzés

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álasztulajdonságok

Név Típus Leírás
requestId GUID A frissítési kérelem azonosítója. Le kell kérdeznie az egyes frissítési műveletek állapotát, vagy le kell requestId mondania egy folyamatban lévő frissítési műveletet.
refreshType Sztring OnDemand azt jelzi, hogy a frissítés interaktív módon aktiválódott a Power BI portálon.
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 Sztring A frissítés kezdete és időpontja.
endTime Sztring A frissítés befejezésének dátuma és időpontja.
status Sztring Completed azt jelzi, hogy a frissítési művelet sikeresen befejeződött.
Failed azt jelzi, hogy a frissítési művelet meghiúsult.
Unknown azt jelzi, hogy a befejezési állapot nem határozható meg. Ezzel az állapottal üres endTime .
Disabled azt jelzi, hogy a frissítés szelektív frissítéssel lett letiltva.
Cancelled azt jelzi, hogy a frissítés sikeresen megszakadt.
extendedStatus Sztring Bővíti a status tulajdonságot, hogy további információt nyújtson.

Feljegyzés

Az Azure Analysis Servicesben a befejezett status eredmény az 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, az alapértelmezett érték 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 requestIdbeállítás megadásával. Ha a művelet folyamatban van, status a következő példaválasz törzséhez hasonlóan ad vissza eredményt InProgress:

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

A 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 requestIdkövetkező 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

  • Az ütemezett vagy igény szerinti manuális modellfrissítéseket nem szakíthatja meg a használatával DELETE /refreshes/<requestId>.
  • Az ütemezett és igény szerinti manuális modellfrissítések nem támogatják a frissítési művelet részleteinek lekérését a használatával 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űveletek állapota legfeljebb hat óráig tart InProgress . Ha a kapacitás hat órán belül újraindul, a frissítési művelet automatikusan folytatódik. Ha a kapacitás hat óránál tovább 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 modellkilakoltatásról további információt a Modell kizárása című témakörben talál.

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

Egyetlen frissítési művelet maximális időtartama öt óra. Ha a frissítési művelet nem fejeződik be az öt órás korláton belül, és retryCount nincs megadva, vagy a kérés törzsében (alapértelmezettként) van megadva 0 , időtúllépési hiba jelenik meg.

Ha retryCount megadja 1 vagy egy másik számot, egy új, ötórás korláttal rendelkező frissítési művelet indul el. Ha ez az újrapróbálkozási művelet meghiúsul, a szolgáltatás továbbra is újrapróbálkozza a frissítési műveletet a megadott legnagyobb számú újrapróbálkozásig retryCount , vagy az első frissítési kérelem kezdetétől számítva 24 órás bővített frissítésfeldolgozási időkorlátig.

Ha a továbbfejlesztett modellfrissítési megoldást a Refresh Dataset REST API-val tervezi, fontos figyelembe venni ezeket az időkorlátokat és a paramétert retryCount . A sikeres frissítés végrehajtása öt órát is meghaladhat, ha egy kezdeti frissítési művelet meghiúsul, és retryCount megadja 1 vagy tovább.

Ha például frissítési műveletet "retryCount": 1kér, és a kezdeti újrapróbálkozási művelet a kezdési időponttól számítva négy órával meghiúsul, megkezdődik a kérés második frissítési művelete. Ha a második frissítési művelet három órán belül sikeres lesz, a frissítési kérelem sikeres végrehajtásának teljes időtartama hét óra.

Ha a frissítési műveletek rendszeresen sikertelenek, túllépik az ötórás időtartamot, 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 paraméterben commitMode is megadhatópartialBatch.

Kódminta

Az első lépésekhez C#-kódmintát a RestApiSample a GitHubon című témakörben talál.

A kódminta használata:

  1. Klónozza vagy töltse le az adattárat.
  2. Nyissa meg a RestApiSample-megoldást.
  3. Keresse meg a sort client.BaseAddress = … , és adja meg az alap URL-címet.

A kódminta szolgáltatásnév-hitelesítést használ.

Kapcsolódó tartalom