Prehľad pokynov na overovanie vyťaženia v službe Microsoft Fabric

Tento článok obsahuje pokyny na prácu s overovaním pri vytváraní vyťažení služby Microsoft Fabric. Obsahuje informácie o práci s tokenmi a súhlasmi.

Skôr než začnete, uistite sa, že poznáte koncepty v prehľade overovania a nastavenia overovania.

Rozhranie API na rovine údajov a ovládajej rovine

• rozhrania API na rovine údajov sú rozhrania API, ktoré sprístupňuje koncový server vyťaženia. Klientske vyťaženie ich môže volať priamo. V prípade rozhraní API na úrovni údajov môže koncový server vyťaženia rozhodnúť o tom, aké rozhrania API budú zobrazovať.

• Rozhrania API na ovládanie lietadla sú rozhrania API, ktoré prechádzajú cez fabric. Proces sa začína klientskou vyťažením, ktoré volá rozhranie JavaScript API, a končí sa na to, že fabric volá vyťaženie backend. Príkladom takéhoto rozhrania API je Vytvoriť položku.

  V prípade rozhrania API na riadenie zaťaženia musí vyťaženie postupovať podľa zmlúv definovaných v koncovom servere vyťaženia a vykonávať tieto rozhrania API.

Vystavenie karty rozhrania API v aplikácii vyťaženia v aplikácii Microsoft Entra ID

Na karte Vystavenie rozhrania API je potrebné pridať rozsahy pre rozhrania API riadenia a rozsahy pre rozhrania API na rovine údajov:

• Rozsahy pridané pre rozhrania API riadiacej roviny by mali predbežne povoliť aplikáciu Fabric Client for Workloads s ID aplikácie d2450708-699c-41e3-8077-b0c8341509aa. Tieto rozsahy sú zahrnuté v tokene, ktorý serverová časť vyťaženia dostane, keď ju zavolá služba Fabric.

  Pre fungovanie postupu je potrebné pridať aspoň jeden rozsah pre rozhranie API ovládanej roviny.

• Rozsahy pridané pre rozhrania API na údajovej rovine by mali predbežne povoliť službu Microsoft Power BI s ID aplikácie 871c010f-5e61-4fb1-83ac-98610a7e9110. Sú zahrnuté v tokene, ktorý acquireAccessToken rozhraní JavaScript API vráti.

  V prípade rozhraní API na úrovni údajov môžete použiť túto kartu na správu podrobných povolení pre každé rozhranie API, ktoré sprístupňuje vaše vyťaženie. V ideálnom prípade by ste mali pridať množinu rozsahov pre každé rozhranie API, ktoré koncový server služby sprístupňuje a overuje, či prijatý token obsahuje tieto rozsahy pri volaní týchto rozhraní API od klienta. Napríklad:

  • Vyťaženie sprístupňuje dve rozhrania API klientovi, ReadData a WriteData.
  • Vyťaženie sprístupňuje dva rozsahy údajovej roviny, data.read a data.write.
  • V rozhraní ReadData API vyťaženie overí, či je rozsah data.read zahrnutý v tokene ešte predtým, ako bude pokračovať s postupom. To isté platí pre WriteData.

Karta povolení rozhrania API v aplikácii vyťaženia v aplikácii Microsoft Entra ID

Na karte povolení rozhrania API musíte pridať všetky rozsahy, pre ktoré si vaše vyťaženie vyžaduje výmenu tokenu. Povinný rozsah, ktorý sa má pridať, je Fabric.Extend v rámci služby Power BI. Žiadosti o fabric môžu zlyhať bez tohto rozsahu.

Práca s tokenmi a súhlasmi

Keď pracujete s rozhraniami API na údajovej rovine, klientske vyťaženie musí získať token pre volania koncového miesta vyťaženia.

Nasledujúce časti popisujú, ako by klientske vyťaženie malo používať rozhrania API JavaScript a postupy v mene (OBO) na získanie tokenov pre vyťaženie a externé služby a na prácu so súhlasmi.

Krok č. 1: Získanie tokenu

Vyťaženie začína požiadavkou na token pomocou rozhrania JavaScript API bez uvedenia parametrov. Toto volanie môže mať za následok dva scenáre:

• Používateľovi sa zobrazí okno so súhlasom všetkých statických závislostí (nakonfigurovaných na karte povolenia rozhrania API), ktoré vyťaženie nakonfigurovalo. Tento scenár nastane, ak používateľ nie je súčasťou domovského nájomníka aplikácie a používateľ predtým neudelil súhlas službe Microsoft Graph pre túto aplikáciu.

• Používateľovi sa nezobrazuje okno so súhlasom. Tento scenár nastane, ak používateľ už aspoň raz povolil použitie služby Microsoft Graph pre túto aplikáciu, alebo ak je používateľ súčasťou domovského nájomníka aplikácie.

V oboch scenároch by vyťaženie nemalo zaujímať, či používateľ udelil úplný súhlas pre všetky závislosti (a v tomto bode sa to nedá zistiť). Prijatý token má cieľovú skupinu koncového vyťaženia a možno ho použiť na priame volanie koncového serveru vyťaženia z frontendu vyťaženia.

Krok č. 2: Skúste získať prístup k externým službám

Vyťaženie môže vyžadovať prístup k službám, ktoré vyžadujú overenie. Na účely tohto prístupu musí vykonať tok OBO, kde sa token, ktorý dostal od svojho klienta alebo zo služby Fabric, vymieňa do inej služby. Výmena tokenov môže zlyhať pre nedostatok súhlasu alebo pre určitú politiku podmieneného prístupu k službe Microsoft Entra, ktorá je nakonfigurovaná na zdroji, pre ktorý sa vyťaženie pokúša vymeniť token.

