Parannettu päivitys Power BI REST -ohjelmointirajapinnan avulla

Artikkeli
01/08/2024

Voit käyttää mitä tahansa ohjelmointikieltä, joka tukee REST-kutsuja, semanttisen mallin päivitystoiminnon suorittamiseen Power BI:n päivitystietojoukon REST-ohjelmointirajapinnan avulla.

Suurten ja monimutkaisten osioitujen mallien optimoitu päivitys käynnistetään perinteisesti ohjelmointimenetelmillä, joissa käytetään TOM:tä (taulukko-objektimalli), PowerShellin cmdlet-komentoja tai TMSL:ää (taulukkomallin komentosarjakieli). Nämä menetelmät edellyttävät kuitenkin pitkäkestoisia HTTP-yhteyksiä, jotka voivat olla epäluotettavia.

Power BI:n päivitystietojoukon REST-ohjelmointirajapinta voi suorittaa mallin päivitystoimintoja asynkronisesti, joten asiakassovellusten pitkäkestoiset HTTP-yhteydet eivät ole välttämättömiä. Vakiopäivitystoimintoihin verrattuna REST-ohjelmointirajapinnan parannettu päivitys tarjoaa enemmän mukautusasetuksia ja seuraavat ominaisuudet, joista on hyötyä suurissa malleissa:

Eristetyt vahvistukset
Taulukko- ja osiotason päivitys
Lisäävän päivityksen käytäntöjen käyttäminen
GET päivitystiedot
Päivityksen peruuttaminen

Muistiinpano

Aiemmin parannettua päivitystä kutsuttiin asynkroniseksi päivitykseksi REST-ohjelmointirajapinnalla. Päivitystietojoukon REST-ohjelmointirajapintaa käyttävä vakiopäivitys suoritetaan kuitenkin myös asynkronisesti sen luonteen mukaan.
Parannetut Power BI:n REST-ohjelmointirajapinnan päivitystoiminnot eivät päivitä ruudun välimuisteja automaattisesti. Ruudun välimuistit päivittyvät vain, kun käyttäjä käyttää raporttia.

URL-perusosoite

Perus-URL-osoite on seuraavassa muodossa:

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

Voit liittää resursseja ja toimintoja URL-perusosoitteeseen parametrien perusteella. Seuraavassa kaaviossa ryhmät, tietojoukot ja päivitykset ovat kokoelmia. Ryhmä, Tietojoukko ja Päivitys ovat objekteja.

Diagram that shows asynchronous refresh flow.

Edellytykset

REST-ohjelmointirajapinnan käyttämiseen tarvitaan seuraavat vaatimukset:

Semanttinen malli Power BI Premiumissa, käyttäjäkohtainen Premium tai Power BI Embeddedissä.
Pyynnön URL-osoitteessa käytettävä ryhmän tunnus ja tietojoukon tunnus.
Dataset.ReadWrite.All permission scope.

Päivitysten määrä on rajoitettu ohjelmointirajapintapohjaisten päivitysten yleisten rajoitusten mukaan Pro- ja Premium-malleille.

Todentaminen

Kaikkien kutsujen on todennettava valtuutusotsikossa kelvollisella Microsoft Entra ID OAuth 2 -tunnuksella. Tunnuksen on täytettävä seuraavat vaatimukset:

Voit olla joko käyttäjätunnus tai sovelluksen palvelun päänimi.
Määritä yleisön arvoksi https://api.powerbi.comoikein .
Oltava sellaisen käyttäjän tai sovelluksen käytössä, jolla on riittävät käyttöoikeudet malliin.

Muistiinpano

REST-ohjelmointirajapinnan muutokset eivät muuta tällä hetkellä määritettyjä mallin päivitysten käyttöoikeuksia.

JULKAISE /päivitykset

Voit tehdä päivityksen lisäämällä kokoelmaan uuden päivitysobjektin /refreshes-kokoelman POST-verbillä. Vastauksen Sijainti-otsikko sisältää kohteen requestId. Koska toiminto on asynkroninen, asiakassovellus voi katkaista yhteyden ja tarkistaa tilan tarvittaessa myöhemmin - requestId parametrilla.

Seuraava koodi näyttää mallipyynnön:

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

Pyynnön runko voi muistuttaa seuraavaa esimerkkiä:

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

