GraphQL için Fabric API ile saklı yordamları kullanma

GraphQL için Microsoft Fabric API, geliştiricilerin özel sunucu kodu yazmadan sezgisel bir API oluşturmasına olanak sağlayan kapsamlı şemalar ve zengin bir sorgu diliyle bir Fabric SQL veritabanı ve Veri Ambarı ve Lakehouse gibi diğer Fabric veri kaynaklarından verileri sorgulamayı ve değiştirmeyi kolaylaştırır. Giriş doğrulama ve veri dönüştürme dahil olmak üzere karmaşık iş mantığını kapsüllemek ve yeniden kullanmak için saklı yordamları kullanabilirsiniz.

GraphQL ile saklı yordamları kimler kullanır?

GraphQL'deki saklı prosedürler aşağıdakiler açısından değerlidir:

• SQL Fabric veritabanlarında veri doğrulama, dönüştürme ve işleme iş akışları uygulayan veri mühendisleri
• Fabric depolarından karmaşık iş mantığını modern GraphQL arayüzleri aracılığıyla ortaya çıkartan arka uç geliştiricileri
• Yapı platformunda iş kurallarını kapsülleyen güvenli, performanslı API'ler tasarlayan uygulama mimarları
• Veritabanı geliştiricileri, mevcut Fabric SQL veritabanı depolanmış prosedürlerini GraphQL arabirimleriyle modernleştiriyor.

Veri doğrulama, karmaşık hesaplamalar veya çok adımlı veritabanı işlemleri için sunucu tarafı mantığına ihtiyacınız olduğunda saklı yordamları kullanın.

Bu makale, Fabric'teki saklı bir yordamın GraphQL mutasyonu aracılığıyla nasıl kullanıma sunulacağını göstermektedir. Örnek, sunucu tarafı doğrulama, veri dönüştürme ve kimlik oluşturma işlemlerini içeren ve saklı yordamda kapsüllenmiş bir ürün kaydı iş akışı uygular; bu iş akışına GraphQL aracılığıyla erişilebilir.

Önkoşullar

Başlamadan önce örnek verileri içeren bir Fabric SQL veritabanı gerekir:

1. Doku çalışma alanınızda Yeni Öğe>SQL veritabanı (önizleme) öğesini seçin
2. Veritabanınıza bir ad verin
3. Gerekli tabloları ve verileri oluşturmak için Örnek veriler'i seçin

Bu, bu örnekte kullanılan tabloyu içeren SalesLT.Product AdventureWorks örnek veritabanını oluşturur.

Senaryo: Yeni bir ürün kaydetme

Bu örnek, yeni ürünleri yerleşik iş mantığıyla kaydetmek için bir saklı yordam oluşturur:

• Doğrulama: ListPrice değerinin StandardCost değerinden büyük olduğundan emin olur
• Veri dönüştürme: Ürün adını büyük harfe çevirir ve ürün numarasını normalleştirir
• Ürün Kimliği oluşturma: Sonraki mevcut Ürün Kimliği'ni otomatik olarak atar

Bu mantığı saklı bir yordamda kapsülleyerek, hangi istemci uygulamasının verileri gönderdiğinden bağımsız olarak tutarlı veri kalitesi sağlarsınız.

1. Adım: Saklı yordamı oluşturma

Ürün kayıt mantığını uygulayan bir T-SQL saklı yordamı oluşturun:

1. SQL veritabanınızda Yeni Sorgu'yu seçin

2. Aşağıdaki ifadeyi yürüt:

   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. Saklı yordamı oluşturmak için Çalıştır'ı seçin

4. Oluşturma işleminden sonra SalesLT şemasındaki Saklı Yordamlar altında RegisterProduct ifadesini görürsünüz. Düzgün çalıştığını doğrulamak için yordamı test edin:

   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. Adım: GraphQL API'si oluşturma

Şimdi hem tabloları hem de saklı yordamı kullanıma sunan bir GraphQL API'sini oluşturun:

1. SQL veritabanı şeridinde GraphQL için Yeni API'yi seçin
2. API'nize bir ad verin
3. Veri al ekranında SalesLT şemasını seçin
4. Kullanıma açmak istediğiniz tabloları ve RegisterProduct saklı yordamını seçin
5. Yükle'yi seçin

GraphQL API'si, şeması ve tüm çözümleyiciler, SQL tablolarına ve saklı yordama göre saniyeler içinde otomatik olarak oluşturulur.

3. Adım: GraphQL'den prosedürü çağırma

Fabric, saklı yordam için otomatik olarak bir GraphQL mutasyonu üretir. Mutasyon adı deseni execute{ProcedureName} izler, bu nedenle RegisterProduct yordamı executeRegisterProduct olur.

Mutasyonu test etmek için:

1. API'yi sorgu düzenleyicisinde açma

2. Aşağıdaki mutasyonu uygulayın:

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

Saklı yordamın iş mantığının, girişi otomatik olarak nasıl işlediğine dikkat edin:

• "graphQL swag""Graphql swag" olur (büyük harfle yazılır)
• "gql-swag-001" , "GQL-SWAG-001" olarak (büyük harfle) olur
• ProductID otomatik olarak sonraki sıralı sayı olarak oluşturulur

En iyi yöntemler

GraphQL API ile saklı yordamlar kullanırken:

• Dönüş sonuç kümeleri: Fabric, OUTPUT kullanan veya sonuç kümeleri döndüren saklı yordamlar için otomatik olarak mutasyonlar oluşturur. Döndürülen sütunlar GraphQL mutasyonunun dönüş türü olur.
• İş mantığını kapsülleme: Doğrulama, dönüştürme ve karmaşık hesaplamaları istemci kodu yerine saklı yordamda tutun. Bu, tüm uygulamalarda tutarlılık sağlar.
• Hataları düzgün bir şekilde işleyin: GraphQL API'sinde ortaya çıkarılabilen anlamlı hata iletileri döndürmek için THROW deyimlerini kullanın.
• Kimlik oluşturmayı göz önünde bulundurun: Kimlik sütunlarını kullanmıyorsanız yalnızca özel kimlik oluşturma mantığını kullanın (max değerini artırma gibi). Üretim senaryolarında kimlik sütunları genellikle daha güvenilirdir.
• Belge parametreleri: GraphQL alan adlarına iyi çevrilen net parametre adlarını kullanın.

Saklı yordamları GraphQL için Doku API'si aracılığıyla kullanıma sunarak SQL'in yordamsal mantığının gücünü GraphQL'in esnek sorgu arabirimiyle birleştirerek güçlü ve sürdürülebilir veri erişim desenleri oluşturursunuz.

İlgili içerik

• GraphQL Düzenleyicisi için Fabric API'si
• Microsoft Fabric'te SQL veritabanı