Ak chcete vyriešiť tento problém, je zodpovednosťou vyťaženia šíriť chybu klientovi pri práci s priamymi volaniami medzi klientskym a koncovým serverom. Je tiež zodpovednosťou vyťaženia šíriť chybu klientovi pri práci s volaniami z služby Fabric pomocou šírenia chýb opísaného v téme komunikácia vyťaženia.

Keď vyťaženie rozšíri chybu, môže zavolať acquireAccessToken rozhranie JavaScript API, ktoré vyrieši problém s politikou súhlasu alebo podmieneného prístupu a zopakuje operáciu.

Informácie o zlyhaniach rozhrania API na základe údajov nájdete v téme Spracovanie viacfaktorového overovania, Podmienený prístup a prírastkový súhlas. Informácie o zlyhaniach rozhrania API na ovládanie roviny nájdete v téme komunikácia vyťaženia.

Príklad scenárov

Pozrime sa na vyťaženie, ktoré potrebuje získať prístup k trom rozhraniam API služby Fabric:

• Zoznam pracovných priestorov: GET https://api.fabric.microsoft.com/v1/workspaces

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

• Zapisovať do súboru lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Aby bolo možné pracovať s týmito rozhraniami API, koncový server vyťaženia musí vymeniť tokeny za nasledujúce rozsahy:

• Uvedenie pracovných priestorov: https://analysis.windows.net/powerbi/api/Workspace.Read.All alebo https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• Vytvorenie skladu: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All alebo https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• Pre písanie do súboru lakehouse: https://storage.azure.com/user_impersonation

Poznámka

Rozsahy potrebné pre každé rozhranie API služby Fabric nájdete v tomto referenčnom článku.

Rozsahy uvedené vyššie je potrebné nakonfigurovať v aplikácii na vyťaženie v časti povolení rozhrania API.

Pozrime sa na príklady scenárov, na ktoré sa vyťaženie môže vyskytnúť.

Príklad č. 1

Predpokladajme, že koncový server vyťaženia má rozhranie API na rovine údajov, ktoré načíta pracovné priestory používateľa a vráti ich klientovi:

1. Vyťaženie frontend žiada o token pomocou rozhrania JavaScript API.

2. Klientske vyťaženie volá rozhranie API koncového vyťaženia, aby sa získali pracovné priestory používateľa, a priloží token do požiadavky.

3. Koncový server vyťaženia overí token a pokúsi sa ho vymeniť za požadovaný rozsah (povedzme https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. Vyťaženie nepodarí vymeniť token za zadaný zdroj, pretože používateľ nebol súhlasný pre aplikáciu na prístup k tomuto zdroju (pozrite si kódy chýb AADSTS).

5. Koncový server vyťaženia rozšíri chybu do vyťaženia vopred zadaním, že potrebuje súhlas pre tento zdroj. Klientske vyťaženie volá acquireAccessToken rozhranie JavaScript API a poskytuje additionalScopesToConsent:

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

   Prípadne sa vyťaženie môže rozhodnúť požiadať o súhlas so všetkými statickými závislosťami, ktoré sú nakonfigurované v jeho aplikácii, takže zavolá rozhranie JavaScript API a poskytuje promptFullConsent:

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

V tomto volaní sa zobrazí okno so súhlasom bez ohľadu na to, či používateľ vyjadril súhlas s niektorými závislosťami. Potom môže vyťaženie na koncovom paneli skúsiť operáciu znova.

Poznámka

Ak výmena tokenov naďalej zlyhá v dôsledku chyby súhlasu, znamená to, že používateľ neudelil súhlas. Vyťaženie musí spracovávať takéto scenáre; Upozornite napríklad používateľa, že toto rozhranie API vyžaduje súhlas a nebude bez neho fungovať.

Príklad č. 2

Predpokladajme, že koncový server vyťaženia musí získať prístup k službe OneLake v rozhraní API na vytvorenie položky (volanie zo služby Fabric do vyťaženia):

1. Klientske vyťaženie volá rozhranie JavaScript API vytvoriť položku.

2. Na server vyťaženia sa odošle volanie služby Fabric, ktoré extrahuje delegovaný token a overí ho.

3. Vyťaženie sa pokúsi vymeniť token za https://storage.azure.com/user_impersonation, ale zlyhá, pretože správca nájomníka nakonfigurovaného viacfaktorového overovania potrebného na prístup k službe Azure Storage (pozri kódy chýb AADSTS).

4. Vyťaženie rozšíri chybu spolu s nárokmi vrátenými v chybe z Microsoft Entra ID do klienta pomocou šírenia chýb opísaného v téme komunikácie vyťaženia.

5. Klientske vyťaženie volá acquireAccessToken rozhranie JavaScript API a poskytuje nároky ako claimsForConditionalAccessPolicy, kde claims odkazuje na tvrdenia šírené zo serveru vyťaženia:

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

Potom môže vyťaženie skúsiť operáciu znova.

Spracovanie chýb pri vyžiadaní súhlasu

Niekedy používateľ nemôže udeliť súhlas z dôvodu rôznych chýb. Po vyžiadaní súhlasu sa odpoveď vráti identifikátoru URI presmerovania. V našom príklade je tento kód zodpovedný za spracovanie odpovede. (Nájdete ho v súbore index.ts.)

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(); 
} 

Klientske vyťaženie môže extrahovať kód chyby z URL adresy a podľa toho ho spracovať.

Poznámka

V oboch scenároch (chyba a úspech) musí vyťaženie vždy okamžite zatvoriť okno bez latencie.