Partager via

API Fabric pour la vue de schéma GraphQL et l’Explorateur de schémas

L’API Fabric pour GraphQL génère automatiquement un schéma qui définit la structure de votre API en fonction des sources de données que vous connectez. Le schéma, écrit dans le langage SDL (GraphQL Schema Definition Language), décrit tous les types, champs, requêtes et mutations disponibles que les clients peuvent utiliser pour interagir avec vos données.

La vue schéma fournit une vue textuelle en lecture seule de votre schéma GraphQL complet, tandis que l’Explorateur de schémas dans le volet gauche vous permet de naviguer, d’inspecter et de modifier les objets exposés via votre API. Ensemble, ces outils vous aident à comprendre la structure de votre API et à contrôler les données accessibles aux clients.

Qui utilise la vue du schéma

La vue de schéma et l’explorateur sont utiles pour :

  • Ingénieurs de données configurant les objets du lakehouse et de l’entrepôt Fabric à exposer via GraphQL
  • Développeurs d’applications découvrant les types de données, champs et relations Fabric disponibles avant d’écrire des requêtes
  • Les contributeurs d’espace de travail Fabric comprennent et gèrent la structure d’accès aux données pour leur espace de travail
  • Développeurs décisionnels consultant les relations de données Fabric lors de la création d’applications d’analytique personnalisées

Utilisez la vue schéma pour explorer la structure de votre API et l’Explorateur de schémas pour modifier les objets de données exposés.

Accéder et explorer le schéma

Vous pouvez accéder à la vue de schéma à partir de l’éditeur de requête ou directement à partir de votre élément d’API GraphQL. Pour ouvrir la vue schéma, sélectionnez Schéma dans le coin inférieur gauche. La vue schéma affiche une version en lecture seule et textuelle de votre sdl GraphQL complet avec tous les types, champs, requêtes et mutations générés.

L’image suivante montre la vue de schéma avec le volet Explorateur de schémas à gauche :

Capture de l’écran d’affichage de la vue du schéma de l’API, qui inclut l’Explorer du schéma dans le volet gauche.

L’Explorateur de schémas dans le volet gauche vous permet de naviguer et d’inspecter tous les objets de votre API. L’Explorateur est disponible à la fois dans la vue de schéma et dans l’éditeur de requête, ce qui facilite l’exploration de votre structure d’API lors de l’écriture de requêtes.

Ouvrez les nœuds dans l’Explorateur de schémas afin de voir :

  • Types : Types GraphQL générés à partir de vos tables et vues de source de données
  • Requêtes : opérations de lecture générées automatiquement pour récupérer des données
  • Mutations : opérations d’écriture générées automatiquement pour la création, la mise à jour et la suppression de données (entrepôt uniquement)

Les types

Les types représentent la structure de vos données et apparaissent sous le nom de la source de données à partir de laquelle elles ont été générées. L’image suivante montre le type SalesOrderDetail généré à partir de la table SalesOrderDetail dans le point de terminaison d’analytique SQL AdventureWorks :

Capture d’écran du volet Explorateur de schémas montrant la liste développée des types disponibles sous un exemple de source de données nommée SalesOrderDetail.

Queries

L’API génère automatiquement des requêtes pour récupérer des données à partir des objets que vous exposez. Développez le nœud de requêtes pour afficher toutes les opérations de lecture disponibles :

Capture d’écran du volet Explorateur de schémas montrant une liste développée de requêtes générées automatiquement.

Mutations

Les mutations sont des opérations d’écriture pour la création, la mise à jour et la suppression de données. Étendez le nœud de mutation pour voir toutes les opérations d'écriture disponibles :

Capture d’écran du volet Explorateur de schémas montrant une liste développée de mutations générées automatiquement.

Remarque

Les mutations sont générées uniquement pour les sources de données Fabric Data Warehouse. Les points de terminaison SQL Analytics (lakehouses et bases de données mises en miroir) sont en lecture seule et prennent uniquement en charge les requêtes. Si vous ne voyez pas de mutations dans votre Explorateur de schémas, vérifiez que vous êtes connecté à un entrepôt de données Fabric.

Modifier des objets à l’aide de l’Explorateur de schémas

Une fois que l’API a généré votre schéma initial, vous pouvez utiliser l’Explorateur de schémas pour affiner ce qui est exposé via votre API. L’Explorateur de schémas fournit des options de gestion qui vous permettent de contrôler la structure de votre API sans modifier les sources de données sous-jacentes. Ces outils sont essentiels pour maintenir une API propre et bien organisée qui expose uniquement les données dont vos clients ont besoin.

