Použití uložených procedur s rozhraním Fabric API pro GraphQL

Microsoft Fabric API pro GraphQL usnadňuje dotazování a mutaci dat z SQL databáze ve Fabric a dalších zdrojích dat Fabric, jako jsou sklady a jezerní domy, s silně typovanými schématy a bohatým dotazovacím jazykem, který umožňuje vývojářům vytvářet intuitivní API bez nutnosti psát vlastní serverový kód. Uložené procedury můžete použít k zapouzdření a opětovnému použití složité obchodní logiky, včetně ověřování vstupu a transformace dat.

Kdo používá uložené procedury s GraphQL

Uložené procedury v GraphQL jsou cenné pro:

  • Datoví inženýři implementující workflowy pro validaci, transformaci a zpracování dat v SQL databázích ve Fabric
  • Back-end vývojáři, kteří vystavují komplexní obchodní logiku ze skladů Fabric prostřednictvím moderních GraphQL API
  • Architekti aplikací navrhují zabezpečená a výkonná rozhraní API, která zapouzdřují obchodní pravidla v rámci platformy Fabric.
  • Vývojáři databází modernizují stávající SQL databáze ve Fabric uložených procedurách s GraphQL rozhraními

Uložené procedury použijte v případě, že potřebujete logiku na straně serveru pro ověřování dat, složité výpočty nebo databázové operace s více kroky.

Tento článek ukazuje, jak vystavit uloženou proceduru prostřednictvím mutace GraphQL ve Fabricu. Příklad implementuje pracovní postup registrace produktu s ověřováním na straně serveru, transformací dat a generováním ID – všechny zapouzdřené v uložené proceduře a přístupné prostřednictvím GraphQL.

Požadavky

Než začnete, potřebujete SQL databázi ve Fabric se vzorovými daty:

  1. V pracovním prostoru Fabric vyberte Nová položka>databáze SQL (Preview)
  2. Zadejte název databáze.
  3. Výběr ukázkových dat pro vytvoření požadovaných tabulek a dat

Tím se vytvoří ukázková databáze AdventureWorks, která obsahuje tabulku použitou SalesLT.Product v tomto příkladu.

Scénář: Registrace nového produktu

Tento příklad vytvoří uloženou proceduru pro registraci nových produktů s integrovanou obchodní logikou:

  • Ověření: Zajišťuje, že hodnota ListPrice je větší než StandardCost.
  • Transformace dat: Kapitalizace názvu produktu a normalizace čísla výrobku.
  • Generování ID: Automaticky přiřadí další dostupné ID produktu.

Zapouzdřením této logiky do uložené procedury zajistíte konzistentní kvalitu dat bez ohledu na to, která klientská aplikace data odesílá.

Krok 1: Vytvoření uložené procedury

Vytvořte uloženou proceduru T-SQL, která implementuje logiku registrace produktu:

  1. V databázi SQL vyberte Nový dotaz.

  2. Spusťte následující příkaz:

    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. Vyberte Spustit a vytvořte uloženou proceduru.

  4. Po vytvoření uvidíte RegisterProduct pod uloženými procedurami ve schématu SalesLT. Otestujte postup, abyste ověřili, že funguje správně:

    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

Krok 2: Vytvoření rozhraní GraphQL API

Teď vytvořte rozhraní GraphQL API, které zpřístupňuje tabulky i uloženou proceduru:

  1. Na pásu databáze SQL vyberte Nové rozhraní API pro GraphQL.
  2. Zadejte název rozhraní API.
  3. Na obrazovce Získat data vyberte schéma SalesLT.
  4. Vyberte tabulky, které chcete zveřejnit, a uloženou proceduru RegisterProduct .
  5. Vyberte Načíst

Obrazovka získání dat pro výběr tabulek a procedur v rozhraní API pro GraphQL

Rozhraní GraphQL API, schéma a všechny překladače se automaticky generují v sekundách na základě tabulek SQL a uložených procedur.

Krok 3: Volání procedury z GraphQL

Platforma Fabric automaticky generuje GraphQL mutaci pro uloženou proceduru. Název mutace se řídí vzorem execute{ProcedureName}, takže se procedura RegisterProduct změní na executeRegisterProduct.

Testovat tuto mutaci:

  1. Otevření rozhraní API v editoru dotazů

  2. Spusťte následující mutaci:

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

Mutace výsledků zobrazená na portálu rozhraní GraphQL API.

Všimněte si, jak obchodní logika uložené procedury automaticky zpracovává vstup:

  • "graphQL swag" se stane "Graphql swag" (velká písmena)
  • "gql-swag-001" se stane "GQL-SWAG-001" (nahoře)
  • ID produktu se automaticky vygeneruje jako další pořadové číslo.

Osvědčené postupy

Při použití uložených procedur s rozhraním API pro GraphQL:

  • Návratové sady výsledků: Prostředky infrastruktury automaticky generují mutace pro uložené procedury, které používají OUTPUT nebo vracejí sady výsledků. Vrácené sloupce se stanou návratovým typem mutace GraphQL.
  • Zapouzdření obchodní logiky: Zachovejte ověřování, transformaci a složité výpočty v uložené proceduře, nikoli v klientském kódu. Tím se zajistí konzistence napříč všemi aplikacemi.
  • Zpracování chyb bez problémů: Pomocí THROW příkazů můžete vracet smysluplné chybové zprávy, které je možné zobrazit prostřednictvím rozhraní GraphQL API.
  • Zvažte generování ID: Použijte vlastní logiku generování ID (například zvětšení maxima) pouze v případě, že nepoužíváte sloupce identit. V produkčních scénářích jsou sloupce identit obvykle spolehlivější.
  • Parametry dokumentu: Použijte jasné názvy parametrů, které dobře překládají názvy polí GraphQL.

Díky zveřejnění uložených procedur prostřednictvím rozhraní Fabric API pro GraphQL zkombinujete výkon procedurální logiky SQL s flexibilním dotazovacím rozhraním GraphQL a vytvoříte robustní a udržovatelné vzory přístupu k datům.

Související obsah

  • Last updated on