Fabric API a GraphQL bevezető és sémaexportáláshoz

Amikor alkalmazásokat hoz létre, vagy külső eszközöket integrál a Fabric API-val a GraphQL-hez, ismernie kell az API szerkezetét – milyen típusok érhetők el, milyen mezőket tartalmaznak, és hogyan kapcsolódnak egymáshoz. Akár ügyfélkódot hoz létre, akár dokumentációt hoz létre, akár API felügyeleti eszközöket konfigurál, elengedhetetlen a sémadefiníció elérése.

A GraphQL-hez készült Fabric API két kiegészítő mechanizmust biztosít a sémainformációk lekéréséhez: a programozott futtatókörnyezeti lekérdezések bevezető szakaszát és a sémaexportálást a teljes sémafájl beszerzéséhez. Mindkét módszer ugyanahhoz az alapul szolgáló sémához biztosít hozzáférést, de mindegyik különböző munkafolyamatokat és használati eseteket szolgál ki.

Jótanács

Szeretné működés közben látni az introspekciót? Próbálja ki az AI-ügynökök csatlakoztatása a GraphQL-hez készült Fabric API-hoz egy helyi Model Context Protocol -kiszolgálóval (MCP) című oktatóanyagot. Ez a gyakorlati útmutató bemutatja, hogyan használják az AI-ügynökök az introspection-t a Fabric-adatok természetes nyelv használatával történő automatikus felderítésére és lekérdezésére.

Ki használja az introspection és a sémaexportálást?

Az introspection és a sémaexportálás értékes a következőkhöz:

Az alkalmazásfejlesztők olyan ügyfeleket hoznak létre, amelyek Fabric-adatokat használnak fel, és típusbiztos kódot kell létrehozniuk
A Háló-munkaterület közreműködői megismerik az elérhető adatstruktúrákat és tesztelik az adathozzáférést
Automatikus kiegészítést és IntelliSense-t biztosító fejlesztési eszközök és integrált fejlesztői környezetek Fabric GraphQL API-khoz
Azure API Management-integrációk , amelyek nagyvállalati szinten irányítják és védik a Fabric GraphQL-forgalmat
Szövetgazdák a feltárt adatstruktúrák auditálása és a hozzáférés-vezérlés ellenőrzésének validálása
Model Context Protocol (MCP) használatával a AI-ügynökök és asszisztensek természetesen fedezik fel és kérdezik le a Fabric-adatokat
A Power Platform fejlesztői az integrációk létrehozása előtt ismerik a Fabric-adatsémákat
CI/CD-folyamatok a Fabric GraphQL-sémaverziók nyomon követésével és a környezetek közötti kompatibilitás érvényesítésével

Akkor válassza az introspekciót , ha a sémainformációkat futásidőben programozott módon kell lekérdeznie, például a fejlesztési eszközök bekapcsolását, az AI-ügynökök engedélyezését vagy a dinamikus ügyfélfunkciók implementálását. A sémaexportálást akkor válassza , ha teljes sémafájlra van szüksége offline használatra, verziókövetésre, API-átjáró-integrációra vagy külső csapatokkal való megosztásra.

Introspection: A graphQL szabvány részét képező GraphQL introspection rendszer használatával programozott módon kérdezheti le a sémát. Az introspekciós lekérdezések lehetővé teszik a típusok, mezők és kapcsolatok dinamikus felderítését, és számos GraphQL-fejlesztőeszközt működtetnek.
Sémaexportálás: Töltsön le egy teljes SDL-fájlt (GraphQL sémadefiníciós nyelv), amely a teljes sémadefiníciót tartalmazza offline használatra, megosztásra vagy eszközintegrációra.

Szemlélődés

Alapértelmezés szerint az introspection le van tiltva az API-ban a GraphQL-elemekhez. Ezt a beállítást csak a munkaterület rendszergazdái kapcsolhatják be. Minden más felhasználó egy letiltott csúszkát fog látni.

Az introspection engedélyezése:

A felső menüben válassza az API-beállítások fogaskerék ikont.
A bal oldali navigációs sávon válassza az Introspection lapot.
Válassza ki a kapcsolót az introspection engedélyezéséhez. Az introspection engedélyezése a sémainformációkat minden olyan felhasználó számára elérhetővé teszi, aki hozzáfér az API-végponthoz.
Megjelenik a jóváhagyást kérő párbeszéd. Válassza a Megerősítés lehetőséget az introspection engedélyezéséhez, vagy a Mégse gombra kattintva kihagyhatja annak engedélyezését.

Példa önvizsgálati lekérdezésre

Íme egy gyors példa egy introspekciós lekérdezésre, amely lekéri az elérhető típusokat a sémából:

Hozzon létre egy új lekérdezést a GraphQL-szerkesztőben. Új lekérdezési lap megnyitásához válassza a meglévő lapok melletti plusz + ikont.

Írja be a következő bevezető lekérdezést a szerkesztőbe:

query {
    __schema {
        types{
            name
        }
    }
}

A lekérdezés végrehajtásához válassza a Futtatás gombot.
Az eredménypanel megjeleníti a sémában definiált összes típus listáját.

