A számítási feladatok hitelesítési irányelveinek áttekintése a Microsoft Fabricben

Ez a cikk útmutatást nyújt a hitelesítés használatához a Microsoft Fabric számítási feladatainak létrehozásakor. Tokenek és hozzájárulások használatával kapcsolatos információkat tartalmaz.

Mielőtt hozzákezdene, győződjön meg arról, hogy ismeri a Hitelesítés áttekintése és Hitelesítés beállításacímű témakörben szereplő fogalmakat.

Adatsíknak és vezérlősíknak API-k

• adatsík API-jai olyan API-k, amelyeket a számítási feladatok háttérrendszere elérhetővé tesz. A számítási feladatok előtérbelije közvetlenül hívhatja meg őket. Az adatsík API-k esetében a számítási feladatok háttérrendszere eldöntheti, hogy milyen API-kat tegyenek közzé.

• Vezérlősík API-k API-k, amelyek a Fabricen keresztül mennek. A folyamat a munkaterhelés előtér JavaScript API meghívásával kezdődik, és a Fabric a munkaterhelés háttérrendszerének meghívásával fejeződik be. Ilyen API például az Elem létrehozása.

  A vezérlősík API-k esetében a számítási feladatnak követnie kell a számítási feladat háttérrendszerében meghatározott szerződéseket, és implementálnia kell ezeket az API-kat.

API-fül megjelenítése a munkaterhelés alkalmazásában a Microsoft Entra ID-ben.

Az Expose an API lapon hatóköröket kell hozzáadnia a "vezérlősík" API-khoz és az "adatsík" API-khoz:

• A vezérlősík API-khoz hozzáadott hatóköröknek előre engedélyezniük kell a Számítási feladatokhoz kapcsolódó Hálóügyfél alkalmazást a d2450708-699c-41e3-8077-b0c8341509aaalkalmazásazonosítóval. Ezek a hatókörök abban a tokenben találhatók, amelyet a munkaterhelés háttérrendszere kap, amikor a Fabric meghívja.

  A folyamat működéséhez hozzá kell adnia legalább egy hatókört a vezérlősík API-hoz.

• Az adatsík API-khoz hozzáadott hatóköröknek előzetesen engedélyezniük kell a Microsoft Power BI-t az alkalmazásazonosítóval 871c010f-5e61-4fb1-83ac-98610a7e9110. A acquireAccessToken JavaScript API által visszaadott jogkivonatba ők is bele vannak foglalva.

  Adatsík API-k esetén ezen a lapon kezelheti a számítási feladat által közzétett API-k részletes engedélyeit. Ideális esetben minden olyan API-hoz hozzá kell adnia hatóköröket, amelyeket a számítási feladat háttérrendszere elérhetővé tesz, és ellenőriznie kell, hogy a kapott jogkivonat tartalmazza-e ezeket a hatóköröket, amikor az ügyfél meghívja ezeket az API-kat. Például:

  • A számítási feladat két API-t tesz elérhetővé az ügyfélnek, ReadData és WriteData.
  • A számítási feladat két adatsík-hatókört tesz elérhetővé, data.read és data.write.
  • A ReadData API-ban a munkafolyamat ellenőrzi, hogy a data.read hatókör szerepel-e a jogkivonatban, mielőtt folytatná a folyamatot. Ugyanez vonatkozik a WriteData.

API-engedélyek lap a Microsoft Entra ID számítási feladathoz tartozó alkalmazásban

A API-engedélyek lapon hozzá kell adnia az összes hatókört, amelyekre a számítási feladatnak jogkivonatot kell cserélnie. A kötelezően hozzáadandó hatókör Fabric.Extend a Power BI szolgáltatásban. Az ilyen hatókör nélkül a Fabric-ra irányuló kérések meghiúsulhatnak.

Tokenek és hozzájárulások kezelése

Amikor adatátviteli sík API-kkal dolgozik, a feladat előterének hozzáférési tokent kell beszereznie a feladat háttérrendszerébe irányuló hívásokhoz.

