Rozhranie API pre zobrazenie schémy GraphQL a prieskumníka schémy

Fabric API pre GraphQL automaticky generuje schému, ktorá definuje štruktúru vášho API na základe pripojených dátových zdrojov. Schéma, napísaná v GraphQL Schema Definition Language (SDL), popisuje všetky dostupné typy, polia, dotazy a mutácie, ktoré môžu klienti použiť na interakciu s vašimi dátami.

Pohľad schémy poskytuje iba na čítanie, textový pohľad na kompletnú schému GraphQL, zatiaľ čo prieskumník schémy v ľavom paneli vám umožní navigovať, kontrolovať a upravovať objekty vystavené cez vaše API. Tieto nástroje vám spolu pomáhajú pochopiť štruktúru vášho API a kontrolovať, aké dáta sú klientom prístupné.

Kto používa pohľad schémy

Schéma pohľad a prieskumník sú cenné pre:

Dátoví inžinieri konfigurujúci , ktoré objekty Fabric lakehouse a warehouse majú sprístupniť cez GraphQL
Vývojári aplikácií objavujú dostupné typy dát, polia a vzťahy v Fabric pred písaním dotazov
Prispievatelia do fabric pracovného priestoru rozumejú a riadia štruktúru prístupu k dátam pre svoj pracovný priestor
BI vývojári kontrolujú vzťahy dát vo Fabric pri tvorbe vlastných analytických aplikácií

Použite pohľad schémy na preskúmanie štruktúry vášho API a prieskumník schémy na úpravu, ktoré dátové objekty sú vystavené.

Prístup a preskúmanie schémy

K zobrazeniu schémy sa môžete dostať buď z editora dotazov, alebo priamo z vašej položky GraphQL API. Pre otvorenie zobrazenia schémy vyberte schému v ľavom dolnom rohu. Zobrazenie schémy zobrazuje textovú verziu vášho kompletného GraphQL SDL len na čítanie so všetkými generovanými typmi, poľami, dotazmi a mutáciami.

Nasledujúci obrázok zobrazuje pohľad schémy s panelom Schema Explorer vľavo:

Navigujte pomocou prieskumníka schémy

Prieskumník schémy v ľavom paneli vám umožní navigovať a kontrolovať všetky objekty vo vašom API. Prieskumník je dostupný v zobrazení schémy aj v editore dotazov, čo uľahčuje skúmanie štruktúry API pri písaní dotazov.

Rozbalte uzly v prieskumníku schémy, aby ste videli:

Typy: Typy GraphQL generované z vašich dátových zdrojov tabuliek a zobrazení
Dotazy: Automaticky generované operácie čítania na získavanie dát
Mutácie: Automaticky generované operácie zápisu na vytváranie, aktualizáciu a mazanie dát (len v sklade)

Typy

Typy predstavujú štruktúru vašich dát a zobrazujú sa pod názvom zdroja dát, z ktorého boli vygenerované. Nasledujúci obrázok zobrazuje typ SalesOrderDetail generovaný z tabuľky SalesOrderDetail v analytickom endpointe AdventureWorks SQL:

Dotazy

API automaticky generuje dotazy na získanie dát z objektov, ktoré vystavujete. Rozšírte uzol dotazov, aby ste videli všetky dostupné operácie čítania:

Mutácie

Mutácie sú operácie zápisu na vytváranie, aktualizáciu a mazanie dát. Rozšírte uzol mutácií, aby ste videli všetky dostupné zápisové operácie:

Poznámka

Mutácie sa generujú iba pre dátové zdroje Fabric Data Warehouse. SQL analytické endpointy (lakehouse a zrkadlové databázy) sú len na čítanie a podporujú iba dotazy. Ak nevidíte mutácie vo svojom Schema Exploreri, overte, či ste sa pripojili k skladu.

Úprava objektov pomocou prieskumníka schémy

