Delen via

Fabric-API voor GraphQL-introspectie en schema-export

Wanneer u toepassingen bouwt of externe hulpprogramma's integreert met uw Fabric-API voor GraphQL, moet u de structuur van uw API begrijpen: welke typen er beschikbaar zijn, welke velden ze bevatten en hoe ze zich verhouden tot elkaar. Of u nu clientcode genereert, documentatie maakt of API Management-hulpprogramma's configureert, het openen van uw schemadefinitie is essentieel.

De Fabric-API voor GraphQL biedt twee aanvullende mechanismen voor het ophalen van schemagegevens: introspectie voor programmatische runtimequery's en schema-export voor het verkrijgen van een volledig schemabestand. Beide methoden bieden u toegang tot hetzelfde onderliggende schema, maar elk biedt verschillende werkstromen en gebruiksvoorbeelden.

Aanbeveling

Wilt u introspectie in actie zien? Probeer de zelfstudie AI-agents verbinden met fabric-API voor GraphQL met een lokale MCP-server (Model Context Protocol). Deze praktische handleiding laat zien hoe AI-agents introspectie gebruiken om uw Fabric-gegevens automatisch te detecteren en er query's op uit te voeren met behulp van natuurlijke taal.

Wie maakt gebruik van introspectie en schema-export

Introspectie en schema-export zijn waardevol voor:

  • Toepassingsontwikkelaars bouwen clients die Fabric-gegevens verbruiken en moeten typeveilige code genereren
  • Bijdragers aan Fabric-werkruimten begrijpen gegevensstructuren en testen gegevenstoegang
  • Ontwikkelhulpprogramma's en IDE's die automatisch aanvullen en IntelliSense voor Fabric GraphQL-API's bieden
  • Azure API Management-integraties die GraphQL-verkeer routeren en beveiligen op ondernemingsniveau
  • Infrastructuurbeheerders controleren de beschikbare gegevensstructuren en valideren van toegangsbeheer
  • AI-agents en -assistenten met behulp van Model Context Protocol (MCP) om fabric-gegevens op natuurlijke wijze te detecteren en op te vragen
  • Power Platform-ontwikkelaars begrijpen infrastructuurgegevensschema's voordat ze integraties bouwen
  • CI/CD-pijplijnen die fabric GraphQL-schemaversies bijhouden en compatibiliteit tussen omgevingen valideren

Kies introspectie wanneer u programmatisch query's op schemagegevens wilt uitvoeren, zoals hulpprogramma's voor ontwikkeling, het inschakelen van AI-agents of het implementeren van dynamische clientfuncties. Kies schema-export wanneer u een volledig schemabestand nodig hebt voor offlinegebruik, versiebeheer, INTEGRATIE van API-gateways of delen met externe teams.

  • Introspection: Voer programmatisch een query uit op uw schema met behulp van het GraphQL-introspection-systeem, dat deel uitmaakt van de GraphQL-standaard. Met introspectiequery's kunt u dynamisch typen, velden en relaties detecteren, en ze maken gebruik van veel GraphQL-ontwikkelhulpprogramma's.

  • Schemaexport: Download een volledig SDL-bestand (GraphQL Schema Definition Language) dat uw volledige schemadefinitie bevat voor offlinegebruik, delen of hulpprogramma-integratie.

Introspectie

Introspectie is standaard uitgeschakeld voor uw API voor GraphQL-items. Deze instelling kan alleen worden ingeschakeld door werkruimtebeheerders. Alle andere gebruikers zien een uitgeschakelde schuifregelaar.

Introspectie inschakelen:

  1. Selecteer het tandwielpictogram api-instellingen in het bovenste menu.

    Schermopname van de portalbalk met de knop Tandwielinstellingen.

  2. Selecteer in het linkernavigatievenster de introspectiepagina .

    Schermopname van de schuifregelaar voor instelling voor introspectie.

  3. Selecteer de wisselknop om introspectie in te schakelen. Als u introspectie inschakelt, worden schemagegevens voor alle gebruikers met toegang tot het API-eindpunt weergegeven.

  4. Er wordt een bevestigingsvenster weergegeven. Selecteer Bevestigen om introspectie in te schakelen of Annuleren om deze uitgeschakeld te laten.

    Schermopname van het bevestigingsdialoogvenster voor introspectie inschakelen.

Voorbeeld van introspectie-query

Hier volgt een snel voorbeeld van een introspectiequery om beschikbare typen op te halen uit het schema:

  1. Maak een nieuwe query in de GraphQL-editor. Selecteer het pluspictogram + naast bestaande tabbladen om een nieuw querytabblad te openen.

    Schermopname van de nieuwe queryknop in de GraphQL-editor.

  2. Voer de volgende introspectiequery in de editor in:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Selecteer de knop Uitvoeren om de query uit te voeren.

  4. In het resultatenvenster wordt een lijst weergegeven met alle typen die in het schema zijn gedefinieerd.

    Schermopname van het voorbeeld van de introspection-query.

Introspectiequeries kunnen grote hoeveelheden informatie teruggeven. U kunt het bereik beperken van wat u opvraagt door specifieker te zijn in uw introspectieaanvraag. In plaats van bijvoorbeeld een query uit te voeren op alle typen, kunt u een query uitvoeren op een specifiek type:

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

