Přehled pokynů pro ověřování úloh v Microsoft Fabric

Článek
12/14/2024

Tento článek obsahuje pokyny pro práci s ověřováním při vytváření úloh Microsoft Fabric. Obsahuje informace o práci s tokeny a souhlasy.

Než začnete, ujistěte se, že znáte koncepty v přehledu ověřování a nastavení ověřování .

Rozhraní API roviny dat a řídicí roviny

Rozhraní API datové vrstvy jsou rozhraní API, která backend úlohy poskytuje. Front-end úlohy je může volat přímo. V případě rozhraní API roviny dat může back-end úlohy rozhodnout o tom, jaká rozhraní API se mají zveřejnit.
rozhraní API řídící roviny jsou rozhraní API, která procházejí Fabric. Proces začíná tím, že frontend úlohy volá JavaScriptové rozhraní API, a končí tím, že Fabric volá backend úlohy. Příkladem takového rozhraní API je Vytvořit položku.

U API řídicí roviny musí pracovní zátěž dodržovat kontrakty definované v zázemí pracovní zátěže a implementovat tato API.

Zobrazit kartu API v aplikaci úkolu v Microsoft Entra ID

Na kartě Zveřejnit rozhraní API je potřeba přidat obory pro rozhraní API roviny řízení a obory pro rozhraní API roviny dat:

Rozsahy přidané pro API řídicí vrstvy by měly předem autorizovat aplikaci Fabric Client for Workloads s ID aplikace d2450708-699c-41e3-8077-b0c8341509aa. Tyto rozsahy jsou zahrnuté v tokenu, který zátěžový backend obdrží, když ho volá Fabric.

Aby tok fungoval, musíte k rozhraní API řídicí roviny přidat alespoň jedno oprávnění.
Obory přidané pro rozhraní API roviny dat by měly předem autorizovat Microsoft Power BI s ID aplikace 871c010f-5e61-4fb1-83ac-98610a7e9110. Jsou zahrnuté v tokenu, který vrací rozhraní JavaScript API acquireAccessToken.

U rozhraní API roviny dat můžete pomocí této karty spravovat podrobná oprávnění pro každé rozhraní API, které vaše úloha zveřejňuje. V ideálním případě byste měli přidat sadu oborů pro každé rozhraní API, které back-end pracovní zátěže zveřejňuje, a ověřit, že přijatý token zahrnuje tyto obory, když jsou tato rozhraní API volána klientem. Například:
- Úloha zpřístupňuje klientovi dvě rozhraní API, ReadData a WriteData.
- Úloha zveřejňuje dva rozsahy roviny dat, data.read a data.write.
- V rozhraní API ReadData systém ověří, že rozsah data.read je zahrnutý v tokenu, než pokračuje v procesu. Totéž platí pro WriteData.

Karta Oprávnění rozhraní API v aplikaci úloh v Microsoft Entra ID

Na kartě oprávnění rozhraní API je potřeba přidat všechny obory, pro které vaše úloha potřebuje vyměnit token. Povinné je přidat obor Fabric.Extend ve službě Power BI. Požadavky na Fabric můžou selhat bez tohoto rozsahu.

Práce s tokeny a souhlasy

Při práci s rozhraními API roviny dat musí přední vrstva úlohy získat token pro volání zadní vrstvy úlohy.

Následující části popisují, jak by workload frontend měl používat JavaScript API a toky 'on-behalf-of' (OBO) k získání tokenů pro workload a externí služby a ke správě souhlasů.

Krok 1: Získání tokenu

Úloha začíná dotazem na token pomocí javascriptového rozhraní API bez zadání parametrů. Výsledkem tohoto volání můžou být dva scénáře:

Uživatel vidí okno souhlasu se všemi statickými závislostmi, které nakonfigurovala pracovní zátěž (podle toho, co je nakonfigurováno na kartě oprávnění rozhraní API ). K tomuto scénáři dochází v případě, že uživatel není součástí domovského tenanta aplikace a uživatel předtím neudělil souhlas s Microsoft Graphem pro tuto aplikaci.
Uživatel nevidí okno souhlasu. K tomuto scénáři dochází v případě, že uživatel už alespoň jednou souhlasil s Microsoft Graphem pro tuto aplikaci nebo pokud je uživatel součástí domovského tenanta aplikace.

V obou scénářích by se neměla zátěž zajímat o to, jestli uživatel udělil úplný souhlas se všemi závislostmi (a v tomto okamžiku to nemůže vědět). Přijatý token má cílovou skupinu back-endu úlohy a dá se použít k přímému volání back-endu úlohy z front-endu úlohy.

Krok 2: Pokuste se o přístup k externím službám

Úloha může potřebovat přístup ke službám, které vyžadují ověřování. Pro tento přístup musí provést tok OBO, v němž vymění token, který přijal od svého klienta nebo z Fabric, za účelem jiné služby. Výměna tokenů může selhat kvůli nedostatku souhlasu nebo některé zásady podmíněného přístupu Microsoft Entra nakonfigurované pro prostředek, pro který se úloha pokouší token vyměnit.

Pokud chcete tento problém vyřešit, je zodpovědností úlohy rozšířit chybu klientovi při práci s přímými voláními mezi front-endem a back-endem. Je také zodpovědností úlohy propagovat chybu ke klientovi při práci s voláními z Fabricu pomocí šíření chyby, jak je popsáno v komunikaci úloh.