Options de modification d’accès

Pour modifier un objet, sélectionnez les points de suspension (...) à côté de n’importe quel type dans l’Explorateur de schémas. L’exemple suivant montre le menu de modification du type SalesOrderDetail :

Capture d’écran de l’Explorateur de schémas avec les points de suspension sélectionnés, montrant les options de menu disponibles.

Options de modification disponibles

Mettre à jour le schéma : synchronise votre schéma GraphQL avec la dernière structure de la source de données. Utilisez cette option lorsque vous avez ajouté de nouvelles tables, vues ou colonnes à votre source de données et souhaitez les exposer via l’API. Cette opération découvre et ajoute de nouveaux objets tout en préservant votre configuration existante.

Renommer : modifie la façon dont l’objet apparaît dans votre API GraphQL. Cela est utile pour créer des conventions d’affectation de noms d’API plus intuitives ou masquer les détails de l’implémentation des clients. Par exemple, vous pouvez renommer tbl_SalesOrderDetail simplement SalesOrderDetail. Le renommage affecte uniquement le schéma de l’API et ne modifie pas l’objet de source de données sous-jacent.

Supprimer du schéma : supprime l’objet de votre API GraphQL, ce qui le rend indisponible pour les clients. Utilisez-le pour masquer les données sensibles, supprimer des objets déconseillés ou simplifier votre surface d’API. Les données restent dans votre source de données ; seule l’exposition de l’API est supprimée.

Gérer les relations : ouvre l’interface de gestion des relations où vous pouvez définir la façon dont les objets se connectent les uns aux autres. Les relations activent les requêtes imbriquées et la traversée de graphe, ce qui permet aux clients de récupérer des données associées dans une seule requête. Pour plus d’informations, consultez Gérer les relations dans l’API Fabric pour GraphQL.

Propriétés : affiche des métadonnées détaillées sur l’objet, y compris le nom d’origine tel qu’il apparaît dans la source de données, le nom de type GraphQL, le propriétaire et l’emplacement (espace de travail et nom de la source de données). Utilisez cette option pour vérifier comment les objets sont mappés entre votre source de données et l’API GraphQL.

Activer et désactiver les requêtes et mutations

La fonctionnalité d’activation ou de désactivation des requêtes et des mutations fournit aux administrateurs et aux développeurs un contrôle granulaire sur l’accès et l’utilisation de l’API. Il vous permet d’activer ou de désactiver de manière sélective des requêtes et mutations spécifiques dans le schéma GraphQL. Cela vous permet de gérer dynamiquement les fonctionnalités d’API sans modifier le code ni déployer des modifications.

Utilisez cette fonctionnalité pour les scénarios tels que :

  • Gestion des versions d’API : désactiver les opérations déconseillées lors de la transition des clients vers de nouvelles versions
  • Fenêtres de maintenance : désactiver temporairement les opérations d’écriture (mutations) pendant la maintenance des données
  • Sécurité et conformité : restreindre l’accès aux opérations sensibles sans les supprimer du schéma
  • Déploiements par phases : activer de nouvelles requêtes ou mutations pour les tester avant de les rendre largement disponibles

Les requêtes et mutations dans l’Explorateur de schémas ont deux autres options :

  • Désactiver : empêche toute demande d’exécuter la requête ou la mutation. Si l’exécution est tentée, une erreur est retournée. Une fois qu’une requête ou une mutation est désactivée, un rechargement de schéma se produit et la requête ou la mutation apparaît grisée dans l’Explorateur de schémas.

Capture d’écran de l’option désactiver la requête ou la mutation affichée dans l’Explorateur de schémas.

  • Activer : vous permet de réactiver une requête ou une mutation précédemment désactivée. La requête ou la mutation est immédiatement disponible après l’opération de rechargement du schéma qui se produit lorsque vous sélectionnez l’option Activer .

Capture d’écran de l’option Activer la requête de mutation affichée dans l’Explorateur de schémas.

Remarque

Les requêtes et mutations générées automatiquement à partir de procédures stockées se comportent différemment de celles générées à partir de tables ou de vues. Ils peuvent seulement être supprimés, et non désactivés. Après la suppression, vous pouvez les lire à l’aide des options Obtenir des données ou mettre à jour le schéma . Pour plus d’informations, consultez Procédures stockées.

Contenu connexe

  • Last updated on