在網狀架構中建立 GraphQL 的 API 並新增資料

藉由建立 API 開始使用適用於 GraphQL 的網狀架構 API，然後連結資料來源以公開您透過 API 選擇的資料。 網狀架構會根據您的資料自動建置 GraphQL 架構，而應用程式已準備好在幾分鐘內連線。

誰應該建立 GraphQL API

在 Fabric 中建立 GraphQL API 的設計目的是：

• 資料工程師 透過現代 API 公開 Fabric 湖屋與倉庫資料供應用程式使用
• 想要快速建立資料存取 API 而不撰寫後端程式碼的 Fabric 工作區貢獻者
• BI 開發者正在打造需要程式化存取 Fabric 資料的客製化分析應用程式
• 整合開發者 為自訂應用程式與自動化工作流程建立資料存取層
• 偏好 GraphQL 靈活且型別安全的開發團隊，而非直接資料庫連接

當你需要建立一個新的 GraphQL API 來向應用程式揭露你的 Fabric 湖屋、倉庫或資料庫資料時，請使用本指南。

必要條件

要建立 GraphQL 的 API，你需要：

您的許可：

• 成為你想建立 API 的 Fabric 工作區成員
• 至少要在該工作區擁有 貢獻者角色 （或更高：管理員、成員）

組織架構：

• Fabric 管理員或容量管理員必須啟用「使用者可建立 Fabric 項目」 租戶設定

  

• 工作空間必須有 Fabric 容量（Premium、Trial 或 Fabric 容量）作為後盾

資料來源存取（後續步驟）：

• 您計畫透過 GraphQL API 曝露的資料來源的讀取權限
• 這些權限可以透過工作區成員資格或直接資料來源權限來授予
• 本指南中，我們以一個連結到鏡像資料庫的 AdventureWorks SQL 分析端點作為範例資料來源。 要取得 AdventureWorks 範例資料，請參閱 將您的 SQL 資料庫載入 AdventureWorks 範例資料。

建立 GraphQL 的 API

建立適用於 GraphQL 的 API：

1. 請前往 Fabric 入口 https://fabric.microsoft.com 網站，並以你的組織帳號登入。

2. 選擇一個你想建立 API 的工作區，然後選擇 新項目。 在開啟的面板中，於 [開發數據] 下，選取 [GraphQL API]。

   

3. 輸入你為 GraphQL 項目的新 API 名稱 ，然後選擇 「建立」。

你現在在 Fabric 裡有一個活躍的 GraphQL API 端點。 此時，你可以從 Fabric 入口複製端點 URL，選擇 產生程式碼 以取得程式碼範例，API 就可以開始接收請求了。 下一節，我們將連結資料來源來建立你的結構，但端點本身已經是可用的。

線上至資料來源並建置架構

此時 API 端點已經準備好，但尚未公開任何資料。 GraphQL 的 API 定義於以強型別系統中的類型和欄位來組織的架構中。 網狀架構會根據您選擇要公開給 GraphQL 用戶端的資料，自動產生必要的 GraphQL 架構。

要連接資料來源並建立你的結構架構：

1. 請確保你在工作區中選擇了新的 GraphQL API 項目。

2. 在 GraphQL 的 API 下新增資料時，選擇 選擇資料來源 圖塊。

   

3. 接下來，選取 API 的連線選項：

   

   您可以在這裏定義 API 用戶端如何存取 API，以根據兩個不同的選項執行 GraphQL 要求：

   • 單一登入（SSO）：你可以使用用戶端憑證連接資料來源。 經過認證的 API 使用者必須能存取資料來源中的底層資料表。

     例如，如果您要向 API 用戶端公開 Lakehouse 數據，則已驗證的使用者必須能夠存取 API 和 Lakehouse。 更具體來說， 執行 GraphQL API 的許可權（新增直接存取權限時執行查詢和突變 選項），以及所選數據源中所需的讀取或寫入許可權。 或者，使用者可以作為帶有 貢獻者角色 的工作區成員被加入其中，此工作區同時儲存 API 及資料來源項目，這樣就能從同一地點方便地存取這兩個項目。 如需詳細資訊，請參閱讓使用者存取工作區。

   • 儲存憑證：你可以利用儲存憑證連接資料來源。 已認證的 API 使用者不需要直接存取資料。 已儲存的認證會共用，以存取數據源中 API 與基礎表之間的數據。

     舉例來說，如果您要將 Lakehouse 資料提供給 API 用戶端，經過認證的使用者只需擁有直接存取 API 的權限（新增直接存取權限時，選擇執行查詢和變更 的選項），而不需要直接存取 Lakehouse。 已儲存的認證可用來將 API 連線至數據源，並由所有已驗證的 API 用戶共用。 如果您要透過 GraphQL 公開 Azure 數據源，例如 Azure SQL 資料庫，則需要此選項。

   一旦選擇，這些選項將強制執行於所有後來加入 API 的資料來源。 您無法在相同的 API 中混合單一登入和儲存的認證。 你可以使用使用者主體名稱（UPN）或服務主體名稱（SPN）來連接你的 API，根據你的安全需求，使用 SSO 或儲存的憑證。

   關於不同驗證情境的權限要求詳細說明，請參見 「認證與權限摘要」。

   注意

   GraphQL 的 API 需要用戶端應用程式使用 Microsoft Entra ID 進行驗證。 您必須註冊並設定用戶端應用程式，才能對 Fabric 執行 API 呼叫。 在 Microsoft Entra ID 中註冊的應用程式需要 Power BI 服務的 GraphQLApi.Execute.All API 許可權。 您可以在 Connect Applications 找到端對端教學課程，其中包含用戶主體和服務主體的指示和範例程序代碼。

4. 從 OneLake 目錄中選擇你想連接的資料來源。 選取 篩選只查看特定類型的 Fabric 資料來源，或依特定關鍵詞搜尋。 當您準備好時，選取設定。

   

   在這個例子中，我們選擇了一個連結到包含 AdventureWorks 範例資料的鏡像資料庫的 SQL 分析端點。

5. 如果你之前選擇 了已儲存的憑證 ，且你的 GraphQL API 沒有已儲存的憑證，系統會提示你建立新的已儲存憑證。

6. 「 選擇資料 」頁面會出現，你可以選擇想在 GraphQL 架構中顯示哪些物件。

7. 選取您要在 API 中公開的個別數據表、檢視或預存程式旁的複選框。 若要選取資料夾中的所有物件，請選取頂端具有資料來源名稱的複選框。

   

8. 選取載入以啟動 GraphQL 架構產生程式。

9. 架構已產生，您可以開始建立 GraphQL 查詢（讀取、清單）或突變（建立、更新、刪除）原型，以與您的資料互動。

   

   小提示

   在編輯器中輸入 Ctrl/Cmd + 空白鍵，就能獲得建議。

   欲了解更多使用 API 編輯器的資訊，請參閱 Fabric API for GraphQL 編輯器。

總結

就是這樣！ 你成功在 Fabric 中建立了 GraphQL API，連接你的資料來源，並產生了一個結構。 你的 API 現在已經準備好接受來自客戶端應用程式的連線和請求。 你可以使用 API 編輯器來測試和原型化 GraphQL 查詢，並 使用 Schema explorer 驗證 API 中暴露的資料型別和欄位。

相關內容

• GraphQL 編輯器的網狀架構 API
• GraphQL 架構檢視和架構總管的網狀架構 API