Muistiinpano

Palvelu hyväksyy mallille vain yhden päivitystoiminnon kerrallaan. Jos käynnissä oleva päivitys on käynnissä ja toinen pyyntö lähetetään, 400 Bad Request HTTP-tilakoodi palautuu.

Parametrit

Jos haluat tehdä parannetun päivitystoiminnon, sinun on määritettävä yksi tai useampi parametri pyynnön leipätekstissä. Määritetyt parametrit voivat määrittää oletusarvon tai valinnaisen arvon. Kun pyyntö määrittää parametrit, kaikki muut parametrit koskevat toimintoa niiden oletusarvoilla. Jos pyyntö ei määritä parametreja, kaikki parametrit käyttävät oletusarvojaan ja suoritetaan vakiopäivitystoiminto.

Nimi	Type	Oletus	Kuvaus
`type`	Luettelointi	`automatic`	Suoritettavan prosessoinnin tyyppi. Tyypit ovat tasassa TMSL-päivityskomentotyyppien kanssa: `full`, , `clearValuescalculate`, `dataOnly`, `automatic`, ja `defragment`. - `add` tyyppiä ei tueta.
`commitMode`	Luettelointi	`transactional`	Määrittää, lähetetäänkö objekteja erissä vai vain, kun ne ovat valmiita. Tilat ovat `transactional` ja `partialBatch`. Kun käytät `partialBatch` päivitystoimintoa, se ei tapahdu yhdessä tapahtumassa. Jokainen komento on varattu erikseen. Jos virhe ilmenee, malli voi olla tyhjä tai sisältää vain tietojen alijoukon. Voit suojautua epäonnistumiselta ja säilyttää mallin tiedot ennen toiminnon käynnistämistä suorittamalla toiminnon palvelussa `commitMode = transactional`.
`maxParallelism`	Int	`10`	Määrittää niiden säikeiden enimmäismäärän, jotka voivat suorittaa käsittelykomentoja rinnakkain. Tämä arvo on linjassa sen ominaisuuden `MaxParallelism` kanssa, joka voidaan määrittää TMSL-komennolla `Sequence` tai muilla menetelmillä.
`retryCount`	Int	`0`	Kuinka monta kertaa toiminto itkee uudelleen ennen epäonnistumista.
`objects`	Matriisi	Koko malli	Käsiteltävä objektimatriisi. Jokainen objekti sisältää`table`, kun käsitellään kokonaista taulukkoa tai `partitiontable` kun käsitellään osiota. Jos objekteja ei määritetä, koko malli päivittyy.
`applyRefreshPolicy`	Boolean	`true`	Jos lisäävän päivityksen käytäntö on määritetty, määritetään, otetaanko käytäntö käyttöön. Tilat ovat `true` tai `false`. Jos käytäntöä ei käytetä, koko prosessi jättää osion määritelmät muuttumatta ja päivittää kaikki taulukon osiot. Jos `commitMode` on `transactional`, `applyRefreshPolicy` voi olla `true` tai `false`. Jos `commitMode` on `partialBatch`, `applyRefreshPolicy` / `true` ei ole tuettu, ja `applyRefreshPolicy` sen arvona `false`on oltava .
`effectiveDate`	Päivämäärä	Nykyinen päivämäärä	Jos lisäävän päivityksen käytäntöä käytetään, `effectiveDate` parametri ohittaa nykyisen päivämäärän. Jos tätä ei määritetä, nykyisen päivän määrittämiseen käytetään UTC-kohdetta.

Response

202 Accepted

Vastaus sisältää myös vastausotsikon kentän, joka Location osoittaa soittajan luotuun ja hyväksyttyun päivitystoimintoon. Location on pyynnön luoman uuden resurssin sijainti, joka sisältää requestId parannetut päivitystoiminnot. Esimerkiksi seuraavassa vastauksessa requestId on vastauksen 87f31ef7-1e3a-4006-9b0b-191693e79e9eviimeinen tunniste .

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

HAE/päivitä

Luettele historialliset, nykyiset ja odottavat päivitystoiminnot käyttämällä /refreshs-kokoelman GET-verbiä.

Vastauksen leipäteksti voi näyttää seuraavan esimerkin kaltaiselta:

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

Muistiinpano

