Partage via

API Fabric pour l’introspection et l’exportation de schémas GraphQL

Lorsque vous générez des applications ou intégrez des outils externes à votre API Fabric pour GraphQL, vous devez comprendre la structure de votre API : quels types sont disponibles, quels champs ils contiennent et comment ils se rapportent les uns aux autres. Que vous générez du code client, créez de la documentation ou configurez des outils de gestion des API, l’accès à votre définition de schéma est essentiel.

L’API Fabric pour GraphQL fournit deux mécanismes complémentaires pour récupérer les informations de schéma : l’introspection pour les requêtes d’exécution programmatiques et l’exportation de schéma pour obtenir un fichier de schéma complet. Les deux méthodes vous donnent accès au même schéma sous-jacent, mais chacune sert des flux de travail et des cas d’usage différents.

Conseil / Astuce

Vous souhaitez voir l’introspection en action ? Essayez le tutoriel Connecter des agents IA à l’API Fabric pour GraphQL avec un serveur MCP (Model Context Protocol) local. Ce guide pratique montre comment les agents IA utilisent l’introspection pour détecter et interroger automatiquement vos données Fabric à l’aide du langage naturel.

Qui utilise l'introspection et l'export de schéma

L’introspection et l'exportation de schémas sont utiles pour :

  • Développeurs d’applications qui génèrent des clients qui consomment des données Fabric et doivent générer du code de type sécurisé
  • Contributeurs d’espace de travail Fabric qui comprennent les structures de données disponibles et testent l’accès aux données
  • Des outils de développement et des IDE fournissant la saisie semi-automatique et l'IntelliSense pour les API Fabric GraphQL
  • Intégrations de Gestion des API Azure qui routent et sécurisent le trafic Fabric GraphQL au niveau de l’entreprise
  • Audit des administrateurs de structure des structures de données exposées et validation des contrôles d’accès
  • Agents et assistants IA utilisant le protocole MCP (Model Context Protocol) pour découvrir et interroger naturellement les données Fabric
  • Développeurs Power Platform qui comprennent les schémas de données Fabric avant de créer des intégrations
  • Pipelines CI/CD qui effectuent le suivi des versions de schéma Fabric GraphQL et validation de la compatibilité entre les environnements

Choisissez l’introspection lorsque vous devez interroger des informations de schéma par programmation au moment de l’exécution, telles que l’alimentation des outils de développement, l’activation d’agents IA ou l’implémentation de fonctionnalités client dynamiques. Choisissez l’exportation de schéma lorsque vous avez besoin d’un fichier de schéma complet pour une utilisation hors connexion, un contrôle de version, une intégration de passerelle d’API ou un partage avec des équipes externes.

  • Introspection : interrogez votre schéma par programmation à l’aide du système d’introspection GraphQL, qui fait partie de la norme GraphQL. Les requêtes d’introspection vous permettent de découvrir des types, des champs et des relations dynamiquement, et elles alimentent de nombreux outils de développement GraphQL.

  • Exportation de schéma : téléchargez un fichier SDL complet (GraphQL Schema Definition Language) qui contient l’intégralité de votre définition de schéma pour une utilisation, un partage ou une intégration d’outils hors connexion.

Introspection

Par défaut, l’introspection est désactivée sur votre API pour les éléments GraphQL. Ce paramètre ne peut être activé que par les administrateurs de l’espace de travail. Tous les autres utilisateurs verront un curseur désactivé.

Pour activer l’introspection :

  1. Sélectionnez l’icône d’engrenage paramètres de l’API dans le menu supérieur.

    Capture d’écran montrant la barre du portail montrant le bouton d’engrenage des paramètres.

  2. Dans le volet de navigation gauche, sélectionnez la page Introspection .

    Capture d’écran montrant le curseur du paramètre d’introspection.

  3. Sélectionnez le bouton bascule pour activer l’introspection. L’activation de l’introspection expose les informations de schéma à tous les utilisateurs ayant accès au point de terminaison de l’API.

  4. Une boîte de dialogue de confirmation s’affiche. Sélectionnez Confirmer pour activer l’introspection ou Annuler pour le laisser désactivé.

    Capture d’écran montrant la boîte de dialogue de confirmation d’activation de l’introspection.

Exemple de requête d’introspection

Voici un exemple rapide d’une requête d’introspection pour récupérer les types disponibles à partir du schéma :

  1. Créez une requête dans l’éditeur GraphQL. Sélectionnez l’icône plus + en regard des onglets existants pour ouvrir un nouvel onglet de requête.

    Capture d’écran montrant le nouveau bouton de requête dans l’éditeur GraphQL.

  2. Entrez la requête d’introspection suivante dans l’éditeur :

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Sélectionnez le bouton Exécuter pour exécuter la requête.

  4. Le volet de résultats affiche une liste de tous les types définis dans le schéma.

    Capture d’écran montrant l’exemple de requête d’introspection.