A következő szakaszok azt ismertetik, hogyan kell a munkafrontnak használnia a JavaScript API-t és az OBO-folyamatokat jogkivonatok beszerzéséhez a számítási feladathoz és külső szolgáltatásokhoz, valamint az engedélyek kezeléséhez.

1. lépés: Token beszerzése

A számítási feladat azzal kezdődik, hogy tokent kér a JavaScript API-val paraméterek megadása nélkül. Ez a hívás két forgatókönyvet eredményezhet:

• A felhasználó megjelenik a számítási feladat által konfigurált összes statikus függőség (a API-engedélyek lapon konfigurált) hozzájárulási ablaka. Ez a forgatókönyv akkor fordul elő, ha a felhasználó nem része az alkalmazás alapértelmezett bérlőjének, és a felhasználó korábban nem adott hozzájárulást a Microsoft Graph számára ehhez az alkalmazáshoz.

• A felhasználó nem lát hozzájárulási ablakot. Ez a forgatókönyv akkor fordul elő, ha a felhasználó már legalább egyszer hozzájárult az alkalmazás Microsoft Graph-hoz, vagy ha a felhasználó az alkalmazás otthoni bérlőjének része.

Mindkét esetben a számítási feladat nem érdekelheti, hogy a felhasználó teljes hozzájárulást adott-e az összes függőséghez (és jelenleg nem tudja). A kapott jogkivonat rendelkezik a számítási feladatok háttérrendszerének célközönségével, és a számítási feladatok háttérrendszerének közvetlen meghívására használható a számítási feladat előteréből.

2. lépés: Külső szolgáltatások elérése

Előfordulhat, hogy a számítási feladatnak hozzá kell férnie a hitelesítést igénylő szolgáltatásokhoz. Ehhez a hozzáféréshez végre kell hajtania az OBO-folyamatot, amely során a kliensétől vagy a Fabrictől kapott tokent kicseréli egy másik szolgáltatás tokenjére. Előfordulhat, hogy a jogkivonat cseréje a hozzájárulás hiánya miatt meghiúsul, vagy valamilyen Microsoft Entra feltételes hozzáférési szabályzat miatt, amely azon az erőforráson van konfigurálva, amelyhez a számítási feladat megpróbálja kicserélni a jogkivonatot.

A probléma megoldásához a számítási feladat feladata a hiba propagálása az ügyfélnek az előtérbeli és a háttérrendszer közötti közvetlen hívások használatakor. Emellett a számítási feladat feladata a hiba propagálása az ügyfélnek, amikor a Fabricből érkező hívásokkal dolgozik az számítási feladatok kommunikációscímű cikkben leírt hibaterjesztés használatával.

Miután a számítási feladat propagálja a hibát, meghívhatja a acquireAccessToken JavaScript API-t a hozzájárulási vagy feltételes hozzáférési szabályzattal kapcsolatos probléma megoldásához, és újrapróbálkozza a műveletet.

Az adatsík API-hibáiról a Többtényezős hitelesítés, a Feltételes hozzáférés és a növekményes hozzájáruláscímű témakörben olvashat. A vezérlősík API-hibái esetén lásd: Munkaterhelés kommunikáció.

Példaforgatókönyvek

Vessünk egy pillantást egy számítási feladatra, amely három Fabric API-hoz kell hozzáférnie:

• Munkaterületek listázása: GET https://api.fabric.microsoft.com/v1/workspaces

• Raktár létrehozása: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• Írjon egy lakehouse fájlba: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Az API-k használatához a számítási feladat háttérrendszerének jogkivonatokat kell cserélnie a következő hatókörökhöz:

• Munkaterületek felsorolásához: https://analysis.windows.net/powerbi/api/Workspace.Read.All vagy https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• Raktár létrehozásához: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All vagy https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• Lakehouse-fájlba való íráshoz: https://storage.azure.com/user_impersonation

Feljegyzés

A jelen referenciacikkbentalálhatja meg az egyes Fabric API-khoz szükséges hatóköröket.

A korábban említett hatóköröket a munkaterhelés-alkalmazásban API-engedélyekalatt kell konfigurálni.

Tekintsünk meg példákat a számítási feladat által esetleg előforduló forgatókönyvekre.