Power BI saattaa pudottaa pyynnöt, jos pyyntöjä on liian paljon lyhyessä ajassa. Power BI päivittää tiedot, siirtää jonoon seuraavan pyynnön ja jättää pois kaikki muut. Pudotetuille pyynnöille ei voi tehdä kyselytilaa.

Vastauksen ominaisuudet

Nimi	Laji	Kuvaus
`requestId`	Guid	Päivityspyynnön tunnus. Sinun on `requestId` tehtävä kysely yksittäisen päivitystoiminnon tilasta tai peruutettava käynnissä oleva päivitystoiminto.
`refreshType`	Merkkijono	`OnDemand` ilmaisee, että päivitys käynnistettiin vuorovaikutteisesti Power BI -portaalin kautta. `Scheduled` ilmaisee, että mallin päivitysaikataulu käynnisti päivityksen. `ViaApi` ilmaisee, että ohjelmointirajapinnan kutsu käynnisti päivityksen. `ViaEnhancedApi` ilmaisee, että ohjelmointirajapinnan kutsu käynnisti parannetun päivityksen.
`startTime`	Merkkijono	Päivityksen alkamispäivämäärä ja -aika.
`endTime`	Merkkijono	Päivityksen päättymispäivä ja -aika.
`status`	Merkkijono	`Completed` ilmaisee, että päivitystoiminto suoritettiin onnistuneesti. `Failed` ilmaisee, että päivitystoiminto epäonnistui. `Unknown` ilmaisee, että valmistumistilaa ei voida määrittää. Kun tämä tila on, `endTime` on tyhjä. `Disabled` ilmaisee, että valikoiva päivitys poisti päivityksen käytöstä. `Cancelled` ilmaisee, että päivitys peruutettiin onnistuneesti.
`extendedStatus`	Merkkijono	Laajentaa -ominaisuutta `status` ja antaa lisätietoja.

Muistiinpano

Azure Analysis Servicesissä valmis status tulos on succeeded. Jos siirrät Azure Analysis Services -ratkaisun Power BI:hin, saatat joutua muokkaamaan ratkaisujasi.

Rajoita palautettujen päivitystoimintojen määrää

Power BI:n REST-ohjelmointirajapinta tukee päivityshistorian pyydettyjen merkintöjen määrän rajoittamista valinnaisen $top parametrin avulla. Jos tätä ei määritetä, oletusarvo on kaikki käytettävissä olevat merkinnät.

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

GET /refreshes/<requestId>

Voit tarkistaa päivitystoiminnon tilan käyttämällä päivitysobjektin GET-verbiä määrittämällä requestId. Jos toiminto on käynnissä, status palauttaa InProgressarvon , kuten seuraavassa esimerkkivastauksen leipätekstissä:

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

POISTA /päivitykset/<pyyntötunnus>

Jos haluat peruuttaa keskeneräisen parannetun päivitystoiminnon, käytä päivitysobjektin DELETE-verbiä määrittämällä requestId.

Esimerkiksi

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

Huomioitavat asiat ja rajoitukset

Päivitystoiminnossa on seuraavat huomioitavat asiat ja rajoitukset:

Vakiopäivitystoiminnot

Et voi peruuttaa ajoitettuja tai manuaalisia manuaalisia mallipäivityksiä :n avulla DELETE /refreshes/<requestId>.
Ajoitetut ja manuaaliset manuaaliset mallin päivitykset eivät tue päivitystoiminnon tietojen saamista :n avulla GET /refreshes/<requestId>.
Hanki tiedot ja Peruuta ovat uusia toimintoja vain parannetuille päivityksille. Vakiopäivitys ei tue näitä toimintoja.

Power BI Embedded

Jos kapasiteetti keskeytetään manuaalisesti Power BI -portaalissa tai PowerShellin avulla tai jos järjestelmässä tapahtuu katkos, käynnissä olevan parannetun päivityksen toiminnon tila on InProgress enintään kuusi tuntia. Jos kapasiteetti jatkaa kuuden tunnin kuluessa, päivitystoiminto jatkuu automaattisesti. Jos kapasiteetti jatkaa yli kuuden tunnin kuluttua, päivitystoiminto saattaa palauttaa aikakatkaisuvirheen. Päivitystoiminto on käynnistettävä uudelleen.

