Usar procedimentos armazenados com a API do Fabric para GraphQL

A API GraphQL do Microsoft Fabric facilita a consulta e a mutação de dados de um banco de dados SQL do Fabric e de outras fontes de dados do Fabric, como Data Warehouse e Lakehouse, com esquemas fortemente tipados e uma linguagem de consulta avançada, permitindo que os desenvolvedores criem uma API intuitiva sem precisar escrever código de servidor personalizado. Você pode usar procedimentos armazenados para encapsular e reutilizar lógica de negócios complexa, incluindo validação de entrada e transformação de dados.

Neste exemplo, aprendemos a usar um procedimento armazenado para registrar novos produtos, com lógica do lado do servidor para validação, formatação e geração de ID, todos expostos por meio de uma mutação GraphQL no Fabric.

Introdução

Começamos criando um banco de dados SQL no Fabric:

1. No workspace do Fabric, selecione Novo Item e, em seguida, Banco de Dados SQL (versão prévia).
2. Dê um nome ao banco de dados e selecione Dados de exemplo para criar rapidamente todas as tabelas e dados necessários em seu banco de dados.

Cenário: registrar um novo produto

Suponha que você queira criar um novo produto com:

• Validação da lógica de preço (por exemplo, ListPrice > StandardCost)
• Transformação (por exemplo, coloque em maiúscula a primeira letra do nome do produto, corte e, em seguida, coloque o número do produto em maiúsculas)
• Geração de ID do Produto (incrementando o último ID do Produto)

Etapa 1: Criar o procedimento armazenado

Aqui está um procedimento armazenado T-SQL que encapsula toda a lógica de negócios de que precisamos. No banco de dados SQL, clique em Nova Consulta e use a seguinte instrução:

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;

Clique em Executar para testar a execução. Observe um novo procedimento armazenado RegisterProduct na pasta Procedimentos Armazenados no banco de dados SalesLT . Use a seguinte consulta para testar a lógica do procedimento:

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

Etapa 2: Criar uma API do GraphQL

A criação de uma API da tabela SQL é rápida, fácil e simples. Você só precisa clicar no botão Nova API para GraphQL na faixa de opções do banco de dados SQL e dar um nome à API.

Em seguida, selecione as tabelas SalesLT no banco de dados e o procedimento armazenado que acabamos de criar e clique em Carregar:

A API, o esquema e todos os resolvedores do GraphQL são gerados automaticamente em segundos com base nas tabelas SQL e no procedimento armazenado.

Etapa 3: Chamar o procedimento do GraphQL

Quando a API estiver pronta, o procedimento armazenado ficará disponível como uma mutação no esquema GraphQL do Fabric. Vá para o editor de consultas e execute a seguinte mutação:

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

Dicas

• O GraphQL do Fabric gera automaticamente campos de mutação para procedimentos armazenados que retornam um conjunto de resultados definido na saída do procedimento.
• A lógica de negócios reside dentro do procedimento, não do cliente.
• Use a geração de ID determinística somente se você não depender de colunas de identidade.

Expor procedimentos armazenados por meio de APIs do Fabric oferece o poder de definir regras robustas e consistentes no SQL para seus dados e acessá-los de forma limpa por meio do GraphQL.

Conteúdo relacionado

• API do Fabric para editor GraphQL
• Banco de dados SQL no Microsoft Fabric