1. példa

Tegyük fel, hogy a számítási feladat háttérrendszere rendelkezik egy adatsík API-val, amely lekéri a felhasználó munkaterületeit, és visszaadja őket az ügyfélnek:

1. A feladatkezelő felület jogkivonatot kér a JavaScript API használatával.

2. A számítási feladat előtér meghívja a számítási feladat háttér API-ját a felhasználó munkaterületeinek lekéréséhez, és csatolja a jogkivonatot a kéréshez.

3. A számítási feladat háttérrendszere ellenőrzi a jogkivonatot, és megpróbálja kicserélni a szükséges hatókörre (tegyük fel).https://analysis.windows.net/powerbi/api/Workspace.Read.All

4. A munkafolyamat nem tudja kicserélni a jogkivonatot a megadott erőforrásra, mert a felhasználó nem adott hozzájárulást az alkalmazásnak az erőforrás eléréséhez (lásd AADSTS hibakódokat).

5. A számítási feladat háttérrendszere propagálja a hibát a számítási feladat előterében azáltal, hogy megadja, hogy hozzájárulásra van szüksége az adott erőforráshoz. A terhelés-kezelő felület meghívja a acquireAccessToken JavaScript API-t, és biztosítja a következőket: additionalScopesToConsent

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

   Másik lehetőségként lehetőség van arra, hogy a számítási feladat beleegyezést kérjen az alkalmazáshoz konfigurált összes statikus függőségre, így meghívja a JavaScript API-t, és promptFullConsent.

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

Ez a hívás egy hozzájárulási ablakot kér, függetlenül attól, hogy a felhasználó hozzájárult-e egyes függőségekhez. Ezt követően a terheléskezelő felület újra megpróbálhatja a műveletet.

Feljegyzés

Ha a jogkivonat cseréje továbbra is meghiúsul egy hozzájárulási hiba miatt, az azt jelenti, hogy a felhasználó nem adta meg a hozzájárulást. A számítási feladatnak kezelnie kell az ilyen forgatókönyveket; Például értesítse a felhasználót arról, hogy ehhez az API-hoz hozzájárulásra van szükség, és nélküle nem fog működni.

2. példa

Tegyük fel, hogy a számítási feladat háttérrendszerének hozzá kell férnie a OneLake-hez a Create Item API-n (a Fabric hívása a számítási feladathoz):

1. A számítási feladat előtere meghívja a Create Item JavaScript API-t.

2. A számítási feladatok háttérrendszere hívást fogad a Fabrictől, kinyeri a delegált jogkivonatot, és ellenőrzi azt.

3. A munkaterhelés megpróbálja kicserélni a tokent https://storage.azure.com/user_impersonation-ra, de kudarcot vall, mert a felhasználó által beállított multifaktoros hitelesítéshez szükség van az Azure Storage elérésére jogosult bérleti rendszergazdára (lásd AADSTS hibakódok).

4. A munkaterhelés a Microsoft Entra ID-ból az ügyfélnek visszaadott attribútumok mellett terjeszti a hibát a Workload communication című cikkben leírt hibapropagálás révén.

5. A számítási feladat előtere meghívja a acquireAccessToken JavaScript API-t, és jogcímeket biztosít claimsForConditionalAccessPolicyként, ahol claims a számítási feladat háttérrendszeréből propagált jogcímekre hivatkozik:

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

Ezt követően a számítási feladat újrapróbálkozza a műveletet.

A hozzájárulások kérésével kapcsolatos hibák kezelése

Előfordulhat, hogy a felhasználó különböző hibák miatt nem tud hozzájárulást adni. A hozzájárulási kérést követően a rendszer visszaadja a választ az átirányítási URI-nak. A példánkban ez a kód felel a válasz kezeléséért. (A index.ts fájlban található.)

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

A számítási feladatok kezelőfelülete kinyerheti a hibakódot az URL-címből, és ennek megfelelően kezelheti azt.

Feljegyzés

Mindkét forgatókönyvben (hiba és siker) a számítási feladatnak mindig azonnal be kell zárnia az ablakot, késés nélkül.