Als u de query uitvoert, wordt gedetailleerde informatie over het ProductCategory type geretourneerd:

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

Veelvoorkomende filterpatronen bij het verwerken van introspectieresultaten zijn:

  • Met uitzondering van typen die beginnen met dubbele onderstrepingstekens (__), dit zijn GraphQL-systeemtypen
  • Typen opnemen die beginnen met specifieke voorvoegsels, zoals ProductCategory

In deze voorbeelden ziet u de standaardintrospectiesyntaxis van GraphQL die in elke GraphQL-implementatie werkt. In dit overzicht worden basisintrospectiepatronen beschreven, voor uitgebreide informatie over het introspectiesysteem, geavanceerde querytechnieken en aanvullende mogelijkheden. Zie de officiële documentatie van GraphQL Foundation over introspectie.

Schema exporteren

Wanneer u een volledige offlinekopie van uw schemadefinitie nodig hebt, gebruikt u de functie voor het exporteren van schema's rechtstreeks vanuit de Fabric-portal. Open uw API voor GraphQL en selecteer Exportschema op de werkbalk. Uw browser downloadt een SDL-bestand (Schema Definition Language) met uw volledige schemadefinitie.

Schermopname van de knop Schema exporteren.

Informatie over het SDL-bestand

Het geëxporteerde bestand maakt gebruik van De Schema Definition Language (SDL) van GraphQL, een door mensen leesbare indeling die de typen, velden en relaties van uw API definieert. Het SDL-bestand bevat:

  • Objecttypen die uw gegevensentiteiten vertegenwoordigen met hun velden
  • Querybewerkingen die definiëren hoe gegevens moeten worden opgehaald
  • Mutatiebewerkingen voor het maken, bijwerken of verwijderen van gegevens
  • Veldargumenten die invoerparameters en hun typen opgeven
  • Typebeschrijvingen met documentatie voor elk element

U kunt het SDL-bestand openen in elke teksteditor om uw schemastructuur te controleren. Dit is met name handig om inzicht te krijgen in het volledige API-oppervlak voordat u deze in uw toepassingen integreert.

Het geëxporteerde schema gebruiken

Veelvoorkomende gebruiksvoorbeelden voor het geëxporteerde SDL-bestand zijn:

  • API-gatewayintegratie: importeren in Azure API Management om verificatie, frequentiebeperking en caching toe te voegen
  • Installatie van de ontwikkelomgeving: IntelliSense configureren in Visual Studio Code voor automatisch aanvullen en validatie
  • Versiebeheer: Doorvoeren in Git of andere broncodebeheersystemen om de evolutie van schema's in de loop van de tijd bij te houden
  • Teamsamenwerking: Delen met externe partners of ontwikkelteams die inzicht moeten hebben in uw API-structuur
  • Codegeneratie: gebruiken met GraphQL-codegeneratoren om typeveilige clients te maken in TypeScript, C#, Java of andere talen
  • Documentatie: API-referentiedocumentatie genereren met hulpprogramma's zoals GraphQL Voyager of GraphQL Markdown

In tegenstelling tot introspectiequery's is voor schema-export niet vereist dat introspectie is ingeschakeld en werkt dit ongeacht de instellingen voor introspectie van uw API. Dit maakt het een betrouwbare manier om toegang te krijgen tot uw schemadefinitie voor beheer- en ontwikkelingsdoeleinden.

Schemawijzigingen beheren

GraphQL-schema's kunnen zich in de loop van de tijd ontwikkelen wanneer u nieuwe typen, velden of mogelijkheden toevoegt aan uw API. Wanneer het schema wordt gewijzigd, raken geëxporteerde SDL-bestanden verouderd. Houd rekening met deze procedures:

  • Exporteer opnieuw na wijzigingen: Download een nieuw SDL-bestand wanneer u uw API-schema wijzigt in Fabric. Schemawijzigingen omvatten het toevoegen van gegevensbronnen, het wijzigen van weergegeven typen of het bijwerken van velddefinities.
  • Versiebeheer: voer elk geëxporteerd schema door naar uw broncodebeheersysteem met beschrijvende doorvoerberichten. Hiermee maakt u een audittrail van de evolutie van het schema en schakelt u indien nodig terugdraaien in.
  • Communicatie: Als externe teams of toepassingen afhankelijk zijn van uw schema, informeert u deze over belangrijke wijzigingen. Hoewel GraphQL additieve wijzigingen ondersteunt zonder bestaande query's te verbreken, kunnen het verwijderen of hernoemen van velden van invloed zijn op clients.
  • Automatisering: Voor CI/CD-pijplijnen kunt u overwegen om schema-exports te automatiseren als onderdeel van uw implementatieproces om ervoor te zorgen dat documentatie en hulpprogramma's gesynchroniseerd blijven met uw API.

De persoon die verantwoordelijk is voor het wijzigen van het API-schema (meestal een data engineer of API-ontwikkelaar) moet het bijgewerkte schema exporteren en versieren om consistentie te behouden tussen de Fabric-API en externe systemen die ervan afhankelijk zijn.

Verwante inhoud

  • Last updated on