Parannettu päivitys Power BI REST -ohjelmointirajapinnan avulla

Artikkeli
12/20/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 parannettujen päivitysten REST-ohjelmointirajapinnalla 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äivityksen tiedot
Päivityksen peruuttaminen

Muistiinpano

Aiemmin parannettua päivitystä kutsuttiin asynkroniseksi päivitykseksi REST-ohjelmointirajapinnan. 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, ryhmät, tietojoukot, ja Päivitykset - ovat kokoelmia. Group, Dataset, ja Refresh ovat objektien .

kaavio, joka näyttää asynkronisen päivitystyönkulun.

Vaatimukset

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

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

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

Todennus

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 oikein https://api.powerbi.com.
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 Sijainnin otsikko sisältää requestId. Koska toiminto on asynkroninen, asiakassovellus voi katkaista yhteyden ja tarkistaa tilan tarvittaessa myöhemmin requestId avulla.

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, http-tilakoodin 400 Bad Request palautetaan.

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	Tyyppi	Laiminlyönti	Kuvaus
`type`	Luettelointi	`automatic`	Suoritettavan prosessoinnin tyyppi. Tyypit ovat TMSL-päivityskomentotyyppien mukaisia: `full`, `clearValues`, `calculate`, `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 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 `commitMode = transactional`.
`maxParallelism`	Int	`10`	Määrittää niiden säikeiden enimmäismäärän, jotka voivat suorittaa käsittelykomentoja rinnakkain. Tämä arvo on tasautunut TMSL `Sequence` -komennossa tai muilla menetelmillä määritettävän `MaxParallelism`-ominaisuuden kanssa.
`retryCount`	Int	`0`	Kuinka monta kertaa toiminto itkee uudelleen ennen epäonnistumista.
`objects`	Valikoima	Koko malli	Käsiteltävä objektimatriisi. Jokainen objekti sisältää `table`, kun käsitellään koko taulukkoa, tai `table` ja `partition` osiota käsiteltäessä. 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`, voit `applyRefreshPolicytrue` tai `false`. Jos `commitMode` on `partialBatch`, `trueapplyRefreshPolicy` ei ole tuettu ja `applyRefreshPolicy` on asetettava arvoksi `false`.
`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ä, nykyinen päivä määritetään käyttämällä aikavyöhykemääritystä kohdassa "Päivitä".

Vastaus

202 Accepted

Vastaus sisältää myös Location vastausotsikon kentän, joka osoittaa soittajan luodulle ja hyväksytylle päivitystoiminnolle. Location on pyynnön luoman uuden resurssin sijainti. Se sisältää requestId, joita jotkin parannetut päivitystoiminnot edellyttävät. Esimerkiksi seuraavassa vastauksessa requestId on vastaus 87f31ef7-1e3a-4006-9b0b-191693e79e9eviimeisenä tunnisteena.

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",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "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	Tyyppi	Kuvaus
`requestId`	Guid	Päivityspyynnön tunnus. Sinun on `requestId`, jotta voit suorittaa kyselyn yksittäisen päivitystoiminnon tilasta tai peruuttaa käynnissä olevan päivitystoiminnon.
`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ä suoritustilaa ei voi määrittää. Tässä tilassa `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 `status`-ominaisuutta 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 käyttämällä valinnaista $top-parametria. 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 päivitysobjektin GET-verbillä määrittämällä requestId. Jos toiminto on käynnissä, status palauttaa InProgressseuraavan esimerkkivastauksen leipätekstin mukaisesti:

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

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 pyydettäessä tehtyjä mallipäivityksiä, jotka käynnistettiin napsauttamalla portaalin päivityspainiketta DELETE /refreshes/<requestId>.
Ajoitetut ja pyynnöstä suoritetut mallipäivitykset, jotka käynnistettiin valitsemalla päivityspainike portaalissa, eivät tue päivitystoiminnon tietojen saamista GET /refreshes/<requestId>avulla.
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 ilmenee järjestelmän katkos, käynnissä olevan parannetun päivityksen toiminnon tila on InProgress enintään kuuden tunnin ajan. 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öistä 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 aikana eikä retryCount ole määritetty 0 (oletus) pyynnön leipätekstissä, aikakatkaisuvirhe palauttaa aikakatkaisuvirheen.

Jos retryCount määrittää 1 tai toisen luvun, aloitetaan uusi viiden tunnin rajoituksen aikainen päivitystoiminto. Jos tämä uudelleenyritysten toiminto epäonnistuu, palvelu yrittää uudelleen päivitystoimintoa enintään suurimmalla määrällä uudelleenyritysten määrää, jonka retryCount määrittää, tai parannetun päivityksen käsittelyn aikarajan, joka on 24 tuntia ensimmäisen päivityspyynnön alusta.

Kun suunnittelet parannetun mallin päivitysratkaisun Päivitystietojoukon 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ää vähintään 1.

Jos esimerkiksi pyydät päivitystoimintoa "retryCount": 1, ja ensimmäinen uudelleenyritysten toiminto epäonnistuu neljän tunnin kuluttua 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 myös määrittää partialBatchcommitMode-parametrissa.

Koodiesimerkki

C#-koodiesimerkki on artikkelissa RestApiSample GitHubissa.

Koodimallin käyttäminen:

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

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

Jaa

Parannettu päivitys Power BI REST -ohjelmointirajapinnan avulla

URL-perusosoite

Vaatimukset

Todennus

JULKAISE /päivitykset

Parametrit

Vastaus

HAE/päivitä

Vastauksen ominaisuudet

Rajoita palautettujen päivitystoimintojen määrää

GET/refreshes/<requestId>

Delete/refreshes/<requestId->

Huomioitavat asiat ja rajoitukset

Vakiopäivitystoiminnot

Power BI Embedded

Semanttisen mallin häätö

Päivitystoiminnon aikarajat

Koodiesimerkki

Palaute

Lisäresursseja

Jaa

Parannettu päivitys Power BI REST -ohjelmointirajapinnan avulla

URL-perusosoite

Vaatimukset

Todennus

JULKAISE /päivitykset

Parametrit

Vastaus

HAE/päivitä

Vastauksen ominaisuudet

Rajoita palautettujen päivitystoimintojen määrää

GET/refreshes/<requestId>

Delete/refreshes/<requestId->

Huomioitavat asiat ja rajoitukset

Vakiopäivitystoiminnot

Power BI Embedded

Semanttisen mallin häätö

Päivitystoiminnon aikarajat

Koodiesimerkki

Aiheeseen liittyvä sisältö

Palaute

Lisäresursseja