Использование хранимых процедур с API Fabric для GraphQL

API Microsoft Fabric для GraphQL позволяет легко запрашивать и изменять данные из SQL-базы данных в Fabric и других источниках данных Fabric, таких как склады и озерные дома, с чётко типизированными схемами и богатым языком запросов, что позволяет разработчикам создавать интуитивно понятный API без написания собственного серверного кода. Хранимые процедуры можно использовать для инкапсулации и повторного использования сложной бизнес-логики, включая преобразование входных данных и проверки данных.

Кто использует хранимые процедуры с GraphQL

Хранимые процедуры в GraphQL ценны для:

  • Инженеры по данным, реализующие валидацию, трансформацию и обработку рабочих процессов данных в SQL базах данных в Fabric
  • Бэкенд-разработчики, предоставляющие сложную бизнес-логику из складов Fabric через современные GraphQL API
  • Архитекторы приложений , разрабатывающие безопасные и выполняющие API-интерфейсы, инкапсулируя бизнес-правила на платформе Fabric.
  • Разработчики баз данных модернизируют существующие процедуры хранения SQL в Fabric с интерфейсами GraphQL

Используйте хранимые процедуры, если требуется логика на стороне сервера для проверки данных, сложных вычислений или многоэтапных операций базы данных.

В этой статье показано, как опубликовать хранимую процедуру посредством мутации GraphQL в Fabric. В этом примере реализуется рабочий процесс регистрации продукта с помощью проверки на стороне сервера, преобразования данных и создания идентификаторов— все инкапсулированные в хранимой процедуре и доступные через GraphQL.

Предпосылки

Прежде чем начать, вам нужна SQL-база данных в Fabric с примерами данных:

  1. В рабочей области Fabric выберите Создать элемент>база данных SQL (предварительная версия)
  2. Присвойте базе данных имя
  3. Выберите пример данных для создания необходимых таблиц и данных

При этом создается пример базы данных AdventureWorks, включающую таблицу SalesLT.Product, используемую в этом примере.

Сценарий: регистрация нового продукта

В этом примере создается хранимая процедура для регистрации новых продуктов со встроенной бизнес-логикой:

  • Проверка: убедитесь, что ListPrice больше StandardCost
  • Преобразование данных: пишет с заглавной буквы имя продукта и нормализует номер продукта.
  • Создание идентификаторов: автоматически назначает следующий доступный ProductID

Инкапсулируя эту логику в хранимой процедуре, вы гарантируете согласованное качество данных независимо от того, какое клиентское приложение отправляет данные.

Шаг 1. Создание хранимой процедуры

Создайте хранимую процедуру T-SQL, которая реализует логику регистрации продукта:

  1. В базе данных SQL выберите "Создать запрос"

  2. Выполните следующую команду:

    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. Выберите "Выполнить" , чтобы создать хранимую процедуру

  4. После создания вы увидите RegisterProduct в разделе "Хранимые процедуры " в схеме SalesLT . Проверьте процедуру, чтобы убедиться, что она работает правильно:

    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

Шаг 2. Создание API GraphQL

Теперь создайте API GraphQL, предоставляющий как таблицы, так и хранимую процедуру:

  1. На ленте базы данных SQL выберите Новый API для GraphQL
  2. Присвойте API имя
  3. На экране "Получение данных" выберите схему SalesLT
  4. Выберите таблицы, которые нужно предоставить, и хранимую процедуру RegisterProduct
  5. Выберите Load

Получите экран данных для выбора таблиц и процедур в API для GraphQL.

API GraphQL, схема и все сопоставители автоматически создаются в секундах на основе таблиц SQL и хранимой процедуры.

Шаг 3. Вызов процедуры из GraphQL

Fabric автоматически генерирует мутацию GraphQL для хранимой процедуры. Имя мутации следует шаблону execute{ProcedureName}, поэтому процедура RegisterProduct становится executeRegisterProduct.

Чтобы проверить мутацию, выполните следующие действия:

  1. Открытие API в редакторе запросов

  2. Выполните следующую мутацию:

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

Изменение на портале API GraphQL, отображающее результаты.

Обратите внимание, что бизнес-логика хранимой процедуры автоматически обрабатывает входные данные:

  • "GraphQL swag" становится "Graphql swag" (прописной)
  • "gql-swag-001" становится "GQL-SWAG-001" (в верхнем регистре)
  • ProductID автоматически создается в виде следующего последовательного номера.

Лучшие практики

При использовании хранимых процедур с API для GraphQL:

  • Возвращаемые результирующие наборы: Структура автоматически создает изменения для хранимых процедур, использующих OUTPUT или возвращающих результирующие наборы. Возвращаемые столбцы становятся типом данных, возвращаемым мутацией GraphQL.
  • Инкапсулировать бизнес-логику: сохраняйте проверку, преобразование и сложные вычисления в хранимой процедуре, а не в клиентском коде. Это обеспечивает согласованность во всех приложениях.
  • Обработка ошибок корректно: используйте THROW инструкции для возврата значимых сообщений об ошибках, которые могут быть отображены через API GraphQL.
  • Рассмотрим создание идентификаторов: используйте логику пользовательского создания идентификаторов (например, инкремент MAX) только в том случае, если вы не используете идентификационные столбцы. В производственных сценариях идентификационные столбцы обычно являются более надежными.
  • Параметры документа: используйте четкие имена параметров, которые хорошо преобразуют имена полей GraphQL.

Предоставляя хранимые процедуры через API Fabric для GraphQL, вы объединяете возможности процедурной логики SQL с гибким интерфейсом запросов GraphQL, создавая надежные и обслуживаемые шаблоны доступа к данным.

Связанный контент

  • Last updated on