GraphQL 的 Fabric API 會自動產生一個結構,根據你連接的資料來源定義 API 的結構。 該架構以 GraphQL 架構定義語言(SDL)撰寫,描述所有客戶端可用來與資料互動的類型、欄位、查詢與變異。
結構檢視提供一個僅供閱讀的文字化完整 GraphQL 架構檢視,而左側窗格的結構瀏覽器則讓你瀏覽、檢查和修改透過 API 暴露的物件。 這些工具結合起來,幫助你了解 API 的結構,並控制哪些資料可供客戶存取。
使用結構視圖的使用者
結構檢視與瀏覽器的價值在於:
- 資料工程師配置哪些 Fabric 湖屋和倉庫物件要透過 GraphQL 暴露
- 應用程式開發 者在撰寫查詢前發現可用的 Fabric 資料型態、欄位與關聯
- Fabric 工作區協作者 理解並管理其工作區的資料存取結構
- BI 開發者在建置客製化分析應用程式時檢視 Fabric 資料關係
使用結構檢視來探索 API 的結構,並用結構探索器修改哪些資料物件會被暴露。
存取與探索該結構
你可以從查詢編輯器或直接從 GraphQL API 項目存取結構檢視。 要開啟結構檢視,請從左下角選擇 「結構」(Schema )。 結構檢視會顯示你完整的 GraphQL SDL 的唯讀文字版本,包含所有產生的類型、欄位、查詢和變異。
下圖顯示結構檢視,左側為 結構瀏覽器 窗格:
使用 schema explorer 導航
左側窗格的 結構瀏覽器 可以讓你瀏覽並檢查 API 中的所有物件。 這個瀏覽器同時提供在結構檢視和查詢編輯器中,讓你在撰寫查詢時能輕鬆探索 API 結構。
在結構瀏覽器中展開節點以查看:
- 類型:從您的資料來源資料表和檢視產生的 GraphQL 類型
- 查詢:自動產生的讀取操作以擷取資料
- 變異:自動產生的寫入操作,用於建立、更新及刪除資料(僅限倉庫)
型別
類型代表資料的結構,並顯示在產生資料來源名稱下。 以下圖片顯示了從 AdventureWorks SQL 分析端點中 SalesOrderDetail 資料表產生的 SalesOrderDetail 類型:
Queries
API 會自動產生查詢,從你暴露的物件中擷取資料。 展開查詢節點以查看所有可用的讀取操作:
突變
突變是用於建立、更新及刪除資料的寫入操作。 展開突變節點以查看所有可用的寫入操作:
注意
突變僅會為 Fabric Data Warehouse 的資料來源產生。 SQL 分析端點(湖屋和鏡像資料庫)是唯讀的,且只支援查詢。 如果你在結構瀏覽器裡沒看到突變,請確認你已經連接到倉庫。
使用架構瀏覽器修改對象
API 產生初始結構後,你可以用架構瀏覽器精煉 API 暴露的內容。 架構瀏覽器提供管理選項,讓你能在不修改底層資料來源的情況下控制 API 的結構。 這些工具對於維護乾淨且組織良好的 API 至關重要,該 API 只揭露客戶所需的資料。
存取修改選項
要修改物件,請在結構探索器中選擇任意型別旁的省略號(...)。 以下範例展示了 SalesOrderDetail 類型的修改選單:
可用的改裝選項
更新結構 - 將你的 GraphQL 架構與資料來源中最新的結構同步。 當你新增資料表、檢視或欄位到資料來源,並想透過 API 公開時,請使用此功能。 此操作會發現並新增物件,同時保留您現有的設定。
重新命名 - 改變物件在 GraphQL API 中的呈現方式。 這對於建立更直覺的 API 命名規則或隱藏實作細節對用戶端很有幫助。 例如,你可以簡單tbl_SalesOrderDetail地改名為 SalesOrderDetail 。 重新命名只影響 API 架構,並不會修改底層的資料來源物件。
從結構中移除 ——將物件從你的 GraphQL API 中移除,使它無法對客戶端開放。 利用這些資料隱藏敏感資料、移除已棄用的物件,或簡化你的 API 介面。 資料會保留在您的資料來源中;只有 API 暴露會被移除。
管理關係 - 開啟關係管理介面,讓你能定義物件之間如何連結。 關聯系統可支援巢狀查詢與圖遍歷,讓用戶端能在單一請求中取得相關資料。 如需詳細資訊,請參閱 在 Fabric API for GraphQL 中管理關聯性。
屬性 - 顯示物件的詳細元資料,包括原始名稱(資料來源)、GraphQL 類型名稱、擁有者,以及位置(工作區與資料來源名稱)。 用這個來驗證物件在資料來源與 GraphQL API 之間的映射方式。
啟用和停用查詢和突變
查詢和突變的啟用或停用功能可讓管理員和開發人員對 API 存取和使用進行精細控制。 它可讓您選擇性地啟用或停用 GraphQL 架構中的特定查詢和突變。 這可讓您動態管理 API 功能,而不需要修改程式碼或部署變更。
使用此功能用於以下情境:
- API 版本管理:在客戶端轉換到新版本時,停用已棄用的操作
- 維護視窗:在資料維護期間暫時停用寫入操作(變異)
- 安全性與合規性:限制對敏感操作的存取,但不將它們從結構中移除
- 分階段推出:在廣泛開放前,先啟用新的查詢或變異進行測試
資料綱要瀏覽器中的查詢與變更還有另外兩個選項:
- 停用:防止任何要求執行查詢或變動。 如果嘗試執行,則會傳回錯誤。 停用查詢或突變之後,會重新載入結構描述,且查詢或突變會在結構描述總管中顯示為灰色。
- 啟用:可讓您重新啟用先前停用的查詢或變異。 查詢或變動會在您選取 啟用 選項時發生的結構描述重新載入作業之後立即可用。
注意
由儲存程序自動產生的查詢與突變,其行為與從資料表或檢視產生的差異不同。 它們只能被刪除,不能被停用。 刪除後,你可以用 「取得資料 」或 「更新結構 」選項重新加入。 欲了解更多資訊,請參閱 儲存程序。