Jaa

Microsoft Fabric -kuormituksen todentamisen ohjeiden yleiskatsaus

  • Artikkeli

Tässä artikkelissa on ohjeita siitä, miten todennusta käsitellään, kun luot Microsoft Fabric -kuormituksia. Se sisältää tietoja tunnusten ja suostumusten käsittelemisestä.

Ennen kuin aloitat, varmista, että olet tutustunut käsitteisiin kohdassa Authentication overview and Authentication setup.

Tietotason ja ohjaustason ohjelmointirajapinnat

  • Tietotason ohjelmointirajapinnat ovat ohjelmointirajapintoja, jotka kuormituksen tausta paljastaa. Kuormituksen edusta voi kutsua suoraan. Tietotason ohjelmointirajapinnoille kuormituksen taustatiedot voivat päättää, mitä ohjelmointirajapintoja paljastaa.

  • Control -tason ohjelmointirajapinnat ovat Fabricin kautta olevia ohjelmointirajapintoja. Prosessi alkaa kuormituksen edustalla, joka kutsuu JavaScript-ohjelmointirajapinnan, ja se päättyy siihen, että Fabric kutsuu kuormituksen taustaksi. Esimerkki tällaisesta ohjelmointirajapinnasta on Luo kohde.

    Hallintatason ohjelmointirajapintojen osalta kuormituksen on noudatettava kuormituksen taustaliittymessä määritettyjä sopimuksia ja toteutettava nämä ohjelmointirajapinnat.

Ohjelmointirajapinnan välilehden paljastaminen kuormituksen sovelluksessa Microsoft Entra -tunnuksella

Näytä ohjelmointirajapinnan -välilehdessä sinun on lisättävä vaikutusalueet tason ohjelmointirajapinnoille ja tietotason ohjelmointirajapinnoille:

  • Ohjaustason ohjelmointirajapinnoille lisättyjen vaikutusalueiden tulisi määrittää Fabric Client for Workloads -sovellus valmiiksi sovellustunnuksella d2450708-699c-41e3-8077-b0c8341509aa. Nämä alueet sisältyvät tunnukseen, jonka kuormituksen tausta vastaanottaa, kun Fabric kutsuu sitä.

    Sinun on lisättävä vähintään yksi laajuus ohjaustason ohjelmointirajapinnalle, jotta työnkulku toimii.

  • Tietotason ohjelmointirajapinnoille lisättyjen vaikutusalueiden tulisi esimäärittää Microsoft Power BI sovellustunnuksella 871c010f-5e61-4fb1-83ac-98610a7e9110. Ne sisältyvät tunnukseen, jonka acquireAccessToken JavaScript-ohjelmointirajapinta palauttaa.

    Tietotason ohjelmointirajapintojen tapauksessa voit tämän välilehden avulla hallita eriytettyjä käyttöoikeuksia kullekin ohjelmointirajapinnalle, jonka kuormitus paljastaa. Ihannetapauksessa sinun kannattaa lisätä vaikutusaluejoukko kullekin ohjelmointirajapinnalle, jonka kuormituksen tausta paljastaa, ja vahvistaa, että saatu tunnus sisältää nämä alueet, kun kyseisiä ohjelmointirajapintoja kutsutaan asiakkaalta. Esimerkiksi:

    • Kuormitus paljastaa asiakkaalle kaksi ohjelmointirajapintaa, ReadData ja WriteData.
    • Kuormitus näyttää kaksi tietotason vaikutusaluetta, data.read ja data.write.
    • ReadData-ohjelmointirajapinnassa kuormitus vahvistaa, että data.read laajuus on tunnuksen mukana, ennen kuin se jatkaa työnkulkua. Sama koskee WriteData.

Ohjelmointirajapinnan käyttöoikeudet -välilehti kuormituksen sovelluksessa Microsoft Entra -tunnuksella

ohjelmointirajapinnan käyttöoikeudet -välilehdessä sinun on lisättävä kaikki vaikutusalueet, joihin kuormituksesi tarvitsee vaihtaa tunnus. Pakollinen lisättävä vaikutusalue on Fabric.Extend Power BI -palvelussa. Fabric-pyynnöt saattavat epäonnistua ilman tätä soveltamisalaa.

Tunnusten ja suostumusten käyttäminen