Les requêtes d’introspection peuvent retourner de grandes quantités d’informations. Vous pouvez limiter l’étendue de ce que vous interrogez en étant plus spécifique dans votre demande d’introspection. Par exemple, au lieu d’interroger tous les types, vous pouvez interroger un type spécifique :

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

L’exécution de la requête retourne des informations détaillées sur le ProductCategory type :

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

Les modèles de filtrage courants lors du traitement des résultats d’introspection sont les suivants :

  • Exclusion des types commençant par des traits de soulignement doubles (__), qui sont des types système GraphQL
  • Inclusion de types commençant par des préfixes spécifiques comme ProductCategory

Ces exemples illustrent la syntaxe d’introspection GraphQL standard qui fonctionne sur n’importe quelle implémentation GraphQL. Cette vue d’ensemble couvre les modèles d’introspection de base : pour plus d’informations sur le système d’introspection, les techniques d’interrogation avancées et les fonctionnalités supplémentaires, consultez la documentation officielle de GraphQL Foundation sur l’introspection.

Schéma d’exportation

Lorsque vous avez besoin d’une copie complète et hors connexion de votre définition de schéma, utilisez la fonctionnalité d’exportation de schéma directement à partir du portail Fabric. Ouvrez votre API pour GraphQL et sélectionnez Exporter le schéma dans la barre d’outils. Votre navigateur télécharge un fichier SDL (Schema Definition Language) contenant votre définition de schéma complète.

Capture d’écran montrant le bouton exporter le schéma.

Présentation du fichier SDL

Le fichier exporté utilise le langage SDL (Schema Definition Language) de GraphQL, un format lisible par l’homme qui définit les types, les champs et les relations de votre API. Le fichier SDL inclut les éléments suivants :

  • Types d’objets représentant vos entités de données avec leurs champs
  • Opérations de requête qui définissent comment récupérer des données
  • Opérations de mutation pour la création, la mise à jour ou la suppression de données
  • Arguments de champ qui spécifient les paramètres d’entrée et leurs types
  • Descriptions de type fournissant de la documentation pour chaque élément

Vous pouvez ouvrir le fichier SDL dans n’importe quel éditeur de texte pour passer en revue votre structure de schéma. Cela est particulièrement utile pour comprendre l’aire d’API complète avant de l’intégrer à vos applications.

Utilisation du schéma exporté

Les cas d’usage courants pour le fichier SDL exporté sont les suivants :

  • Intégration de la passerelle d’API : Importer dans Gestion des API Azure pour ajouter l’authentification, la limitation du débit et la mise en cache
  • Configuration de l’environnement de développement : Configurer IntelliSense dans Visual Studio Code pour la saisie semi-automatique et la validation
  • Contrôle de version : Valider sur Git ou d’autres systèmes de contrôle de code source pour suivre l’évolution du schéma au fil du temps
  • Collaboration d’équipe : partager avec des partenaires externes ou des équipes de développement qui doivent comprendre votre structure d’API
  • Génération de code : utiliser avec des générateurs de code GraphQL pour créer des clients de type sécurisé dans TypeScript, C#, Java ou d’autres langages
  • Documentation : Générer une documentation de référence d’API à l’aide d’outils tels que GraphQL Voyager ou GraphQL Markdown

Contrairement aux requêtes d’introspection, l’exportation de schéma ne nécessite pas l’activation de l’introspection et fonctionne indépendamment des paramètres d’introspection de votre API. Cela permet d’accéder à votre définition de schéma à des fins d’administration et de développement.

Gestion des modifications de schéma

Les schémas GraphQL peuvent évoluer au fil du temps lorsque vous ajoutez de nouveaux types, champs ou fonctionnalités à votre API. Lorsque le schéma change, les fichiers SDL exportés deviennent obsolètes. Tenez compte des pratiques suivantes :

  • Réexporter après les modifications : téléchargez un nouveau fichier SDL chaque fois que vous modifiez votre schéma d’API dans Fabric. Les modifications de schéma incluent l’ajout de sources de données, la modification des types exposés ou la mise à jour des définitions de champs.
  • Contrôle de version : validez chaque schéma exporté dans votre système de contrôle de code source avec des messages de validation descriptifs. Cela crée une piste d’audit de l’évolution du schéma et permet la réversion si nécessaire.
  • Communication : si des équipes ou applications externes dépendent de votre schéma, informez-les des modifications importantes. Alors que GraphQL prend en charge les modifications additives sans interrompre les requêtes existantes, la suppression ou le changement de nom des champs peut avoir un impact sur les clients.
  • Automatisation : pour les pipelines CI/CD, envisagez d’automatiser les exportations de schémas dans le cadre de votre processus de déploiement pour vous assurer que la documentation et les outils restent synchronisés avec votre API.

La personne responsable de la modification du schéma d’API (généralement un ingénieur de données ou un développeur d’API) doit exporter et versionr le schéma mis à jour pour maintenir la cohérence entre l’API Fabric et les systèmes externes qui en dépendent.

Contenu connexe

  • Last updated on