Utiliser des procédures stockées avec l’API Fabric pour GraphQL

L’API Microsoft Fabric pour GraphQL permet d’interroger et de muter facilement des données à partir d’une base de données Fabric SQL et d’autres sources de données Fabric telles que Data Warehouse et Lakehouse, avec des schémas fortement typés et un langage de requête enrichi permettant aux développeurs de créer une API intuitive sans écrire de code serveur personnalisé. Vous pouvez utiliser des procédures stockées pour encapsuler et réutiliser une logique métier complexe, notamment la validation d’entrée et la transformation des données.

Qui utilise des procédures stockées avec GraphQL

Les procédures stockées dans GraphQL sont utiles pour :

Ingénieurs données implémentant des workflows de validation, de transformation et de traitement des données dans les bases de données SQL Fabric
Développeurs principaux exposant une logique métier complexe à partir d’entrepôts Fabric via des API GraphQL modernes
Architectes d’applications qui conçoivent des API sécurisées et performantes qui encapsulent des règles métier au sein de la plateforme Fabric
Développeurs de bases de données qui modernisent des procédures stockées de base de données SQL Fabric existantes avec des interfaces GraphQL

Utilisez des procédures stockées lorsque vous avez besoin d’une logique côté serveur pour la validation des données, les calculs complexes ou les opérations de base de données à plusieurs étapes.

Cet article montre comment exposer une procédure stockée par le biais d’une mutation GraphQL dans Fabric. L’exemple implémente un flux de travail d’inscription de produit avec validation côté serveur, transformation de données et génération d’ID, tous encapsulés dans une procédure stockée et accessibles via GraphQL.

Prerequisites

Avant de commencer, vous avez besoin d’une base de données SQL Fabric avec des exemples de données :

Dans votre espace de travail Fabric, sélectionnez Nouvel Élément>base de données SQL (préversion)
Donnez un nom à votre base de données
Sélectionnez Exemples de données pour créer les tables et données requises

Cela crée l’exemple de base de données AdventureWorks, qui inclut la SalesLT.Product table utilisée dans cet exemple.

Scénario : inscrire un nouveau produit

Cet exemple crée une procédure stockée pour inscrire de nouveaux produits avec une logique métier intégrée :

Validation : garantit que ListPrice est supérieur à StandardCost
Transformation des données : met en majuscule le nom du produit et normalise le numéro de produit
Génération d’ID : assigne automatiquement le ProductID disponible suivant

Encapsulant cette logique dans une procédure stockée, vous garantissez une qualité de données cohérente, quelle que soit l’application cliente qui envoie les données.

Étape 1 : Créer la procédure stockée

Créez une procédure stockée T-SQL qui implémente la logique d’inscription de produit :

Dans votre base de données SQL, sélectionnez Nouvelle requête

Exécutez l’instruction suivante :

CREATE PROCEDURE SalesLT.RegisterProduct
  @Name nvarchar(50),
  @ProductNumber nvarchar(25),
  @StandardCost money,
  @ListPrice money,
  @SellStartDate datetime
AS
BEGIN
  SET NOCOUNT ON;
  SET IDENTITY\_INSERT SalesLT.Product ON;

  -- Validate pricing logic
  IF @ListPrice <= @StandardCost
    THROW 50005, 'ListPrice must be greater than StandardCost.', 1;

-- Transform product name: capitalize first letter only
  DECLARE @CleanName nvarchar(50);
  SET @CleanName = UPPER(LEFT(LTRIM(RTRIM(@Name)), 1)) + LOWER(SUBSTRING(LTRIM(RTRIM(@Name)), 2, 49));

  -- Trim and uppercase product number
  DECLARE @CleanProductNumber nvarchar(25);
  SET @CleanProductNumber = UPPER(LTRIM(RTRIM(@ProductNumber)));

  -- Generate ProductID by incrementing the latest existing ID
  DECLARE @ProductID int;
  SELECT @ProductID = ISNULL(MAX(ProductID), 0) + 1 FROM SalesLT.Product;

  INSERT INTO SalesLT.Product (
    ProductID,
    Name,
    ProductNumber,
    StandardCost,
    ListPrice,
    SellStartDate
  )
  OUTPUT 
    inserted.ProductID,
    inserted.Name,
    inserted.ProductNumber,
    inserted.StandardCost,
    inserted.ListPrice,
    inserted.SellStartDate
  VALUES (
    @ProductID,
    @CleanName,
    @CleanProductNumber,
    @StandardCost,
    @ListPrice,
    @SellStartDate
  );
