Teilen über

Fabric-API für GraphQL-Introspection und Schemaexport

Wenn Sie Anwendungen erstellen oder externe Tools in Ihre Fabric-API für GraphQL integrieren, müssen Sie die Struktur Ihrer API verstehen – welche Typen verfügbar sind, welche Felder sie enthalten und wie sie miteinander zusammenhängen. Unabhängig davon, ob Sie Clientcode generieren, Dokumentation erstellen oder API-Verwaltungstools konfigurieren, ist der Zugriff auf Ihre Schemadefinition unerlässlich.

Die Fabric-API für GraphQL bietet zwei ergänzende Mechanismen zum Abrufen von Schemainformationen: Introspection für programmgesteuerte Laufzeitabfragen und Schemaexport zum Abrufen einer vollständigen Schemadatei. Beide Methoden bieten Ihnen Zugriff auf dasselbe zugrunde liegende Schema, aber jeder dient verschiedenen Workflows und Anwendungsfällen.

Tipp

Möchten Sie die Introspektion in Aktion sehen? Probieren Sie das Lernprogramm "KI-Agents mit Fabric-API für GraphQL mit einem lokalen MCP-Server (Model Context Protocol)" verbinden. In diesem praktischen Leitfaden wird gezeigt, wie KI-Agents die Introspektion verwenden, um Ihre Fabric-Daten automatisch mithilfe natürlicher Sprache zu ermitteln und abzufragen.

Anwender von Introspection und Schema-Export

Introspection und Schemaexport sind nützlich für:

  • Anwendungsentwickler , die Clients erstellen, die Fabric-Daten nutzen und typsicheren Code generieren müssen
  • Fabric-Arbeitsbereichsmitwirkende, die verfügbare Datenstrukturen verstehen und den Datenzugriff testen
  • Entwicklungstools und IDEs, die Autovervollständigung und IntelliSense für Fabric GraphQL-APIs bereitstellen
  • Azure API Management-Integrationen , die Fabric GraphQL-Datenverkehr auf Unternehmensebene weiterleiten und sichern
  • Fabric-Administratoren prüfen freigelegte Datenstrukturen und validieren Zugriffskontrollen
  • KI-Agenten und -Assistenten, die das Model Context Protocol (MCP) verwenden, um Fabric-Daten auf natürliche Weise zu ermitteln und abzufragen.
  • Power Platform-Entwickler verstehen Fabric-Datenschemas vor dem Erstellen von Integrationen
  • CI/CD-Pipelines, die Fabric-GraphQL-Schemaversionen nachverfolgen und die Kompatibilität über verschiedene Umgebungen hinweg validieren

Wählen Sie "Introspection " aus, wenn Sie Schemainformationen programmgesteuert zur Laufzeit abfragen müssen, z. B. Entwicklertools betreiben, KI-Agenten aktivieren oder dynamische Client-Features implementieren. Wählen Sie den Schemaexport aus, wenn Sie eine vollständige Schemadatei für die Offlineverwendung, Versionssteuerung, API-Gatewayintegration oder Freigabe für externe Teams benötigen.

  • Introspection: Fragen Sie Ihr Schema programmgesteuert mithilfe des GraphQL-Introspection-Systems ab, das Teil des GraphQL-Standards ist. Mithilfe von Introspektionsabfragen können Sie Typen, Felder und Beziehungen dynamisch ermitteln, die viele GraphQL-Entwicklungstools unterstützen.

  • Schemaexport: Laden Sie eine vollständige SDL-Datei (GraphQL Schema Definition Language) herunter, die Ihre gesamte Schemadefinition für die Offlineverwendung, Freigabe oder Toolintegration enthält.

Introspektion

Introspection ist standardmäßig für Ihre API für GraphQL-Elemente deaktiviert. Diese Einstellung kann nur von Arbeitsbereichsadministratoren umgeschaltet werden. Alle anderen Benutzer sehen einen deaktivierten Schieberegler.

