使用 Fabric API 的預存程序來處理 GraphQL

Microsoft Fabric API for GraphQL 讓查詢與變異 Fabric 資料庫及其他 Fabric 資料來源（如倉庫、湖屋）提供便利，具備強型別結構與豐富的查詢語言，讓開發者無需撰寫自訂伺服器程式碼即可建立直覺式 API。 您可以使用預存程式來封裝及重複使用複雜的商業規則，包括輸入驗證和數據轉換。

誰會用 GraphQL 來使用儲存程序

GraphQL 中的儲存程序有以下價值：

• 在 Fabric 中實作資料驗證、轉換及處理工作流程的資料工程師
• 後端開發者透過先進的 GraphQL API 從 Fabric 倉庫中公開複雜的商業邏輯
• 應用程式架構師設計安全且效能高的 API，將商業規則封裝於 Fabric 平台中
• 資料庫開發者在 Fabric 中現代化現有的 SQL 資料庫，並搭配 GraphQL 介面

當你需要伺服器端邏輯進行資料驗證、複雜計算或多步驟資料庫操作時，可以使用儲存程序。

本文示範如何透過 Fabric 中的 GraphQL 變異來暴露儲存程序。 本範例實作產品註冊工作流程，包含伺服器端驗證、資料轉換與ID產生——全部封裝在儲存程序中，並可透過GraphQL存取。

先決條件

在開始之前，你需要在 Fabric 裡建立一個包含範例資料的 SQL 資料庫：

1. 在你的 Fabric 工作區中，選擇 新項目>SQL 資料庫（預覽）
2. 給你的資料庫取個名字
3. 選擇 範例資料 以建立所需的表格與資料

這會建立 AdventureWorks 範例資料庫，其中包含本範例中使用的 SalesLT.Product 表格。

案例：註冊新產品

此範例建立一個儲存程序，用於註冊新產品，並內建商業邏輯：

• 驗證：確保 ListPrice 高於標準成本
• 資料轉換：將產品名稱大寫並標準化產品編號
• ID 產生：自動指派下一個可用的 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. 建立後，你會在 SalesLT 架構的儲存程序中看到 RegisterProduct。 測試程序以確認其運作正確：

   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：建立 GraphQL API

現在建立一個 GraphQL API，同時暴露資料表與儲存程序：

1. 在 SQL 資料庫功能區中，選擇 GraphQL 的新 API
2. 給你的 API 取個名字
3. 在 「取得資料 」畫面，選擇 SalesLT 架構
4. 選擇你想公開的資料表和 RegisterProduct 儲存程序
5. 選擇 載入

GraphQL API、架構和所有解析程式都會根據 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
      }
   }
   

請注意儲存程序的商業邏輯如何自動處理輸入：

• 「graphQL swag」 變成 「Graphql swag」（ 大寫）
• 「GQL-SWAG-001」 變成 「GQL-SWAG-001」（ 大寫）
• ProductID 會自動產生為下一個連續編號

最佳做法

使用 API for GraphQL 的儲存程序時：

• 回傳結果集：Fabric 會自動為使用 OUTPUT 或回傳結果集的儲存程序產生變異。 回傳的欄位即為 GraphQL 變異的返回類型。
• 封裝商業邏輯：將驗證、轉換及複雜計算保留在儲存程序中，而非用戶端程式碼中。 這確保了所有應用的一致性。
• 優雅處理錯誤：使用 THROW 語句回傳可透過 GraphQL API 呈現的有意義錯誤訊息。
• 考慮 ID 生成：只有在沒有使用識別欄位時，才使用自訂的 ID 生成邏輯（例如遞增 MAX）。 在生產情境中，身份欄位通常較為可靠。
• 文件參數：使用清晰且能順利轉換成 GraphQL 欄位名稱的參數名稱。

透過 Fabric API 為 GraphQL 暴露儲存程序，結合了 SQL 的程序邏輯與 GraphQL 靈活的查詢介面，創造出穩健且易於維護的資料存取模式。

相關內容

• 適用於 GraphQL 編輯器的 Fabric API
• Fabric 中的 SQL 資料庫