Po tom, čo API vygeneruje vašu počiatočnú schému, môžete použiť prieskumník schémy na upresnenie toho, čo je cez vaše API vystavené. Prieskumník schémy poskytuje možnosti správy, ktoré vám umožňujú ovládať štruktúru vášho API bez úpravy základných zdrojov dát. Tieto nástroje sú nevyhnutné pre udržiavanie čistého, dobre organizovaného API, ktoré zverejňuje len dáta, ktoré vaši klienti potrebujú.

Možnosti úpravy prístupu

Na úpravu objektu vyberte elipsiu (...) vedľa ľubovoľného typu v prieskumníku schémy. Nasledujúci príklad ukazuje menu na úpravu typu SalesOrderDetail :

Dostupné možnosti úprav

Aktualizovať schému – Synchronizuje vašu GraphQL schému s najnovšou štruktúrou zo zdroja dát. Použite ju, keď ste pridali nové tabuľky, pohľady alebo stĺpce do svojho dátového zdroja a chcete ich sprístupniť cez API. Táto operácia objavuje a pridáva nové objekty pri zachovaní existujúcej konfigurácie.

Premenovanie - Mení to, ako sa objekt zobrazuje vo vašom GraphQL API. To je užitočné pri vytváraní intuitívnejších konvencií pomenovania API alebo pri skrývaní detailov implementácie pred klientmi. Napríklad môžete jednoducho premenovať tbl_SalesOrderDetail na SalesOrderDetail. Premenovanie ovplyvňuje iba schému API a nemení základný dátový zdrojový objekt.

Odstrániť zo schémy – Odstráni objekt z vášho GraphQL API, čím sa stane nedostupným pre klientov. Použite to na skrytie citlivých údajov, odstránenie zastaraných objektov alebo zjednodušenie povrchu API. Dáta zostávajú vo vašom dátovom zdroji; odstráni sa iba expozícia API.

Spravovať vzťahy – Otvára rozhranie na správu vzťahov, kde môžete definovať, ako sa objekty navzájom prepájajú. Vzťahy umožňujú vnorené dotazy a prechádzanie grafmi, čo umožňuje klientom získať súvisiace údaje v jednej požiadavke. Ďalšie informácie nájdete v téme Spravovanie vzťahov v rozhraní API služby Fabric pre GraphQL.

Vlastnosti – Zobrazuje podrobné metadáta o objekte, vrátane pôvodného názvu, ako sa objavuje v zdroji dát, názvu typu GraphQL, vlastníka a lokality (názov pracovného priestoru a zdroja dát). Použite to na overenie, ako sú objekty mapované medzi vaším zdrojom dát a GraphQL API.

Povolenie a zakázanie dotazov a mutácií

Funkcia povolenia alebo vypnutia pre dotazy a mutácie poskytuje správcom a vývojárom podrobnú kontrolu nad prístupom k rozhraniu API a jeho používaním. Umožňuje selektívnu aktiváciu alebo deaktivovanie konkrétnych dotazov a mutácií v rámci schémy GraphQL. To vám umožňuje dynamicky spravovať možnosti rozhrania API bez toho, aby ste upravili kód alebo nasadili zmeny.

Použite túto funkciu v situáciách ako:

Verziovanie API: Vypnúť zastarané operácie pri prechode klientov na nové verzie
Údržbové okná: Dočasne deaktivujte zápisné operácie (mutácie) počas údržby dát
Bezpečnosť a súlad: Obmedziť prístup k citlivým operáciám bez ich odstránenia zo schémy
Fázové zavádzanie: Povoliť nové dotazy alebo mutácie na testovanie predtým, než ich sprístupnia široko

Dotazy a mutácie v prieskumníkovi schém majú dve ďalšie možnosti:

Zakázať: Zabráni spusteniu dotazu alebo mutácie akýmkoľvek požiadavkám. Pri pokuse o vykonanie sa vráti chyba. Po vypnutí dotazu alebo mutácie dôjde k opätovnému načítaniu schémy a dotaz alebo mutácia sa v prieskumníkovi schémy zobrazí sivá.

Povoliť: Umožňuje znova povoliť predtým zakázaný dotaz alebo mutáciu. Dotaz alebo mutácia je k dispozícii okamžite po operácii opätovného načítania schémy, ktorá nastane po výbere možnosti Povoliť .