Dela via

Fabric API för GraphQL-introspektion och schemaexport

När du skapar program eller integrerar externa verktyg med ditt Fabric-API för GraphQL måste du förstå strukturen för ditt API– vilka typer som är tillgängliga, vilka fält de innehåller och hur de relaterar till varandra. Oavsett om du genererar klientkod, skapar dokumentation eller konfigurerar API-hanteringsverktyg är det viktigt att komma åt schemadefinitionen.

Infrastruktur-API:et för GraphQL innehåller två kompletterande mekanismer för att hämta schemainformation: introspektion för programmatiska körningsfrågor och schemaexport för att hämta en fullständig schemafil. Båda metoderna ger dig åtkomst till samma underliggande schema, men var och en hanterar olika arbetsflöden och användningsfall.

Tips/Råd

Vill du se introspektion i praktiken? Prova självstudien Anslut AI-agenter till Fabric API för GraphQL med en lokal MCP-server (Model Context Protocol). Den här praktiska guiden visar hur AI-agenter använder introspektion för att automatiskt identifiera och köra frågor mot dina Fabric-data med naturligt språk.

Vem använder introspektion och schemaexport

Introspektion och schemaexport är värdefulla för:

  • Programutvecklare skapar klienter som använder Infrastrukturdata och behöver generera typsäker kod
  • Fabric arbetsytedeltagare förstår de tillgängliga datastrukturerna och testar tillgången till data
  • Utvecklingsverktyg och IDE:er som tillhandahåller automatisk komplettering och IntelliSense för Fabric GraphQL-API:er
  • Azure API Management-integreringar som dirigerar och skyddar Fabric GraphQL-trafik på företagsnivå
  • Infrastrukturadministratörer granskar exponerade datastrukturer och validerar åtkomstkontroller
  • AI-agenter och assistenter som använder Model Context Protocol (MCP) för att identifiera och köra frågor mot Fabric-data naturligt
  • Power Platform-utvecklare förstår Infrastrukturdatascheman innan de skapar integreringar
  • CI/CD-pipelines spårar Fabric GraphQL-schemaversioner och validerar kompatibilitet mellan miljöer

Välj introspektion när du behöver fråga efter schemainformation programmatiskt under körning, till exempel när du använder utvecklingsverktyg, möjliggör AI-agenter eller implementerar dynamiska klientfunktionaliteter. Välj schemaexport när du behöver en fullständig schemafil för offlineanvändning, versionskontroll, API Gateway-integrering eller delning med externa team.

  • Introspektion: Fråga schemat programmatiskt med graphQL-introspektionssystemet, som är en del av GraphQL-standarden. Med introspektionsfrågor kan du identifiera typer, fält och relationer dynamiskt, och de driver många GraphQL-utvecklingsverktyg.

  • Schemaexport: Ladda ned en fullständig SDL-fil (GraphQL Schema Definition Language) som innehåller hela schemadefinitionen för offlineanvändning, delning eller verktygsintegrering.

Introspektion

Som standard inaktiveras introspektion i api:et för GraphQL-objekt. Den här inställningen kan bara växlas av arbetsyteadministratörer. Alla andra användare kommer att se ett inaktiverat skjutreglage.

Så här aktiverar du introspektion:

  1. Välj kugghjulsikonen FÖR API-inställningar på den översta menyn.

    Skärmbild som visar portalfältet som visar kugghjulsknappen för inställningar.

  2. I det vänstra navigeringsfältet väljer du sidan Introspektion .

    Skärmbild som visar skjutreglaget för introspektioninställning.

  3. Välj växlingsknappen för att aktivera introspektion. Aktivering av introspektion visar schemainformation för alla användare med åtkomst till API-slutpunkten.

  4. En dialogruta för bekräftelse visas. Välj Bekräfta för att aktivera introspektion eller Avbryt för att lämna det inaktiverat.

    Skärmbild som visar dialogrutan för att bekräfta aktivering av introspektion.

Exempel på introspektionfråga

Här är ett snabbt exempel på en introspektionsfråga för att hämta tillgängliga typer från schemat:

  1. Skapa en ny fråga i GraphQL-redigeraren. Välj plusikonen + bredvid befintliga flikar för att öppna en ny frågeflik.

    Skärmbild som visar den nya frågeknappen i GraphQL-redigeraren.

  2. Ange följande introspektionsfråga i redigeraren:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Välj knappen Kör för att köra frågan.

  4. Resultatfönstret visar en lista över alla typer som definierats i schemat.

    Skärmbild som visar exempel på introspektionsfråga.