Kun käsittelet tietotason ohjelmointirajapintoja, kuormituksen edustan on hankittava tunnus kuormituksen taustakutsujen kutsuille.

Seuraavissa osioissa kuvataan, miten kuormituksen edustan tulee käyttää JavaScript -ohjelmointirajapinnan ja OBO-työnkulkuja kuormituksen ja ulkoisten palveluiden tunnusten hankkimiseen sekä suostumukseen.

Vaihe 1: Hanki tunnus

Kuormitus alkaa kysymällä tunnusta JavaScript-ohjelmointirajapinnan avulla ilman parametreja. Tämä kutsu voi aiheuttaa kaksi skenaariota:

  • Käyttäjä näkee suostumusikkunan kaikista staattisista riippuvuuksista (jotka on määritetty kuormituksen määrittämässä -ohjelmointirajapinnan käyttöoikeudet välilehdessä). Näin tapahtuu, jos käyttäjä ei ole osa sovelluksen kotivuokraajaa eikä käyttäjä ole aiemmin myöntänyt Microsoft Graphille lupaa tähän sovellukseen.

  • Käyttäjä ei näe suostumusikkunaa. Näin tapahtuu, jos käyttäjä on jo antanut vähintään kerran luvan Microsoft Graphille tätä sovellusta varten tai jos käyttäjä on osa sovelluksen kotivuokraajaa.

Molemmissa tilanteissa kuormituksen ei pitäisi välittää siitä, antoiko käyttäjä täyden suostumuksen kaikille riippuvuuksille (eikä voi tässä vaiheessa tietää). Vastaanotetun tunnuksen kohderyhmä on kuormituksen taustaryhmä, ja sen avulla voidaan kutsua kuormituksen taustatunnusta suoraan kuormituksen edustasta.

Vaihe 2: Yritä käyttää ulkoisia palveluita

Kuormituksen on ehkä päästävä palveluihin, jotka edellyttävät todentamista. Tätä käyttöä varten sen on suoritettava OBO-työnkulun , jossa se vaihtaa asiakkaaltaan tai Fabricilta saamansa tunnuksen toiseen palveluun. Tunnuksen vaihto saattaa epäonnistua, jos suostumus tai Jokin Microsoft Entran ehdollinen käyttöoikeuskäytäntö on määritetty resurssille, jolle kuormitus yrittää vaihtaa tunnusta.

Tämän ongelman ratkaisemiseksi on kuormituksen vastuulla levittää virhe asiakkaalle käsiteltäessä suoria kutsuja edustan ja taustan välillä. Kuormituksen vastuulla on myös levittää virhe asiakkaalle, kun hän käsittelee Fabricin kutsuja käyttämällä kuormituksen välitysvirhettä kuormitusviestinnässä.

Kun kuormitus levittää virheen, se voi kutsua acquireAccessToken JavaScript-ohjelmointirajapinnan suostumus- tai ehdollisten käyttöoikeuksien käytännön ongelman ratkaisemiseksi ja toiminnon uudelleen yrityksenä.

Jos tietotason ohjelmointirajapinta epäonnistuu, katso Monimenetelmäisen todentamisen käsittely, Ehdollinen käyttöoikeus ja lisäävän suostumuksen. Katso lentokoneen ohjelmointirajapintavirheiden hallinta kohdasta Kuormituksen tietoliikenne.

Esimerkkejä

Katsotaanpa kuormitusta, jonka on käytettävä kolmea Fabric-ohjelmointirajapintaa:

  • Luetteloi työtilat: GET https://api.fabric.microsoft.com/v1/workspaces

  • Luo varasto: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

  • Kirjoita Lakehouse-tiedostoon: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Jotta voit käyttää kyseisiä ohjelmointirajapintoja, kuormituksen taustan on vaihdettava tunnukset seuraaville soveltamisalueille:

  • Työtilojen luettelointi: https://analysis.windows.net/powerbi/api/Workspace.Read.All tai https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
  • Varaston luominen: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All tai https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
  • Lakehouse-tiedostoon kirjoittamisesta: https://storage.azure.com/user_impersonation

Muistiinpano

Löydät jokaisen Fabric-ohjelmointirajapinnan käyttöalueet tämän viiteartikkelin .

Aiemmin mainitut vaikutusalueet on määritettävä kuormitussovelluksessa kohdassa ohjelmointirajapinnan käyttöoikeudet.