So aktivieren Sie die Introspection:

  1. Wählen Sie das Zahnradsymbol " API-Einstellungen " im oberen Menü aus.

    Screenshot der Portalleiste mit der Zahnrad-Schaltfläche für Einstellungen.

  2. Wählen Sie in der linken Navigationsleiste die Seite "Introspection " aus.

    Screenshot des Schiebereglers für die Introspection-Einstellung.

  3. Wählen Sie die Umschaltfläche aus, um die Introspection zu aktivieren. Durch aktivieren der Introspektion werden Schemainformationen für alle Benutzer verfügbar gemacht, die Zugriff auf den API-Endpunkt haben.

  4. Ein Bestätigungsdialogfeld wird angezeigt. Wählen Sie "Bestätigen ", um "Introspection" zu aktivieren oder "Abbrechen ", um sie deaktiviert zu lassen.

    Screenshot des Bestätigungsdialogfelds

Beispiel für eine Introspection-Abfrage

Hier ist ein schnelles Beispiel für eine Introspection-Abfrage zum Abrufen verfügbarer Typen aus dem Schema:

  1. Erstellen Sie eine neue Abfrage im GraphQL-Editor. Wählen Sie das Pluszeichen + neben vorhandenen Registerkarten aus, um eine neue Abfrageregisterkarte zu öffnen.

    Screenshot der neuen Abfrageschaltfläche im GraphQL-Editor.

  2. Geben Sie die folgende Introspection-Abfrage im Editor ein:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Wählen Sie die Schaltfläche "Ausführen " aus, um die Abfrage auszuführen.

  4. Im Ergebnisbereich wird eine Liste aller typen angezeigt, die im Schema definiert sind.

    Screenshot des Beispiels für die Introspection-Abfrage.

Introspection-Abfragen können große Mengen von Informationen zurückgeben. Sie können den Umfang der Abfrage einschränken, indem Sie in Ihrer Introspection-Anforderung spezifischer sind. Anstatt beispielsweise alle Typen zu abfragen, können Sie einen bestimmten Typ abfragen:

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

Beim Ausführen der Abfrage werden detaillierte Informationen zum ProductCategory Typ zurückgegeben:

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

Zu den allgemeinen Filtermustern bei der Verarbeitung von Introspektionsergebnissen gehören:

  • Ausschließen von Typen beginnend mit doppelten Unterstrichen (__), bei denen es sich um GraphQL-Systemtypen handelt
  • Einschließen von Typen, die mit bestimmten Präfixen beginnen, z. B. ProductCategory

Diese Beispiele veranschaulichen die standardmäßige GraphQL-Introspektionsyntax, die in jeder Beliebigen GraphQL-Implementierung funktioniert. Diese Übersicht befasst sich mit grundlegenden Introspektionsmustern – ausführliche Informationen zum Introspectionssystem, erweiterten Abfragetechniken und zusätzlichen Funktionen finden Sie in der offiziellen Dokumentation der GraphQL Foundation zur Introspection.

Exportschema

Wenn Sie eine vollständige Offlinekopie Ihrer Schemadefinition benötigen, verwenden Sie das Schemaexportfeature direkt aus dem Fabric-Portal. Öffnen Sie Ihre API für GraphQL, und wählen Sie " Schema exportieren " auf der Symbolleiste aus. Ihr Browser lädt eine SDL-Datei (Schemadefinitionssprache) herunter, die Ihre vollständige Schemadefinition enthält.

Screenshot der Schaltfläche

Grundlegendes zur SDL-Datei

Die exportierte Datei verwendet die Schemadefinitionssprache (SCHEMA Definition Language, SDL) von GraphQL, ein lesbares Format, das die Typen, Felder und Beziehungen Ihrer API definiert. Die SDL-Datei enthält:

  • Objekttypen , die Ihre Datenentitäten mit ihren Feldern darstellen
  • Abfragevorgänge , die definieren, wie Daten abgerufen werden
  • Mutationsvorgänge zum Erstellen, Aktualisieren oder Löschen von Daten
  • Feldargumente , die Eingabeparameter und deren Typen angeben
  • Typbeschreibungen , die Dokumentation für jedes Element bereitstellen