Introspektionsfrågor kan returnera stora mängder information. Du kan begränsa omfånget för det du frågar efter genom att vara mer specifik i din introspektionsbegäran. I stället för att fråga alla typer kan du till exempel fråga en viss typ:

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

Om du kör frågan returneras detaljerad information om ProductCategory typen:

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

Vanliga filtreringsmönster vid bearbetning av introspektionsresultat är:

  • Exkludering av typer som börjar med dubbla understreck (__), som är GraphQL-systemtyper
  • Inkludera typer som börjar med specifika prefix som ProductCategory

De här exemplen visar standardsyntax för GraphQL-introspektion som fungerar i alla GraphQL-implementeringar. Den här översikten beskriver grundläggande introspektionsmönster – omfattande information om introspektionssystemet, avancerade frågetekniker och ytterligare funktioner finns i GraphQL Foundations officiella dokumentation om introspektion.

Exportera schema

När du behöver en fullständig offlinekopia av schemadefinitionen använder du funktionen för schemaexport direkt från Fabric-portalen. Öppna API:et för GraphQL och välj Exportera schema i verktygsfältet. Webbläsaren laddar ned en SDL-fil (Schema Definition Language) som innehåller din fullständiga schemadefinition.

Skärmbild som visar knappen exportera schema.

Förstå SDL-filen

Den exporterade filen använder GraphQL:s SDL (Schema Definition Language), ett format som kan läsas av människor och som definierar api:ets typer, fält och relationer. SDL-filen innehåller:

  • Objekttyper som representerar dina dataentiteter med sina fält
  • Frågeåtgärder som definierar hur du hämtar data
  • Mutationsåtgärder för att skapa, uppdatera eller ta bort data
  • Fältargument som anger indataparametrar och deras typer
  • Typbeskrivningar som tillhandahåller dokumentation för varje element

Du kan öppna SDL-filen i valfri textredigerare för att granska schemastrukturen. Detta är särskilt användbart för att förstå den fullständiga API-ytan innan du integrerar den i dina program.

Använda det exporterade schemat

Vanliga användningsfall för den exporterade SDL-filen är:

  • API Gateway-integrering: Importera till Azure API Management för att lägga till autentisering, hastighetsbegränsning och cachelagring
  • Konfiguration av utvecklingsmiljö: Konfigurera IntelliSense i Visual Studio Code för automatisk komplettering och validering
  • Versionskontroll: Checka in till Git eller andra källkontrollsystem för att spåra schemautvecklingen över tid
  • Teamsamarbete: Dela med externa partner eller utvecklingsteam som behöver förstå din API-struktur
  • Kodgenerering: Använd med GraphQL-kodgeneratorer för att skapa typsäkra klienter i TypeScript, C#, Java eller andra språk
  • Dokumentation: Generera API-referensdokumentation med hjälp av verktyg som GraphQL Voyager eller GraphQL Markdown

Till skillnad från introspektionsfrågor kräver schemaexport inte att introspektion aktiveras och fungerar oavsett api:ets introspektionsinställningar. Detta gör det till ett tillförlitligt sätt att komma åt schemadefinitionen i administrativa och utvecklingsmässiga syften.

Hantera schemaändringar

GraphQL-scheman kan utvecklas med tiden när du lägger till nya typer, fält eller funktioner i ditt API. När schemat ändras blir exporterade SDL-filer inaktuella. Tänk på följande metoder:

  • Exportera igen efter ändringar: Ladda ned en ny SDL-fil när du ändrar DITT API-schema i Infrastrukturresurser. Schemaändringar inkluderar att lägga till datakällor, ändra exponerade typer eller uppdatera fältdefinitioner.
  • Versionshantering: Commita varje exporterat schema till källkontrollsystemet med beskrivande commit-meddelanden. Detta skapar en spårningslogg för schemautveckling och aktiverar återställning om det behövs.
  • Kommunikation: Om externa team eller program är beroende av ditt schema meddelar du dem om betydande ändringar. GraphQL stöder additiva ändringar utan att bryta befintliga frågor, men om du tar bort eller byter namn på fält kan det påverka klienterna.
  • Automatisering: För CI/CD-pipelines bör du överväga att automatisera schemaexporter som en del av distributionsprocessen för att säkerställa att dokumentation och verktyg förblir synkroniserade med ditt API.

Den person som ansvarar för att ändra API-schemat (vanligtvis en datatekniker eller API-utvecklare) bör exportera och version det uppdaterade schemat för att upprätthålla konsekvens mellan Infrastruktur-API:et och externa system som är beroende av det.

Relaterat innehåll

  • Last updated on