Del via

Fabric API til GraphQL-introduktion og skemaeksport

Når du bygger applikationer eller integrerer eksterne værktøjer med dit Fabric API til GraphQL, skal du forstå strukturen af dit API – hvilke typer der er tilgængelige, hvilke felter de indeholder, og hvordan de relaterer til hinanden. Uanset om du genererer klientkode, skaber dokumentation eller konfigurerer API-administrationsværktøjer, er det essentielt at få adgang til din skema-definition.

Fabric API for GraphQL tilbyder to komplementære mekanismer til at hente skemainformation: introspektion til programmatiske runtime-forespørgsler og skema-eksport til at opnå en komplet skemafil. Begge metoder giver dig adgang til det samme underliggende skema, men hver betjener forskellige arbejdsgange og anvendelsestilfælde.

Tips

Vil du se introspektion i praksis? Prøv tutorialen Connect AI Agents to Fabric API til GraphQL med en lokal Model Context Protocol (MCP) server. Denne praktiske guide viser, hvordan AI-agenter bruger introspektion til automatisk at opdage og forespørge dine Fabric-data ved hjælp af naturligt sprog.

Hvem bruger introspektion og skema-eksport

Introspektion og skema-eksport er værdifulde til:

  • Applikationsudviklere , der bygger klienter, der forbruger Fabric-data og skal generere type-sikker kode
  • Fabric workspace-bidragydere forstår, at tilgængelige datastrukturer og tester dataadgangen
  • Udviklingsværktøjer og IDE'er, der tilbyder autofuldførelse og IntelliSense for Fabric GraphQL API'er
  • Azure API Management-integrationer , der ruter og sikrer Fabric GraphQL-trafik på enterprise-niveau
  • Fabric-administratorer, der reviderer eksponerede datastrukturer og validerer adgangskontroller
  • AI-agenter og assistenter, der bruger Model Context Protocol (MCP) til naturligt at opdage og forespørge Fabric-data
  • Power Platform-udviklere forstår Fabric-dataskemaer, før de bygger integrationer
  • CI/CD-pipelines, der sporer Fabric GraphQL-skemaversioner og validerer kompatibilitet på tværs af miljøer

Vælg introspektion, når du skal forespørge skemainformation programmæssigt under kørsel, såsom at drive udviklingsværktøjer, aktivere AI-agenter eller implementere dynamiske klientfunktioner. Vælg skema-eksport, når du har brug for en komplet skemafil til offline brug, versionskontrol, API-gateway-integration eller deling med eksterne teams.

  • Introspektion: Forespørg dit skema programmatisk ved hjælp af GraphQL introspektionssystemet, som er en del af GraphQL-standarden. Introspektionsforespørgsler giver dig mulighed for dynamisk at opdage typer, felter og relationer, og de driver mange GraphQL-udviklingsværktøjer.

  • Skema-eksport: Download en komplet SDL (GraphQL Schema Definition Language)-fil, der indeholder hele din skema-definition til offline brug, deling eller værktøjsintegration.

Introspektion

Introspection er som standard deaktiveret på din API til GraphQL-elementer. Denne indstilling kan kun slås til af arbejdsområdeadministratorer. Alle andre brugere får vist en deaktiveret skyder.

For at muliggøre introspektion:

  1. Vælg API-indstillingernes tandhjulsikon i topmenuen.

    Skærmbillede, der viser portallinjen, der viser tandhjulsknappen for indstillinger.

  2. Fra venstre navigation vælger du siden Introspektion .

    Skærmbillede, der viser skyderen for introspektionsindstilling.

  3. Vælg knappen for at aktivere introspektion. Aktivering af introspektion eksponerer skemainformation for alle brugere med adgang til API-endpointet.

  4. Der vises en bekræftelsesdialogboks. Vælg Bekræft for at aktivere introspektion eller Annuller for at lade det være deaktiveret.

    Skærmbillede, der viser dialogboksen til bekræftelse af aktivering af introspektion.

Eksempel på introduktionsforespørgsel

Her er et hurtigt eksempel på en introduktionsforespørgsel til hentning af tilgængelige typer fra skemaet:

  1. Opret en ny forespørgsel i GraphQL-editoren. Vælg plus-ikonet + ved siden af eksisterende faner for at åbne en ny forespørgselsfane.

    Skærmbillede, der viser den nye forespørgselsknap i GraphQL-editoren.

  2. Indtast følgende introspektionsforespørgsel i editoren:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Vælg knappen Kør for at udføre forespørgslen.

  4. Resultatpanelet viser en liste over alle typer defineret i skemaet.

    Skærmbillede, der viser eksemplet på introspektionsforespørgslen.

