Usare le stored procedure con l'API Fabric per GraphQL

L'API di Microsoft Fabric per GraphQL semplifica le query e le modifiche dei dati da un database SQL di Fabric e da altre origini dati di Fabric, come Data Warehouse e Lakehouse, con schemi fortemente tipizzati e un linguaggio di query avanzato che consente agli sviluppatori di creare un'API intuitiva senza scrivere codice server personalizzato. È possibile usare stored procedure per incapsulare e riutilizzare una logica di business complessa, inclusa la convalida e la trasformazione dei dati di input.

Utenti che usano stored procedure con GraphQL

La procedura memorizzata in GraphQL è utile per:

• Data engineer che implementano flussi di lavoro di convalida, trasformazione ed elaborazione dei dati nei database SQL di Fabric
• Sviluppatori back-end che espongono la complessa logica aziendale dai magazzini di Fabric tramite moderne API GraphQL.
• Architetti di applicazioni che progettano API sicure e efficienti che incapsulano le regole business all'interno della piattaforma Fabric
• Sviluppatori di database che modernizzano le stored procedures di database SQL di Fabric esistenti con le interfacce GraphQL

Usare le stored procedure quando è necessaria la logica lato server per la convalida dei dati, calcoli complessi o operazioni di database in più passaggi.

Questo articolo illustra come esporre una stored procedure tramite una mutazione GraphQL in Fabric. L'esempio implementa un flusso di lavoro di registrazione del prodotto con convalida lato server, trasformazione dei dati e generazione id, tutti incapsulati in una stored procedure e accessibili tramite GraphQL.

Prerequisiti

Prima di iniziare, è necessario un database SQL di Infrastruttura con dati di esempio:

1. Nell'area di lavoro Fabric, selezionare Nuovo elemento>database SQL (anteprima)
2. Assegnare un nome al database
3. Selezionare Dati di esempio per creare le tabelle e i dati necessari

Verrà creato il database di esempio AdventureWorks, che include la SalesLT.Product tabella usata in questo esempio.

Scenario: registrare un nuovo prodotto

Questo esempio crea una procedura archiviata per la registrazione di nuovi prodotti con logica aziendale integrata.

• Convalida: assicura che ListPrice sia maggiore di StandardCost
• Trasformazione dei dati: inizializza il nome del prodotto e normalizza il numero di prodotto
• Generazione ID: assegna automaticamente il successivo ProductID disponibile

Incapsulando questa logica in una stored procedure, si garantisce una qualità dei dati coerente indipendentemente dall'applicazione client che invia i dati.

Passaggio 1: Creare la procedura memorizzata

Creare una stored procedure T-SQL che implementa la logica di registrazione del prodotto:

1. Nel database SQL selezionare Nuova query

2. Eseguire l'istruzione seguente:

   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;
   

3. Selezionare Esegui per creare la procedura memorizzata

4. Dopo la creazione, si noterà RegisterProduct in Procedure memorizzate nello schema SalesLT. Testare la procedura per verificare che funzioni correttamente:

   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
   

Passaggio 2: Creare un'API GraphQL

Ora crea un'API GraphQL che espone sia le tabelle che la procedura memorizzata.

1. Nella barra multifunzione del database SQL selezionare Nuova API per GraphQL
2. Assegnare un nome all'API
3. Nella schermata Recupera dati selezionare lo schema SalesLT
4. Seleziona le tabelle da esporre e la stored procedure RegisterProduct
5. Seleziona Carica

L'API GraphQL, lo schema e tutti i resolver vengono generati automaticamente in pochi secondi in base alle tabelle SQL e alla stored procedure.

Passaggio 3: Chiamare la procedura da GraphQL

Fabric genera automaticamente un'operazione di modifica GraphQL per la stored procedure. Il nome della mutazione segue il modello execute{ProcedureName}, quindi la routine RegisterProduct diventa executeRegisterProduct.

Per testare la mutazione:

1. Aprire l'API nell'editor di query

2. Eseguire la mutazione seguente:

   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
      }
   }
   

Si noti come la logica di business della stored procedure elabora automaticamente l'input.

• "graphQL swag" diventa "Graphql swag" (in maiuscolo)
• "gql-swag-001" diventa "GQL-SWAG-001" (maiuscolo)
• ProductID viene generato automaticamente come numero sequenziale successivo

Procedure consigliate

Quando si utilizzano le stored procedure con l'API per GraphQL:

• Restituisce set di risultati: Fabric genera automaticamente mutazioni per le stored procedure che usano OUTPUT o restituiscono set di risultati. Le colonne restituite diventano il tipo restituito della mutazione graphQL.
• Incapsulare la logica di business: mantenere la convalida, la trasformazione e i calcoli complessi nella stored procedure anziché nel codice client. In questo modo si garantisce la coerenza tra tutte le applicazioni.
• Gestire gli errori normalmente: usare THROW istruzioni per restituire messaggi di errore significativi che possono essere visualizzati tramite l'API GraphQL.
• Prendere in considerazione la generazione di ID: usare solo la logica di generazione id personalizzata (ad esempio l'incremento di MAX) se non si usano colonne Identity. Per gli scenari di produzione, le colonne Identity sono in genere più affidabili.
• Parametri del documento: usare nomi di parametro non crittografati che traducono correttamente in nomi di campo GraphQL.

Esponendo le stored procedure tramite l'API di Fabric per GraphQL, si combina la potenza della logica procedurale di SQL con l'interfaccia di query flessibile di GraphQL, creando modelli affidabili e gestibili per l'accesso ai dati.

Contenuti correlati

• API Fabric per l'editor GraphQL
• Database SQL in Microsoft Fabric