Compartir vía

Uso de procedimientos almacenados con Fabric API para GraphQL

La API de Microsoft Fabric para GraphQL facilita la consulta y mutación de datos de una base de datos sql de Fabric y otros orígenes de datos de Fabric, como Data Warehouse y Lakehouse, con esquemas fuertemente tipados y un lenguaje de consulta enriquecido que permite a los desarrolladores crear una API intuitiva sin escribir código de servidor personalizado. Puede usar procedimientos almacenados para encapsular y reutilizar lógica de negocios compleja, incluida la validación de entrada y la transformación de datos.

Quién usa procedimientos almacenados con GraphQL

Los procedimientos almacenados de GraphQL son valiosos para:

  • Ingenieros de datos que implementan flujos de trabajo de validación, transformación y procesamiento de datos en bases de datos SQL de Fabric
  • Desarrolladores de back-end que exponen la compleja lógica empresarial desde almacenes de Fabric a través de modernas APIs de GraphQL
  • Arquitectos de aplicaciones que diseñan API seguras y de rendimiento que encapsulan reglas de negocio dentro de la plataforma Fabric
  • Desarrolladores de bases de datos que modernizan los procedimientos almacenados existentes de la base de datos SQL de Fabric con interfaces GraphQL

Use procedimientos almacenados cuando necesite lógica del lado servidor para la validación de datos, cálculos complejos o operaciones de base de datos de varios pasos.

En este artículo se muestra cómo exponer un procedimiento almacenado a través de una mutación de GraphQL en Fabric. En el ejemplo se implementa un flujo de trabajo de registro de productos con validación del lado servidor, transformación de datos y generación de identificadores, todo encapsulado en un procedimiento almacenado y accesible a través de GraphQL.

Prerrequisitos

Antes de empezar, necesita una base de datos SQL de Fabric con datos de ejemplo:

  1. En el área de trabajo de Fabric, seleccione Nuevo Elemento>base de datos SQL (versión preliminar)
  2. Asigne un nombre a la base de datos.
  3. Seleccione Datos de ejemplo para crear las tablas y los datos necesarios.

Esto crea la base de datos de ejemplo AdventureWorks, que incluye la SalesLT.Product tabla usada en este ejemplo.

Escenario: registrar un nuevo producto

En este ejemplo se crea un procedimiento almacenado para registrar nuevos productos con lógica empresarial integrada:

  • Validación: garantiza que ListPrice es mayor que StandardCost
  • Transformación de datos: capitaliza el nombre del producto y normaliza el número de producto.
  • Generación de identificadores: asigna automáticamente el siguiente ProductID disponible.

Al encapsular esta lógica en un procedimiento almacenado, se garantiza una calidad de datos coherente independientemente de la aplicación cliente que envíe los datos.

Paso 1: Crear el procedimiento almacenado

Cree un procedimiento almacenado de T-SQL que implemente la lógica de registro del producto:

  1. En la base de datos SQL, seleccione Nueva consulta.

  2. Ejecute la instrucción siguiente:

    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. Seleccione Ejecutar para crear el procedimiento almacenado.

  4. Después de la creación, verá RegisterProduct en Procedimientos almacenados en el esquema SalesLT . Pruebe el procedimiento para comprobar que funciona correctamente:

    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

Paso 2: Creación de una API de GraphQL

Ahora cree una API de GraphQL que exponga las tablas y el procedimiento almacenado:

  1. En la cinta de opciones de SQL Database, seleccione Nueva API para GraphQL.
  2. Asigne un nombre a la API.
  3. En la pantalla Obtener datos , seleccione el esquema SalesLT .
  4. Seleccione las tablas que desea exponer y el procedimiento almacenado RegisterProduct .
  5. Seleccione Cargar.

Pantalla de obtención de datos para seleccionar tablas y procedimientos en la API de GraphQL.

El GraphQL API, el esquema y todos los resolutores se generan automáticamente en segundos a partir de las tablas SQL y el procedimiento almacenado.

Paso 3: Llamada al procedimiento desde GraphQL

Fabric genera automáticamente una mutación de GraphQL para el procedimiento almacenado. El nombre de la mutación sigue el patrón execute{ProcedureName}, por lo que el procedimiento RegisterProduct se convierte en executeRegisterProduct.

Para probar la mutación:

  1. Abra la API en el editor de consultas.

  2. Ejecute la mutación siguiente:

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

Mutación en el portal de GraphQL API que muestra los resultados.

Observe cómo la lógica de negocios del procedimiento almacenado procesa automáticamente la entrada:

  • "graphQL swag" se convierte en "Graphql swag" (en mayúsculas)
  • "gql-swag-001" se convierte en "GQL-SWAG-001" (en mayúsculas)
  • ProductID se genera automáticamente como el siguiente número secuencial

procedimientos recomendados

Al usar procedimientos almacenados con API para GraphQL:

  • Conjuntos de resultados devueltos: Fabric genera automáticamente mutaciones para procedimientos almacenados que usan OUTPUT o devuelven conjuntos de resultados. Las columnas devueltas constituyen el tipo devuelto de la mutación de GraphQL.
  • Encapsular la lógica de negocios: mantenga la validación, la transformación y los cálculos complejos en el procedimiento almacenado en lugar de en el código de cliente. Esto garantiza la coherencia en todas las aplicaciones.
  • Maneje los errores de forma elegante: use THROW instrucciones para devolver mensajes de error significativos que se pueden mostrar a través de la API de GraphQL.
  • Considere la posibilidad de generar identificadores: use solo la lógica de generación de identificadores personalizada (como incrementar MAX) si no usa columnas de identidad. En escenarios de producción, las columnas de identidad suelen ser más confiables.
  • Parámetros de documento: use nombres de parámetro claros que se traduzcan bien a los nombres de campo de GraphQL.

Al exponer procedimientos almacenados a través de Fabric API para GraphQL, se combina la eficacia de la lógica de procedimientos de SQL con la interfaz de consulta flexible de GraphQL, lo que crea patrones de acceso a datos sólidos y fáciles de mantener.

Contenido relacionado

  • Last updated on