Sie können die SDL-Datei in einem beliebigen Text-Editor öffnen, um Ihre Schemastruktur zu überprüfen. Dies ist besonders hilfreich, um die vollständige API-Oberfläche zu verstehen, bevor sie in Ihre Anwendungen integriert wird.

Verwenden des exportierten Schemas

Zu den gängigen Anwendungsfällen für die exportierte SDL-Datei gehören:

  • API-Gatewayintegration: Importieren in Azure API Management , um Authentifizierung, Ratelimitierung und Zwischenspeicherung hinzuzufügen
  • Setup der Entwicklungsumgebung: Konfigurieren von IntelliSense in Visual Studio Code für autoVervollständigen und Validierung
  • Versionsverwaltung: Commit für Git oder andere Quellcodeverwaltungssysteme, um die Schemaentwicklung im Laufe der Zeit nachzuverfolgen
  • Teamzusammenarbeit: Teilen Sie Informationen mit externen Partnern oder Entwicklungsteams, die das Verständnis Ihrer API-Struktur benötigen.
  • Codegenerierung: Verwenden von GraphQL-Codegeneratoren zum Erstellen von typsicheren Clients in TypeScript, C#, Java oder anderen Sprachen
  • Dokumentation: Generieren der API-Referenzdokumentation mithilfe von Tools wie GraphQL Voyager oder GraphQL Markdown

Im Gegensatz zu Introspection-Abfragen erfordert der Schemaexport nicht, dass die Introspection aktiviert ist und unabhängig von den Introspektioneinstellungen Ihrer API funktioniert. Dies macht es zu einer zuverlässigen Möglichkeit, auf Ihre Schemadefinition für administrative und Entwicklungszwecke zuzugreifen.

Verwalten von Schemaänderungen

GraphQL-Schemas können sich im Laufe der Zeit weiterentwickeln, wenn Sie Ihrer API neue Typen, Felder oder Funktionen hinzufügen. Wenn sich das Schema ändert, werden exportierte SDL-Dateien veraltet. Berücksichtigen Sie die folgenden Methoden:

  • Erneutes Exportieren nach Änderungen: Laden Sie eine neue SDL-Datei herunter, wenn Sie Ihr API-Schema in Fabric ändern. Schemaänderungen umfassen das Hinzufügen von Datenquellen, das Ändern verfügbar gemachter Typen oder das Aktualisieren von Felddefinitionen.
  • Versionsverwaltung: Übernehmen Sie jedes exportierte Schema in Ihr Quellcodeverwaltungssystem mit beschreibenden Commit-Nachrichten. Dadurch wird ein Überwachungspfad der Schemaentwicklung erstellt und bei Bedarf ein Rollback aktiviert.
  • Kommunikation: Wenn externe Teams oder Anwendungen von Ihrem Schema abhängen, benachrichtigen Sie sie über erhebliche Änderungen. Während GraphQL additive Änderungen unterstützt, ohne vorhandene Abfragen zu unterbrechen, können sich das Entfernen oder Umbenennen von Feldern auf Clients auswirken.
  • Automatisierung: Für CI/CD-Pipelines sollten Sie schemaexporte im Rahmen Ihres Bereitstellungsprozesses automatisieren, um sicherzustellen, dass Dokumentation und Tools mit Ihrer API synchronisiert bleiben.

Die Person, die für die Änderung des API-Schemas (in der Regel ein Datentechniker oder API-Entwickler) verantwortlich ist, sollte das aktualisierte Schema exportieren und versionieren, um die Konsistenz zwischen der Fabric-API und externen Systemen aufrechtzuerhalten, die davon abhängig sind.

Verwandte Inhalte

  • Last updated on