Zdieľať cez

Rozhranie API služby Fabric na introspekciu a export schémy GraphQL

Keď vytvárate aplikácie alebo integrujete externé nástroje do Fabric API pre GraphQL, musíte pochopiť štruktúru svojho API – aké typy sú dostupné, aké polia obsahujú a ako spolu súvisia. Či už generujete klientsky kód, dokumentáciu alebo konfigurujete nástroje na správu API, prístup k definícii schémy je nevyhnutný.

Fabric API pre GraphQL poskytuje dva doplnkové mechanizmy na získavanie informácií o schéme: introspekciu pre programové bežné dotazy a export schémy na získanie kompletného súboru schémy. Obe metódy vám dávajú prístup k rovnakej základnej schéme, ale každá slúži iným pracovným postupom a prípadom použitia.

Prepitné

Chcete vidieť introspekciu v praxi? Vyskúšajte návod Connect AI Agents to Fabric API for GraphQL s lokálnym serverom Model Context Protocol (MCP). Tento praktický sprievodca ukazuje, ako AI agenti využívajú introspekciu na automatické objavovanie a dotazovanie na vaše Fabric dáta pomocou prirodzeného jazyka.

Kto používa introspekciu a export schém

Introspekcia a export schém sú cenné pre:

  • Vývojári aplikácií stavajú klientov, ktorí spotrebúvajú dáta Fabric a potrebujú generovať typovo bezpečný kód
  • Prispievatelia do pracovného priestoru fabric rozumejú dostupným dátovým štruktúram a testujú prístup k dátam
  • Vývojové nástroje a IDE poskytujúce automatické dopĺňanie a IntelliSense pre Fabric GraphQL API
  • Azure API Management integrácie, ktoré smerujú a zabezpečujú Fabric GraphQL prevádzku na podnikovej úrovni
  • Administrátori štruktúr auditujú vystavené dátové štruktúry a overujú prístupové kontroly
  • AI agenti a asistenti využívajúci Model Context Protocol (MCP) na prirodzené objavovanie a dotazovanie Fabric dát
  • Vývojári Power Platform rozumejú dátovým schémam Fabric pred vytvorením integrácií
  • CI/CD pipeline sledujúce verzie schémy Fabric GraphQL a overujúce kompatibilitu naprieč prostrediami

Zvoľte introspekciu , keď potrebujete programovo vyhľadávať informácie o schéme za behu, napríklad pri napájaní vývojových nástrojov, zapnutí AI agentov alebo implementácii dynamických funkcií klienta. Vyberte si export schémy , keď potrebujete kompletný súbor schémy na offline použitie, správu verzií, integráciu API brán alebo zdieľanie s externými tímami.

  • Introspekcia: Dotazujte svoju schému programovo pomocou systému introspekcie GraphQL, ktorý je súčasťou štandardu GraphQL. Introspekčné dotazy vám umožňujú dynamicky objavovať typy, polia a vzťahy a poháňajú mnohé vývojové nástroje GraphQL.

  • Export schémy: Stiahnite si kompletný súbor SDL (GraphQL Schema Definition Language), ktorý obsahuje celú vašu definíciu schémy pre offline použitie, zdieľanie alebo integráciu nástrojov.

Introspekcie

V predvolenom nastavení je v rozhraní API pre položky GraphQL zakázané introspekcie. Toto nastavenie môžu zapnúť iba administrátori pracovného priestoru. Všetkým ostatným používateľom sa zobrazí neaktívny jazdec.

Na umožnenie introspekcie:

  1. Vyberte ikonu ozubeného kolieska API Settings v hornom menu.

    Snímka obrazovky, ktorá zobrazuje panel portálu s tlačidlom ozubeného kolieska nastavení.

  2. Z ľavej navigácie vyberte stránku Introspekcia .

    Snímka obrazovky s jazdcom nastavenia introspekcie.

  3. Vyberte prepínač na povolenie introspekcie. Povolenie introspekcie sprístupní informácie o schéme všetkým používateľom s prístupom k API endpointu.

  4. Zobrazí sa dialógové okno s potvrdením. Vyberte Potvrdiť , aby ste povolili introspekciu, alebo Zrušiť , aby ste to nechali vypnuté.

    Snímka obrazovky s dialógovým oknom na potvrdenie povolenia introspekcie.

Príklad dotazu introspekcie

Tu je rýchly príklad introspektného dotazu na načítanie dostupných typov zo schémy:

  1. Vytvorte nový dotaz v editore GraphQL. Vyberte ikonu plus + vedľa existujúcich záložiek, aby ste otvorili novú záložku dotazu.

    Snímka obrazovky, ktorá ukazuje nové tlačidlo dotazu v editore GraphQL.

  2. Do editora zadajte nasledujúcu introspekčnú otázku:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Výberom tlačidla Spustiť spustíte dotaz.

  4. Panel s výsledkami zobrazuje zoznam všetkých typov definovaných v schéme.

    Snímka obrazovky s príkladom dotazu introspekcie.

Introspekčné dotazy môžu priniesť veľké množstvo informácií. Môžete zúžiť rozsah toho, čo sa pýtate, tým, že budete konkrétnejší vo svojej introspekčnej požiadavke. Napríklad namiesto dotazovania všetkých typov môžete dotazovať konkrétny typ:

query {
    __type(name: "ProductCategory") {
        name
        kind
        fields {
            name
            type {
                name
            }
        }
    }
}

