Sdílet prostřednictvím

Rozhraní Fabric API pro introspekci GraphQL a export schématu

Když vytváříte aplikace nebo integrujete externí nástroje s rozhraním API Fabric pro GraphQL, musíte porozumět struktuře vašeho rozhraní API – jaké typy jsou k dispozici, jaká pole obsahují a jak spolu souvisí. Bez ohledu na to, jestli generujete kód klienta, vytváříte dokumentaci nebo konfigurujete nástroje API Management, je přístup k definici schématu nezbytný.

Rozhraní API fabric pro GraphQL poskytuje dva doplňkové mechanismy pro načtení informací o schématu: introspection pro dotazy programového modulu runtime a export schématu pro získání kompletního souboru schématu. Obě metody poskytují přístup ke stejnému podkladovému schématu, ale každá z nich obsluhuje různé pracovní postupy a případy použití.

Návod

Chcete vidět introspekci v akci? Vyzkoušejte kurz Připojení agentů AI k rozhraní FABRIC API pro GraphQL pomocí místního serveru MCP (Model Context Protocol). Tato praktická příručka ukazuje, jak agenti umělé inteligence používají introspekci k automatickému zjišťování a dotazování dat fabric pomocí přirozeného jazyka.

Kdo používá introspekci a export schématu

Introspekce a export schématu jsou cenné pro:

  • Vývojáři aplikací vytvářející klienty, kteří využívají data Fabric a potřebují vygenerovat typově bezpečný kód
  • Přispěvatelé pracovního prostoru Fabric chápou dostupné datové struktury a testují přístup k datům.
  • Vývojové nástroje a IDE poskytující automatické dokončování a IntelliSense pro rozhraní API Fabric GraphQL
  • Integrace služby Azure API Management, které směrují a zabezpečují provoz Fabric GraphQL na podnikové úrovni
  • Správci fabric auditují vystavené datové struktury a ověřují řízení přístupu.
  • Agenti a asistenti umělé inteligence, které využívají protokol Model Context Protocol (MCP) k přirozenému zjišťování a dotazování dat ve Fabricu
  • Vývojáři Power Platform chápou schémata dat Fabric před sestavováním integrací
  • Kanály CI/CD sledující verze schématu GraphQL Fabric a ověřování kompatibility napříč prostředími

Zvolte introspekci , pokud potřebujete dotazovat informace o schématu programově za běhu, jako je řízení vývojových nástrojů, umožnění agentů AI nebo implementace dynamických klientských funkcí. Vyberte export schématu , pokud potřebujete kompletní soubor schématu pro offline použití, správu verzí, integraci brány rozhraní API nebo sdílení s externími týmy.

  • Introspekce: Programaticky dotazujte své schéma pomocí systému introspection GraphQL, který je součástí standardu GraphQL. Introspektivní dotazy umožňují dynamicky zjišťovat typy, pole a relace a umožňují jim mnoho vývojových nástrojů GraphQL.

  • Export schématu: Stáhněte si kompletní soubor SDL (GraphQL Schema Definition Language), který obsahuje celou definici schématu pro offline použití, sdílení nebo integraci nástrojů.

Introspekce

Ve výchozím nastavení je v rozhraní API pro položky GraphQL zakázaná introspekce. Toto nastavení můžou přepínat jenom správci pracovního prostoru. Všichni ostatní uživatelé uvidí zakázaný posuvník.

Povolení introspekce:

  1. V horní nabídce vyberte ikonu ozubeného kolečka nastavení rozhraní API.

    Snímek obrazovky znázorňující panel portálu s tlačítkem ozubeného kola nastavení

  2. V levém navigačním panelu vyberte stránku Introspection .

    Snímek obrazovky znázorňující posuvník nastavení introspekce

  3. Výběrem přepínače povolte introspekci. Povolení introspekce zveřejňuje informace o schématu všem uživatelům s přístupem ke koncovému bodu rozhraní API.

  4. Zobrazí se dialogové okno s potvrzením. Výběrem možnosti Potvrdit povolíte introspekci nebo zrušíte jeho zakázání.

    Snímek obrazovky s dialogovým oknem pro potvrzení povolení introspekce

Příklad dotazu sebereflexe

Tady je rychlý příklad dotazu introspekce pro načtení dostupných typů ze schématu:

  1. V editoru GraphQL vytvořte nový dotaz. Výběrem ikony plus + vedle existujících karet otevřete novou kartu dotazu.

    Snímek obrazovky znázorňující tlačítko nového dotazu v editoru GraphQL

  2. V editoru zadejte následující úvodní dotaz:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Vyberte tlačítko Spustit a spusťte dotaz.

  4. V podokně výsledků se zobrazí seznam všech typů definovaných ve schématu.

    Snímek obrazovky znázorňující příklad dotazu introspekce