Semanttisen mallin häätö

Power BI käyttää dynaamista muistinhallintaa kapasiteetin muistin optimoinniin. Jos malli häädetään muistista päivitystoiminnon aikana, seuraava virhe saattaa palauttaa:

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

Ratkaisu on päivittää toiminto uudelleen. Lisätietoja dynaamisesta muistinhallinnasta ja mallin häädöstä on artikkelissa Mallin häätö.

Päivitystoiminnon aikarajat

Yksittäisen päivitystoiminnon enimmäisaika on viisi tuntia. Jos päivitystoiminto ei onnistu viiden tunnin rajoituksen puitteissa eikä retryCount sitä ole määritetty 0 (oletus) pyynnön leipätekstissä, aikakatkaisuvirhe palauttaa aikakatkaisuvirheen.

Jos retryCount määritetään 1 tai jokin muu luku, aloitetaan uusi viiden tunnin rajoitus oleva päivitystoiminto. Jos tämä uudelleenyritysten toiminto epäonnistuu, palvelu yrittää uudelleen päivitystoimintoa enintään suurimpaan määrään uudelleenyritysten määrää tai parannetun päivityksen käsittelyn aikarajan, joka retryCount on 24 tuntia ensimmäisen päivityspyynnön alusta.

Kun suunnittelet parannetun mallin päivitysratkaisun Päivitä tietojoukko REST -ohjelmointirajapinnan avulla, on tärkeää huomioida nämä aikarajat ja retryCount parametri. Onnistunut päivityksen valmistuminen voi olla yli viisi tuntia, jos ensimmäinen päivitystoiminto epäonnistuu, ja retryCount määrittää 1 tai enemmän.

Jos esimerkiksi pyydät päivitystoimintoa :n avulla "retryCount": 1ja ensimmäinen uudelleenyritysten toiminto epäonnistuu neljä tuntia alkamisajasta, käynnistetään toinen päivitystoiminto pyynnölle. Jos tämä toinen päivitystoiminto onnistuu kolmen tunnin kuluessa, päivityspyynnön onnistuneen suorittamisen kokonaisaika on seitsemän tuntia.

Jos päivitystoiminnot epäonnistuvat säännöllisesti, ylität viiden tunnin aikarajan tai ylität haluamasi onnistuneen päivityksen käyttöajan, harkitse tietolähteestä päivitettävien tietojen määrän pienentämistä. Voit jakaa päivityksen useisiin pyyntöihin, esimerkiksi kullekin taulukolle pyynnön. Voit määrittää partialBatch myös -parametrissa commitMode .

Koodiesimerkki

C#-koodiesimerkki on artikkelissa RestApiSample GitHubissa.

Koodimallin käyttäminen:

Kloonaa tai lataa säilö.
Avaa RestApiSample-ratkaisu.
Etsi rivi client.BaseAddress = … ja anna perus-URL-osoite.

Koodimalli käyttää palvelun päänimen todentamista.

Jaa

Parannettu päivitys Power BI REST -ohjelmointirajapinnan avulla

URL-perusosoite

Edellytykset

Todentaminen

JULKAISE /päivitykset

Parametrit

Response

HAE/päivitä

Vastauksen ominaisuudet

Rajoita palautettujen päivitystoimintojen määrää

GET /refreshes/<requestId>

POISTA /päivitykset/<pyyntötunnus>

Huomioitavat asiat ja rajoitukset

Vakiopäivitystoiminnot

Power BI Embedded

Semanttisen mallin häätö

Päivitystoiminnon aikarajat

Koodiesimerkki

Lisäresursseja

Jaa

Parannettu päivitys Power BI REST -ohjelmointirajapinnan avulla

URL-perusosoite

Edellytykset

Todentaminen

JULKAISE /päivitykset

Parametrit

Response

HAE/päivitä

Vastauksen ominaisuudet

Rajoita palautettujen päivitystoimintojen määrää

GET /refreshes/<requestId>

POISTA /päivitykset/<pyyntötunnus>

Huomioitavat asiat ja rajoitukset

Vakiopäivitystoiminnot

Power BI Embedded

Semanttisen mallin häätö

Päivitystoiminnon aikarajat

Koodiesimerkki

Liittyvä sisältö

Lisäresursseja