Introspektionsforespørgsler kan give store mængder information. Du kan indsnævre omfanget af det, du spørger om, ved at være mere specifik i din introspektionsanmodning. For eksempel kan du i stedet for at forespørge alle typer, forespørge en specifik type:

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

Kørsel af forespørgslen returnerer detaljeret 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
          }
        }
      ]
    }
  }
}

Almindelige filtreringsmønstre ved behandling af introspektionsresultater inkluderer:

  • Undtagen typer, der starter med dobbelte understrøg (__), som er GraphQL-systemtyper
  • Inklusive typer, der starter med specifikke præfikser som ProductCategory

Disse eksempler demonstrerer standard GraphQL-introspektionssyntaks, der fungerer på tværs af enhver GraphQL-implementering. Denne oversigt dækker grundlæggende introspektionsmønstre—for omfattende detaljer om introspektionssystemet, avancerede forespørgselsteknikker og yderligere funktioner, se GraphQL Foundations officielle dokumentation om introspektion.

Eksportér skema

Når du har brug for en komplet, offline kopi af din skema-definition, brug skema-eksportfunktionen direkte fra Fabric-portalen. Åbn dit API for GraphQL og vælg Eksporter skema fra værktøjslinjen. Din browser downloader en SDL (Schema Definition Language)-fil, der indeholder din komplette skema-definition.

Skærmbillede, der viser knappen Eksporter skema.

Forståelse af SDL-filen

Den eksporterede fil bruger GraphQL's Schema Definition Language (SDL), et menneskeligt læsbart format, der definerer din API's typer, felter og relationer. SDL-filen omfatter:

  • Objekttyper, der repræsenterer dine dataenheder med deres felter
  • Forespørgselsoperationer , der definerer, hvordan data skal hentes
  • Mutationsoperationer til oprettelse, opdatering eller sletning af data
  • Feltargumenter, der specificerer inputparametre og deres typer
  • Typebeskrivelser, der indeholder dokumentation for hvert element

Du kan åbne SDL-filen i enhver teksteditor for at gennemgå din skemastruktur. Dette er særligt nyttigt for at forstå hele API-overfladen, før du integrerer det i dine applikationer.

Brug af det eksporterede skema

Almindelige anvendelsestilfælde for den eksporterede SDL-fil inkluderer:

  • API-gateway-integration: Importer til Azure API Management for at tilføje autentificering, hastighedsbegrænsning og caching
  • Opsætning af udviklingsmiljø: Konfigurer IntelliSense i Visual Studio Code til autofuldførelse og validering
  • Versionskontrol: Forpligt dig til Git eller andre versionskontrolsystemer for at følge skemaudvikling over tid
  • Teamsamarbejde: Del med eksterne partnere eller udviklingsteams, der har brug for at forstå din API-struktur
  • Kodegenerering: Brug med GraphQL-kodegeneratorer til at oprette type-sikre klienter i TypeScript, C#, Java eller andre sprog
  • Dokumentation: Generer API-referencedokumentation ved hjælp af værktøjer som GraphQL Voyager eller GraphQL Markdown

I modsætning til introspektionsforespørgsler kræver skema-eksport ikke at være aktiveret for introspektion og fungerer uanset din API's introspektionsindstillinger. Dette gør det til en pålidelig måde at få adgang til din skema-definition til administrative og udviklingsmæssige formål.

Håndtering af skemaændringer

GraphQL-skemaer kan udvikle sig over tid, efterhånden som du tilføjer nye typer, felter eller kapabiliteter til din API. Når skemaet ændres, bliver eksporterede SDL-filer forældede. Overvej disse praksisser:

  • Gen-eksportér efter ændringer: Download en frisk SDL-fil, hver gang du ændrer dit API-skema i Fabric. Skemaændringer inkluderer tilføjelse af datakilder, ændring af eksponerede typer eller opdatering af feltdefinitioner.
  • Versionskontrol: Commit hvert eksporteret skema til dit versionskontrolsystem med beskrivende commit-beskeder. Dette skaber et revisionsspor af skemaudvikling og muliggør rollback, hvis det er nødvendigt.
  • Kommunikation: Hvis eksterne teams eller applikationer er afhængige af dit skema, så underret dem om væsentlige ændringer. Selvom GraphQL understøtter additive ændringer uden at bryde eksisterende forespørgsler, kan fjernelse eller omdøbning af felter påvirke klienter.
  • Automatisering: For CI/CD-pipelines bør du overveje at automatisere skema-eksport som en del af din implementeringsproces for at sikre, at dokumentation og værktøj forbliver synkroniseret med dit API.

Den person, der er ansvarlig for at ændre API-skemaet (typisk en dataingeniør eller API-udvikler), bør eksportere og versionere det opdaterede skema for at opretholde konsistens mellem Fabric API'en og eksterne systemer, der er afhængige af den.

Relateret indhold

  • Last updated on