Az introspekciós lekérdezések nagy mennyiségű információt adhatnak vissza. A lekérdezés hatókörét úgy szűkítheti le, hogy konkrétabban fogalmazza meg az introspekciós kérelmet. Az összes típus lekérdezése helyett például lekérdezhet egy adott típust:

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

A lekérdezés futtatása részletes információkat ad vissza a ProductCategory típusról:

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

Az introspekciós eredmények feldolgozásakor gyakran használt szűrési minták a következők:

A dupla aláhúzásjellel kezdődő típusok (__a GraphQL-rendszertípusok) kizárása
Adott előtaggal kezdődő típusokat is beleértve, például ProductCategory

Ezek a példák a GraphQL bevezető szintaxisát mutatják be, amely bármilyen GraphQL-implementációban működik. Ez az áttekintés az alapszintű bevezető mintákat ismerteti – az introspection rendszer átfogó részleteiért, a speciális lekérdezési technikákért és a további képességekért tekintse meg a GraphQL Foundation bevezető eljárásokkal kapcsolatos hivatalos dokumentációját.

Séma exportálása

Ha egy teljes, offline másolatára van szüksége a sémadefinícióknak, használja a Fabric portál sémaexportálási funkcióját közvetlenül. Nyissa meg a GraphQL API-t, és válassza a Séma exportálása lehetőséget az eszköztárról. A böngésző letölti a teljes sémadefiníciót tartalmazó SDL-fájlt (sémadefiníciós nyelv).

Az SDL-fájl ismertetése

Az exportált fájl a GraphQL sémadefiníciós nyelvét (SDL) használja, amely egy ember által olvasható formátum, amely meghatározza az API típusait, mezőit és kapcsolatait. Az SDL-fájl a következőket tartalmazza:

Az adatentitások és mezőik objektumtípusai
Az adatok lekérését meghatározó lekérdezési műveletek
Mutációs műveletek adatok létrehozásához, frissítéséhez vagy törléséhez
Bemeneti paramétereket és típusukat meghatározó mezőargumentumok
Az egyes elemek dokumentációját tartalmazó típusleírások

Az SDL-fájlt bármely szövegszerkesztőben megnyithatja a sémastruktúra áttekintéséhez. Ez különösen hasznos a teljes API-felület megértéséhez, mielőtt integrálható lenne az alkalmazásokkal.

Az exportált séma használata

Az exportált SDL-fájl gyakori használati esetei a következők:

API Gateway-integráció: Importálás az Azure API Managementbe hitelesítés, sebességkorlátozás és gyorsítótárazás hozzáadásához
Fejlesztői környezet beállítása: Az IntelliSense konfigurálása a Visual Studio Code-ban az automatikus kiegészítéshez és az ellenőrzéshez
Verziókövetés: Commit Git vagy más verziókezelő rendszerekhez a séma időbeli alakulásának nyomon követéséhez
Csapatmunka: Megosztás külső partnerekkel vagy fejlesztői csapatokkal, akiknek meg kell ismerniük az API-struktúrát
Kódlétrehozás: A GraphQL-kódgenerátorok használatával típusbiztos ügyfeleket hozhat létre TypeScript, C#, Java vagy más nyelveken
Dokumentáció: API-referenciadokumentáció létrehozása olyan eszközökkel, mint a GraphQL Voyager vagy a GraphQL Markdown

Az introspekciós lekérdezésekkel ellentétben a sémaexportálás nem igényli az introspection engedélyezését, és az API bevezető beállításaitól függetlenül működik. Így megbízható módon érheti el a sémadefiníciót adminisztratív és fejlesztési célokra.

Sémamódosítások kezelése

A GraphQL-sémák idővel fejlődhetnek, amikor új típusokat, mezőket vagy képességeket ad hozzá az API-hoz. A séma módosításakor az exportált SDL-fájlok elavulttá válnak. Fontolja meg az alábbi eljárásokat:

Újraexportálás a módosítások után: Töltsön le egy friss SDL-fájlt, amikor módosítja az API-sémát a Fabricben. A sémamódosítások közé tartozik az adatforrások hozzáadása, a közzétett típusok módosítása vagy a meződefiníciók frissítése.
Verziókövetés: Minden exportált séma véglegesítése a forrásvezérlő rendszerbe leíró véglegesítési üzenetekkel. Ez létrehozza a sémafejlődés naplózási nyomvonalát, és szükség esetén lehetővé teszi a visszaállítást.
Kommunikáció: Ha a külső csapatok vagy alkalmazások a sémától függenek, értesítse őket a jelentős változásokról. Bár a GraphQL támogatja az additív módosításokat a meglévő lekérdezések feltörése nélkül, a mezők eltávolítása vagy átnevezése hatással lehet az ügyfelekre.
Automatizálás: CI-/CD-folyamatok esetén fontolja meg a sémaexportálások automatizálását az üzembe helyezési folyamat részeként, hogy a dokumentáció és az eszközök szinkronizálva maradjanak az API-val.

Az API-séma módosításáért felelős személynek (általában adatmérnöknek vagy API-fejlesztőnek) exportálnia és verziószámba kell helyeznie a frissített sémát, hogy fenntartsa a Fabric API és az attól függő külső rendszerek közötti konzisztenciát.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-01-21