Tutustutaan nyt esimerkkeihin skenaarioista, joita kuormitus saattaa kohdata.

Esimerkki 1

Oletetaan, että kuormituksen taustan ohjelmointirajapinnalla on tietotason ohjelmointirajapinta, joka hakee käyttäjän työtilat ja palauttaa ne asiakkaalle:

  1. Kuormituksen edusta pyytää tunnusta JavaScript-ohjelmointirajapinnan avulla.

  2. Kuormituksen edusta kutsuu kuormituksen taustan ohjelmointirajapintaa käyttäjän työtilojen hakemiseksi ja liittää tunnuksen pyynnössä.

  3. Kuormituksen taustapalvelu vahvistaa tunnuksen ja yrittää vaihtaa sen vaaditulle laajuudelle (esimerkiksi https://analysis.windows.net/powerbi/api/Workspace.Read.All).

  4. Kuormitus ei vaihda tunnusta määritetylle resurssille, koska käyttäjä ei antanut sovellukselle lupaa käyttää tätä resurssia (katso AADSTS-virhekoodit).

  5. Kuormituksen taustailmoitus levittää virheen kuormituksen eteen määrittämällä, että se tarvitsee suostumuksen kyseiselle resurssille. Kuormituksen edusta kutsuu acquireAccessToken JavaScript -ohjelmointirajapintaa ja tarjoaa additionalScopesToConsent:

    workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

    Vaihtoehtoisesti kuormitus voi pyytää suostumusta kaikille sovelluksen staattisille riippuvuuksilleen, joten se kutsuu JavaScript-ohjelmointirajapintaa ja tarjoaa promptFullConsent:

    workloadClient.auth.acquireAccessToken({promptFullConsent: true}).

Tämä kutsu antaa suostumusikkunan riippumatta siitä, onko käyttäjä antanut suostumuksensa joihinkin riippuvuuksia. Sen jälkeen kuormituksen edusta voi yrittää toimintoa uudelleen.

Muistiinpano

Jos tunnusten vaihto epäonnistuu edelleen suostumusvirheen vuoksi, käyttäjä ei ole antanut suostumustaan. Kuormituksen on käsiteltävä tällaisia skenaarioita. Voit esimerkiksi ilmoittaa käyttäjälle, että tämä ohjelmointirajapinta edellyttää suostumusta, eikä se toimi ilman sitä.

Esimerkki 2

Oletetaan, että kuormituksen taustan on käytettävä OneLakea Kohteen luomisen ohjelmointirajapinnassa (kutsu Fabricista työkuormaan):

  1. Kuormituksen edusta kutsuu Luo kohde JavaScript -ohjelmointirajapintaa.

  2. Kuormituksen taustatunnus vastaanottaa kutsun Fabricista ja poimii delegoidun tunnuksen ja vahvistaa sen.

  3. Kuormitus yrittää vaihtaa tunnuksen https://storage.azure.com/user_impersonation mutta epäonnistuu, koska Azure-tallennuksen käyttämiseen tarvittavan käyttäjän määrittämän monimenetelmäisen todentamisen vuokraajajärjestelmänvalvoja (katso AADSTS-virhekoodit).

  4. Kuormitus levittää virheen Microsoft Entra ID:ssä saamien väitteiden ohessa asiakkaalle käyttämällä Kuormitusviestinnänkuvattua virheen välittämistä.

  5. Kuormituksen edusta kutsuu acquireAccessToken JavaScript -ohjelmointirajapintaa ja esittää väitteet muodossa claimsForConditionalAccessPolicy, joissa claims viittaavat kuormituksen taustasta välitettyihin vaateisiin:

    workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

Sen jälkeen kuormitus voi yrittää toimintoa uudelleen.

Virheiden käsittely suostumusta pyydettäessä

Joskus käyttäjä ei voi antaa suostumusta eri virheiden vuoksi. Suostumuspyynnön jälkeen vastaus palautetaan uudelleenohjauksen URI-tunnuksen. Tässä esimerkissä tämä koodi vastaa vastauksen käsittelystä. (Löydät sen index.ts tiedostosta.)

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
}

Kuormituksen edusta voi poimia virhekoodin URL-osoitteesta ja käsitellä sen vastaavasti.

Muistiinpano

Molemmissa tilanteissa (virhe ja onnistuminen) kuormituksen on aina suljettava ikkuna välittömästi ilman viivettä.