Dotazy introspekce mohou vracet velké množství informací. Rozsah dotazu můžete zúžit tím, že budete v požadavku introspekce konkrétnější. Například místo dotazování na všechny typy můžete zadat dotaz na konkrétní typ:

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

Spuštění dotazu vrátí podrobné informace o ProductCategory typu:

{
  "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
          }
        }
      ]
    }
  }
}

Mezi běžné vzory filtrování při zpracování výsledků introspekce patří:

  • Vyloučení typů začínajících dvojitým podtržítkem (__), což jsou systémové typy GraphQL
  • Zahrnutí typů začínajících konkrétními předponami, jako je ProductCategory

Tyto příklady ukazují standardní syntaxi introspekce GraphQL, která funguje napříč implementací GraphQL. Tento přehled se zabývá základními vzory introspekce – komplexní podrobnosti o systému introspekce, pokročilých technikách dotazování a dalších možnostech, viz oficiální dokumentace k introspekci nadace GraphQL.

Export schématu

Až budete potřebovat úplnou offline kopii definice schématu, použijte funkci exportu schématu přímo z portálu Fabric. Otevřete rozhraní API pro GraphQL a na panelu nástrojů vyberte Exportovat schéma . Váš prohlížeč stáhne soubor SDL (Schema Definition Language) obsahující úplnou definici schématu.

Snímek obrazovky znázorňující tlačítko exportovat schéma

Porozumění souboru SDL

Exportovaný soubor používá jazyk SDL (GraphQL Schema Definition Language), čitelný formát, který definuje typy, pole a relace rozhraní API. Soubor SDL obsahuje:

  • Objektové typy představující datové entity s jejich poli
  • Dotazovací operace , které definují, jak načíst data
  • Operace s mutací pro vytváření, aktualizaci nebo odstraňování dat
  • Argumenty pole , které určují vstupní parametry a jejich typy
  • Popisy typů poskytující dokumentaci pro každý prvek

Soubor SDL můžete otevřít v libovolném textovém editoru a zkontrolovat strukturu schématu. To je užitečné zejména pro pochopení kompletní plochy rozhraní API před jejich integrací do vašich aplikací.

Použití exportovaného schématu

Mezi běžné případy použití exportovaného souboru SDL patří:

  • Integrace brány rozhraní API: Import do služby Azure API Management za účelem přidání ověřování, omezování rychlosti a ukládání do mezipaměti
  • Nastavení vývojového prostředí: Konfigurace IntelliSense v editoru Visual Studio Code pro automatické dokončování a ověřování
  • Správa verzí: Potvrzení do Gitu nebo jiných systémů správy zdrojového kódu ke sledování vývoje schématu v průběhu času
  • Týmová spolupráce: Sdílení s externími partnery nebo vývojovými týmy, kteří potřebují porozumět vaší struktuře rozhraní API
  • Generování kódu: Použití s generátory kódu GraphQL k vytvoření type-safe klientů v TypeScriptu, C#, Javě nebo jiných jazycích
  • Dokumentace: Generování referenční dokumentace k rozhraní API pomocí nástrojů, jako je GraphQL Voyager nebo GraphQL Markdown

Na rozdíl od příchozích dotazů nevyžaduje export schématu povolení introspekce a funguje bez ohledu na nastavení introspekce vašeho rozhraní API. Díky tomu je spolehlivý způsob, jak získat přístup k definici schématu pro účely správy a vývoje.

Správa změn schématu

Schémata GraphQL se můžou v průběhu času vyvíjet při přidávání nových typů, polí nebo funkcí do rozhraní API. Po změně schématu se exportované soubory SDL stanou zastaralými. Zvažte tyto postupy:

  • Opětovné exportování po změnách: Při každé úpravě schématu rozhraní API ve Fabric stáhněte nový soubor SDL. Změny schématu zahrnují přidání zdrojů dat, úpravu vystavených typů nebo aktualizaci definic polí.
  • Správa verzí: Potvrďte každé exportované schéma do systému správy zdrojového kódu s popisnými zprávami potvrzení. Tím se vytvoří záznam auditu vývoje schématu a v případě potřeby umožňuje vrácení zpět.
  • Komunikace: Pokud externí týmy nebo aplikace závisí na vašem schématu, upozorněte je na významné změny. I když GraphQL podporuje doplňkové změny bez přerušení stávajících dotazů, může odebrání nebo přejmenování polí ovlivnit klienty.
  • Automatizace: Pro kanály CI/CD zvažte automatizaci exportu schématu v rámci procesu nasazení, abyste zajistili, že dokumentace a nástroje zůstanou synchronizované s vaším rozhraním API.

Osoba odpovědná za úpravu schématu rozhraní API (obvykle datový inženýr nebo vývojář rozhraní API) by měla exportovat a upravovat aktualizované schéma, aby zachovala konzistenci mezi rozhraním FABRIC API a externími systémy, které na něm závisejí.

Související obsah

  • Last updated on