Spustenie dotazu vracia podrobné informácie o type ProductCategory :

{
  "data": {
    "__type": {
      "name": "ProductCategory",
      "kind": "OBJECT",
      "fields": [
        {
          "name": "ProductCategoryID",
          "type": {
            "name": null
          }
        },
        {
          "name": "ParentProductCategoryID",
          "type": {
            "name": "Int"
          }
        },
        {
          "name": "Name",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "rowguid",
          "type": {
            "name": null
          }
        },
        {
          "name": "ModifiedDate",
          "type": {
            "name": null
          }
        }
      ]
    }
  }
}

Bežné filtračné vzory pri spracovaní výsledkov introspekcie zahŕňajú:

  • Ak vylúčime typy začínajúce dvojitými podčiarknutiami (__), ktoré sú typmi systémov GraphQL
  • Vrátane typov začínajúcich konkrétnymi predponami ako ProductCategory

Tieto príklady ukazujú štandardnú introspekcionickú syntax GraphQL, ktorá funguje naprieč akoukoľvek implementáciou GraphQL. Tento prehľad pokrýva základné vzorce introspekcie – pre komplexné informácie o systéme introspekcie, pokročilých technikách dotazovania a ďalších schopnostiach si pozrite oficiálnu dokumentáciu GraphQL Foundation o introspekcii.

Exportovať schému

Keď potrebujete kompletnú, offline kópiu definície schémy, použite funkciu exportu schémy priamo z portálu Fabric. Otvorte svoje API pre GraphQL a vyberte Exportovať schému v paneli nástrojov. Váš prehliadač si stiahne súbor SDL (Schema Definition Language) obsahujúci kompletnú definíciu schémy.

Snímka obrazovky s tlačidlom schémy exportu.

Pochopenie SDL súboru

Exportovaný súbor používa GraphQL Schema Definition Language (SDL), formát čitateľný pre človeka, ktorý definuje typy, polia a vzťahy vášho API. Súbor SDL obsahuje:

  • Typy objektov reprezentujúce vaše dátové entity s ich poliami
  • Operácie dotazov, ktoré definujú, ako získať dáta
  • Mutačné operácie na vytváranie, aktualizáciu alebo mazanie dát
  • Argumenty polí, ktoré špecifikujú vstupné parametre a ich typy
  • Popisy typov poskytujúce dokumentáciu ku každému prvku

SDL súbor môžete otvoriť v akomkoľvek textovom editore a skontrolovať štruktúru schémy. To je obzvlášť užitočné na pochopenie celého povrchu API pred jeho integráciou do vašich aplikácií.

Použitie exportovanej schémy

Bežné prípady použitia exportovaného SDL súboru zahŕňajú:

  • Integrácia API gateway: Import do Azure API Management na pridanie autentifikácie, obmedzenia rýchlosti a cachovania
  • Nastavenie vývojového prostredia: Konfigurujte IntelliSense vo Visual Studio Code pre automatické dopĺňanie a validáciu
  • Správa verzií: Commit do Git alebo iných systémov na správu zdrojového kódu na sledovanie vývoja schémy v čase
  • Spolupráca tímov: Zdieľajte to s externými partnermi alebo vývojovými tímami, ktoré potrebujú pochopiť štruktúru vášho API
  • Generovanie kódu: Použitie s generátormi kódu GraphQL na vytváranie typovo bezpečných klientov v TypeScript, C#, Java alebo iných jazykoch
  • Dokumentácia: Generujte referenčnú dokumentáciu API pomocou nástrojov ako GraphQL Voyager alebo GraphQL Markdown

Na rozdiel od introspekčných dotazov, export schémy nevyžaduje povolenie introspekcie a funguje bez ohľadu na nastavenia introspekcie vo vašom API. To z neho robí spoľahlivý prístup k definícii schémy pre administratívne a vývojové účely.

Správa zmien schémy

Schémy GraphQL sa môžu časom vyvíjať, keď pridávate nové typy, polia alebo schopnosti do svojho API. Keď sa schéma zmení, exportované SDL súbory sa stávajú zastaranými. Zvážte tieto praktiky:

  • Opätovný export po zmenách: Stiahnite si nový SDL súbor vždy, keď upravujete schému API vo Fabric. Zmeny schémy zahŕňajú pridanie zdrojov dát, úpravu exponovaných typov alebo aktualizáciu definícií polí.
  • Správa verzií: Commitujte každú exportovanú schému do vášho systému správy zdrojového kódu s popisnými commit správami. To vytvára auditnú stopu vývoja schémy a umožňuje vrátenie späť v prípade potreby.
  • Komunikácia: Ak externé tímy alebo aplikácie závisia od vašej schémy, informujte ich o významných zmenách. Hoci GraphQL podporuje aditívne zmeny bez narušenia existujúcich dotazov, odstránenie alebo premenovanie polí môže ovplyvniť klientov.
  • Automatizácia: Pre CI/CD pipeline zvážte automatizáciu exportu schém ako súčasť procesu nasadenia, aby dokumentácia a nástroje zostali synchronizované s vaším API.

Osoba zodpovedná za úpravu API schémy (zvyčajne dátový inžinier alebo API vývojár) by mala exportovať a verzionovať aktualizovanú schému, aby sa zachovala konzistencia medzi Fabric API a externými systémami, ktoré na ňom závisia.

Súvisiaci obsah

  • Last updated on