END;

Sélectionnez Exécuter pour créer la procédure stockée

Après la création, vous verrez RegisterProduct sous Procédures stockées dans le schéma SalesLT . Testez la procédure pour vérifier qu’elle fonctionne correctement :

DECLARE @RC int
DECLARE @Name nvarchar(50)
DECLARE @ProductNumber nvarchar(25)
DECLARE @StandardCost money
DECLARE @ListPrice money
DECLARE @SellStartDate datetime

-- TODO: Set parameter values here.
Set @Name = 'test product'       
Set @ProductNumber = 'tst-0012'
Set @StandardCost = '10.00'
Set @ListPrice = '9.00'
Set @SellStartDate = '2025-05-01T00:00:00Z'

EXECUTE @RC = \[SalesLT\].\[RegisterProduct\] 
   @Name
  ,@ProductNumber
  ,@StandardCost
  ,@ListPrice
  ,@SellStartDate
GO

Étape 2 : Créer une API GraphQL

Créez maintenant une API GraphQL qui expose les tables et la procédure stockée :

Dans le ruban de base de données SQL, sélectionnez Nouvelle API pour GraphQL
Donnez un nom à votre API
Dans l’écran Obtenir des données, sélectionnez le schéma SalesLT
Sélectionnez les tables que vous souhaitez exposer et la procédure stockée RegisterProduct
Sélectionnez Charger

L’API GraphQL, le schéma et tous les résolveurs sont générés automatiquement en secondes en fonction des tables SQL et de la procédure stockée.

Étape 3 : Appeler la procédure à partir de GraphQL

Fabric génère automatiquement une mutation GraphQL pour la procédure stockée. Le nom de mutation suit le modèle execute{ProcedureName}, de sorte que la procédure RegisterProduct devient executeRegisterProduct.

Pour tester la mutation :

Ouvrir l’API dans l’éditeur de requête

Exécutez la mutation suivante :

mutation {
   executeRegisterProduct (
    Name: " graphQL swag ",
    ProductNumber: "gql-swag-001",
    StandardCost: 10.0,
    ListPrice: 15.0,
    SellStartDate: "2025-05-01T00:00:00Z"
  ) {
ProductID
    Name
    ProductNumber
    StandardCost
    ListPrice
    SellStartDate
   }
}

Notez comment la logique métier de la procédure stockée traite automatiquement l’entrée :

« graphQL swag » devient « Graphql swag » (majuscule)
« gql-swag-001 » devient « GQL-SWAG-001 » (majuscules)
ProductID est généré automatiquement en tant que numéro séquentiel suivant

Meilleures pratiques

Lorsque vous utilisez des procédures stockées avec l’API pour GraphQL :

Jeux de résultats de retour : Fabric génère automatiquement des mutations pour les procédures stockées qui utilisent OUTPUT ou retournent des jeux de résultats. Les colonnes retournées deviennent le type de retour de la mutation GraphQL.
Encapsuler la logique métier : conservez la validation, la transformation et les calculs complexes dans la procédure stockée plutôt que dans le code client. Cela garantit la cohérence entre toutes les applications.
Gérer correctement les erreurs : utilisez des instructions THROW pour retourner des messages d’erreur significatifs pouvant être exposés via l’API GraphQL.
Envisagez la génération d’ID : utilisez uniquement la logique de génération d’ID personnalisée (par exemple, incrémenter MAX) si vous n’utilisez pas de colonnes d’identité. Pour les scénarios de production, les colonnes d’identité sont généralement plus fiables.
Paramètres de document : utilisez des noms de paramètres clairs qui se traduisent correctement en noms de champs GraphQL.

En exposant des procédures stockées via l’API Fabric pour GraphQL, vous combinez la puissance de la logique procédurale de SQL avec l’interface de requête flexible de GraphQL, créant ainsi des modèles d’accès aux données robustes et gérables.

Rétroaction

Cette page a-t-elle été utile ?

Last updated on 2026-01-21