Jaa

Parannettu päivitys Power BI REST -ohjelmointirajapinnan avulla

  • Artikkeli

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
  • Aikakatkaisun määritys

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,
    "timeout": "02:00:00",
    "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, automaticja 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 MaxParallelism -komennossa tai muilla menetelmillä määritettävän Sequence-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, applyRefreshPolicytrue 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ä".
timeout Merkkijono 05.00.00 (5 tuntia) Jos timeout määritetään, jokainen semanttisen mallin tietojen päivitysyritys noudattaa tätä aikakatkaisua. Yksittäinen päivityspyyntö voi sisältää useita yrityksiä, jos määritetään retryCount. Tämä voi aiheuttaa sen, että päivityksen kokonaiskesto ylittää määritetyn aikakatkaisun. Jos esimerkiksi määrität yhden tunnin timeout ja retryCount 2, päivityksen kokonaiskesto voi olla enintään 3 tuntia. Käyttäjät voivat säätää timeout, jos haluat lyhentää päivityksen kestoa, jolloin virhe havaitaan nopeammin, tai pidentää sitä oletusarvon mukaisesta viisi tuntia monimutkaisemmille tietojen päivityksille. Päivityksen kokonaiskesto uudelleenotot mukaan lukien eivät voi kuitenkaan olla yli 24 tuntia.

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

Päivitystoiminto voi sisältää useita yrityksiä, jos retryCount määritetään. Kunkin yrityksen oletusaikakatkaisu on 5 tuntia, jota voidaan muuttaa timeout-parametrilla. Päivityksen kokonaiskesto uudelleenries mukaan lukien ei saa olla yli 24 tuntia.

Jos retryCount määrittää luvun, uusi päivitystoiminto alkaa aikakatkaisurajasta. Palvelu yrittää tehdä tämän toiminnon uudelleen, kunnes se joko onnistuu, saavuttaa retryCount rajan tai ylittää 24 tunnin maksimin ensimmäisestä yrityksestä.

Voit säätää timeout, jos haluat lyhentää päivityksen kestoa, jolloin virhe havaitaan nopeammin, tai pidentää sitä yli monimutkaisempien tietojen päivitysten oletusarvon mukaisen viisi tuntia.

Kun suunnittelet semanttista mallin päivitystä Päivitä tietojoukon REST-ohjelmointirajapinnan avulla, ota huomioon aikarajat ja uudelleentryCount-parametri. Päivitys voi ylittää aikakatkaisun, jos ensimmäinen yritys epäonnistuu ja yritä uudelleenMäärä-arvoksi on asetettu 1 tai enemmän. Jos pyydät päivitystä "retryCount"-arvolla: 1 ja ensimmäinen yritys epäonnistuu 4 tunnin kuluttua, toinen yritys käynnistyy. Jos tämä onnistuu kolmen tunnin kuluessa, päivityksen kokonaisaika on 7 tuntia.

Jos päivitystoiminnot epäonnistuvat säännöllisesti, ylittävät aikakatkaisun aikarajan tai ylittävä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ää partialBatch-ominaisuuden commitMode-parametrissa.

Koodiesimerkki

C#-koodiesimerkki on artikkelissa RestApiSample GitHubissa.

Koodimallin käyttäminen:

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

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

Aiheeseen liittyvä sisältö