Jakmile úloha tuto chybu rozšíří, může volat acquireAccessToken JavaScriptové API k vyřešení problému se zásadami souhlasu nebo podmíněného přístupu a operaci znovu zkusit.

Informace o selhání rozhraní API roviny dat najdete v tématu Zpracování vícefaktorového ověřování, podmíněného přístupu a přírůstkového souhlasu. Informace o selhání rozhraní API řídicí roviny najdete v tématu Komunikace úloh.

Ukázkové scénáře

Pojďme se podívat na úlohu, která potřebuje přístup ke třem rozhraním FABRIC API:

Seznam pracovních prostorů: GET https://api.fabric.microsoft.com/v1/workspaces
Vytvoření skladu: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses
Zápis do souboru lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Aby bylo možné s těmito rozhraními API pracovat, musí back-end úlohy vyměnit tokeny pro následující obory:

Pro výpis pracovních prostorů: https://analysis.windows.net/powerbi/api/Workspace.Read.All nebo https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
Vytvoření skladu: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All nebo https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
Zápis do souboru lakehouse: https://storage.azure.com/user_impersonation

Poznámka:

Obory potřebné pro každé rozhraní FABRIC API najdete v tomto referenčním článku.

Obory uvedené dříve je potřeba nakonfigurovat pro aplikaci úloh v rámci oprávnění rozhraní API .

Podívejme se na příklady scénářů, se kterými se může úloha setkat.

Příklad 1

Předpokládejme, že back-end pracovního zatížení má API datové roviny, které získá pracovní prostory uživatele a vrátí je klientovi.

Front-end úlohy požádá o token pomocí javascriptového rozhraní API.
Front-end úlohy volá rozhraní API back-endu úlohy, aby získalo pracovní prostory uživatele a připojil token v požadavku.
Back-end úlohy token ověří a pokusí se ho vyměnit za požadovaný obor (řekněme https://analysis.windows.net/powerbi/api/Workspace.Read.All).
Úloha se nezdaří vyměnit token pro zadaný prostředek, protože uživatel neudělil aplikaci souhlas s přístupem k tomuto prostředku (viz kódy chyb AADSTS).
Back-end úlohy rozšíří chybu do front-endu úlohy tím, že určí, že pro daný prostředek potřebuje souhlas. Frontend zatížení volá acquireAccessToken JavaScript API a poskytuje additionalScopesToConsent:

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

Případně se může úloha rozhodnout požádat o souhlas pro všechny své statické závislosti nakonfigurované v aplikaci, protože volá rozhraní API JavaScriptu a poskytuje promptFullConsent:

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

Toto volání vyzve okno souhlasu bez ohledu na to, jestli uživatel souhlasil s některými závislostmi. Poté může uživatelské rozhraní pracovní zátěže operaci zopakovat.

Poznámka:

Pokud výměna tokenu stále selže při chybě souhlasu, znamená to, že uživatel neudělil souhlas. Úlohy musí takové scénáře zvládnout; Například upozorněte uživatele, že toto rozhraní API vyžaduje souhlas a nebude bez něj fungovat.

Příklad 2

Předpokládejme, že back-end úlohy potřebuje přístup k OneLake na API pro vytvoření položky (volání z Fabric do úlohy):

Frontend pracovního zatížení volá JavaScript API pro vytvoření položky.
Zátěžový backend přijme volání z Fabric, extrahuje delegovaný token a ověří ho.
Úloha se pokusí vyměnit token pro , ale selže, protože správce tenanta, který konfiguroval vícefaktorové ověřování uživatele potřebné pro přístup ke službě Azure Storage, tuto akci nepovolil (viz kódy chyb AADSTSv ).
Úloha šíří chybu spolu s deklaracemi identity vrácenými v chybě z ID Microsoft Entra do klienta pomocí šíření chyby popsané v komunikace úlohy.
Front-end zátěže volá rozhraní JavaScriptu acquireAccessToken a poskytuje nároky jako claimsForConditionalAccessPolicy, kde claims odkazuje na nároky šířené z back-endu zátěže:

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

Potom může zátěž operaci zopakovat.

Zpracování chyb při vyžádání souhlasu

Někdy uživatel nemůže udělit souhlas kvůli různým chybám. Požadování souhlasu vrátí odpověď na přesměrovací URI. V našem příkladu je tento kód zodpovědný za zpracování odpovědi. (Najdete ho v souboru 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(); 
}

Front-end úlohy může extrahovat kód chyby z adresy URL a odpovídajícím způsobem ho zpracovat.

Poznámka:

V obou scénářích (chyba a úspěch) musí úloha vždy zavřít okno okamžitě bez latence.

Sdílet prostřednictvím

Přehled pokynů pro ověřování úloh v Microsoft Fabric

Rozhraní API roviny dat a řídicí roviny

Zobrazit kartu API v aplikaci úkolu v Microsoft Entra ID

Karta Oprávnění rozhraní API v aplikaci úloh v Microsoft Entra ID

Práce s tokeny a souhlasy

Krok 1: Získání tokenu

Krok 2: Pokuste se o přístup k externím službám

Ukázkové scénáře

Příklad 1

Příklad 2

Zpracování chyb při vyžádání souhlasu

Váš názor

Další materiály