Menggunakan prosedur tersimpan dengan Fabric API untuk GraphQL

Microsoft Fabric API untuk GraphQL memudahkan pencarian dan mutasi data dari database SQL di Fabric dan sumber data Fabric lainnya seperti gudang dan lakehouse, dengan skema yang sangat diketik dan bahasa query yang kaya memungkinkan pengembang membuat API intuitif tanpa harus menulis kode server khusus. Anda dapat menggunakan prosedur tersimpan untuk merangkum dan menggunakan kembali logika bisnis yang kompleks, termasuk validasi input dan transformasi data.

Siapa yang memakai prosedur tersimpan dengan GraphQL?

Prosedur tersimpan di GraphQL sangat berharga untuk:

  • Data engineer yang mengimplementasikan alur kerja validasi, transformasi, dan pemrosesan data di database SQL di Fabric
  • Pengembang backend memperkenalkan logika bisnis kompleks dari gudang data Fabric melalui API GraphQL modern
  • Arsitek aplikasi yang merancang API yang aman dan berkinerja yang merangkum aturan bisnis dalam platform Fabric
  • Pengembang basis data memodernisasi basis data SQL yang sudah ada dalam prosedur tersimpan Fabric dengan antarmuka GraphQL

Gunakan prosedur tersimpan saat Anda memerlukan logika sisi server untuk validasi data, perhitungan kompleks, atau operasi database multi-langkah.

Artikel ini menunjukkan cara mengekspos prosedur tersimpan melalui mutasi GraphQL di Fabric. Contohnya mengimplementasikan alur kerja pendaftaran produk dengan validasi sisi server, transformasi data, dan pembuatan ID—semua dienkapsulasi dalam prosedur tersimpan dan dapat diakses melalui GraphQL.

Prasyarat

Sebelum Anda memulai, Anda memerlukan database SQL di Fabric dengan data contoh:

  1. Di ruang kerja Fabric Anda, pilih Item Baru>Database SQL (pratinjau)
  2. Beri nama database Anda
  3. Pilih Contoh data untuk membuat tabel dan data yang diperlukan

Ini membuat database sampel AdventureWorks, yang mencakup SalesLT.Product tabel yang digunakan dalam contoh ini.

Skenario: mendaftarkan produk baru

Contoh ini membuat prosedur tersimpan untuk mendaftarkan produk baru dengan logika bisnis bawaan:

  • Validasi: Memastikan ListPrice lebih besar dari StandardCost
  • Transformasi data: Mengkapitalisasi nama produk dan menormalkan nomor produk
  • Pembuatan ID: Secara otomatis menetapkan ProductID berikutnya yang tersedia

Dengan merangkum logika ini dalam prosedur tersimpan, Anda memastikan kualitas data yang konsisten terlepas dari aplikasi klien mana yang mengirimkan data.

Langkah 1: Buat prosedur tersimpan

Buat prosedur tersimpan T-SQL yang menerapkan logika pendaftaran produk:

  1. Di database SQL Anda, pilih Kueri Baru

  2. Jalankan pernyataan berikut:

    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. Pilih Jalankan untuk membuat prosedur tersimpan

  4. Setelah pembuatan, Anda akan melihat RegisterProduct di bawah Prosedur Tersimpan dalam skema SalesLT . Uji prosedur untuk memverifikasi bahwa prosedur berfungsi dengan benar:

    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

Langkah 2: Membuat API GraphQL

Sekarang buat API GraphQL yang mengekspos tabel dan prosedur tersimpan:

  1. Di pita database SQL, pilih API Baru untuk GraphQL
  2. Beri nama API Anda
  3. Di layar Dapatkan data, pilih skema SalesLT
  4. Pilih tabel yang ingin Anda ekspos dan prosedur tersimpan RegisterProduct
  5. Pilih Muat

Dapatkan layar data untuk memilih tabel dan prosedur di API untuk GraphQL.

GraphQL API, skema, dan semua resolver secara otomatis dihasilkan dalam hitungan detik berdasarkan tabel SQL dan prosedur tersimpan.

Langkah 3: Panggil prosedur dari GraphQL

Fabric secara otomatis menghasilkan mutasi GraphQL untuk prosedur tersimpan. Nama mutasi mengikuti pola execute{ProcedureName}, sehingga prosedur RegisterProduct menjadi executeRegisterProduct.

Untuk menguji mutasi:

  1. Buka API di editor kueri

  2. Jalankan mutasi berikut:

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

Mutasi di portal GraphQL API yang menampilkan hasilnya.

Perhatikan bagaimana logika bisnis prosedur tersimpan secara otomatis memproses input:

  • "graphQL swag" menjadi "Graphql swag" (huruf besar)
  • "gql-swag-001" menjadi "GQL-SWAG-001" (dengan huruf kapital)
  • ProductID secara otomatis dibuat sebagai nomor berurutan berikutnya

Praktik terbaik

Saat menggunakan prosedur tersimpan dengan API untuk GraphQL:

  • Mengembalikan tataan hasil: Fabric secara otomatis menghasilkan mutasi untuk prosedur tersimpan yang menggunakan OUTPUT atau mengembalikan tataan hasil. Kolom yang dikembalikan menjadi tipe pengembalian untuk mutasi GraphQL.
  • Merangkum logika bisnis: Simpan validasi, transformasi, dan perhitungan kompleks dalam prosedur tersimpan daripada dalam kode klien. Ini memastikan konsistensi di semua aplikasi.
  • Menangani kesalahan dengan anggun: Gunakan THROW pernyataan untuk mengembalikan pesan kesalahan yang bermakna yang dapat muncul melalui API GraphQL.
  • Pertimbangkan pembuatan ID: Hanya gunakan logika pembuatan ID kustom (seperti menaikkan MAX) jika Anda tidak menggunakan kolom identitas. Untuk skenario produksi, kolom identitas biasanya lebih dapat diandalkan.
  • Parameter dokumen: Gunakan nama parameter jelas yang diterjemahkan dengan baik ke nama bidang GraphQL.

Dengan mengekspos prosedur tersimpan melalui Fabric API untuk GraphQL, Anda menggabungkan kekuatan logika prosedural SQL dengan antarmuka kueri fleksibel GraphQL, menciptakan pola akses data yang kuat dan dapat dipertahankan.

Konten terkait

  • Last updated on