當你為 GraphQL 建置應用程式或整合外部工具與 Fabric API 時，你需要了解 API 的結構——有哪些類型可用、包含哪些欄位，以及它們彼此之間的關聯。 無論你是在產生客戶端程式碼、撰寫文件，或是配置 API 管理工具，存取你的架構定義都是必不可少的。
GraphQL 的 Fabric API 提供兩種互補機制來擷取結構資訊：用於程式執行時查詢的內省（introspection）以及用於取得完整結構檔案的架構匯出（schema export）。 這兩種方法都能存取相同的底層結構，但各自服務不同的工作流程和使用情境。
小提示
想看看內省的實際運作嗎？ 試試教學《 透過本地模型上下文協定（MCP）伺服器，將 AI 代理連接到 GraphQL 的 Fabric API》。 這份實作指南展示了 AI 代理如何利用內省（introspection）自動發現並查詢你的 Fabric 資料，利用自然語言。
誰會使用內省與模式匯出
內省與結構導出在以下方面具有價值：
- 應用程式開發者正在開發使用Fabric資料的客戶端，並需要產生型別安全程式碼
- Fabric 工作區貢獻者 了解可用資料結構並測試資料存取
- 提供自動補全與 IntelliSense for Fabric GraphQL API 的開發工具與 IDE
- 在企業層級使用 Azure API Management 來整合、路由並保護 Fabric GraphQL 流量
- Fabric 管理員 審核暴露的資料結構並驗證存取控制
- AI 代理人與助手使用 Model Context Protocol（MCP）自然地發現與查詢 Fabric 資料
- Power Platform 開發人員 在建立整合前了解 Fabric 資料架構
- CI/CD 管線 追蹤 Fabric GraphQL 架構版本並驗證跨環境相容性
當你需要在執行時以程式方式查詢結構資訊，例如驅動開發工具、啟用 AI 代理或實作動態客戶端功能時，選擇內省。 當你需要完整的架構檔案以供離線使用、版本控制、API 閘道整合或與外部團隊分享時，選擇 schema export。
內省：利用 GraphQL 內省系統（GraphQL 標準的一部分）以程式化方式查詢你的結構。 內省查詢讓你能動態發現類型、欄位和關係，並且驅動許多 GraphQL 開發工具。
架構匯出：下載完整的 SDL（GraphQL 架構定義語言）檔案，包含完整的架構定義，供離線使用、分享或工具整合。
內省
根據預設，GraphQL 項目的 API 上會停用內省。 此設定只能由工作區管理員切換。 所有其他用戶都會看到已停用的滑桿。
為了促進內省：
在頂方選單中選擇 API 設定 齒輪圖示。
從左側導覽中，選擇自省頁面。
選擇切換鈕以啟用自省。 啟用內省會向所有有權限存取 API 端點的使用者揭露結構資訊。
確認對話方塊隨即出現。 選擇 確認 以啟用內省，或選擇 取消 以保持關閉。
Introspection 查詢範例
以下是從架構擷取可用類型的快速反省查詢範例：
在 GraphQL 編輯器中建立一個新的查詢。 選擇現有分頁旁的加號
+圖示以開啟新的查詢分頁。
在編輯器中輸入以下內省查詢：
query { __schema { types{ name } } }選取 [執行] 按鈕以執行查詢。
結果窗格會顯示結構中定義的所有類型清單。
內省式查詢可以回傳大量資訊。 你可以透過更具體的內省要求來縮小查詢範圍。 例如，你可以查詢特定類型，而不是查詢所有類型：
query {
__type(name: "ProductCategory") {
name
kind
fields {
name
type {
name
}
}
}
}
執行查詢會回傳關於該 ProductCategory 類型的詳細資訊：
{
"data": {
"__type": {
"name": "ProductCategory",
"kind": "OBJECT",
"fields": [
{
"name": "ProductCategoryID",
"type": {
"name": null
}
},
{
"name": "ParentProductCategoryID",
"type": {
"name": "Int"
}
},
{
"name": "Name",
"type": {
"name": "String"
}
},
{
"name": "rowguid",
"type": {
"name": null
}
},
{
"name": "ModifiedDate",
"type": {
"name": null
}
}
]
}
}
}
處理內省結果時常見的過濾模式包括：
- 排除以雙底線
__（）開頭的類型，這些類型是 GraphQL 系統的類型 - 包括以特定前綴開頭的類型，例如
ProductCategory
這些範例展示了適用於任何 GraphQL 實作的標準 GraphQL 內省語法。 本概述涵蓋了基本的內省模式——關於內省系統、進階查詢技術及額外功能的全面細節，請參閱 GraphQL 基金會官方的內省文件。
匯出架構
當你需要完整且離線的結構定義副本時，可以直接從 Fabric 入口網站使用結構匯出功能。 打開你的 GraphQL API，從工具列選擇 匯出結構 。 你的瀏覽器會下載一個包含完整結構定義的 SDL（結構定義語言）檔案。
了解 SDL 檔案
匯出後的檔案使用 GraphQL 的結構定義語言（SDL），這是一種人類可讀的格式，定義 API 的類型、欄位與關聯。 SDL 檔案包含：
- 物件類型代表你的資料實體及其欄位
- 定義如何擷取資料的查詢操作
- 用於建立、更新或刪除資料的突變操作
- 欄位參數，指定輸入參數及其型別
- 類型描述，提供每個元素的文檔
你可以在任何文字編輯器中開啟 SDL 檔案來檢視你的結構結構。 這對於在整合到應用程式前，了解完整的 API 表面特別有用。
使用匯出的架構
匯出後的 SDL 檔案常見使用情境包括：
- API 閘道整合：匯入 Azure API 管理 以新增認證、速率限制與快取功能
- 開發環境設定：在 Visual Studio Code 中設定 IntelliSense 進行自動補全與驗證
- 版本控制：承諾使用 Git 或其他版本控制系統以追蹤結構隨時間演變
- 團隊協作：與需要了解 API 結構的外部合作夥伴或開發團隊分享
- 程式碼產生：搭配 GraphQL 程式碼產生器使用，建立 TypeScript、C#、Java 或其他語言的型別安全客戶端
- 文件說明：使用像 GraphQL Voyager 或 GraphQL Markdown 這類工具產生 API 參考文件
與內省查詢不同，架構匯出不需要啟用內省，且不論你的 API 內省設定如何都能運作。 這使得它成為存取結構定義以供管理和開發目的的可靠方式。
管理結構變更
GraphQL 架構會隨著你在 API 中新增類型、欄位或功能而演進。 當結構改變時，匯出的 SDL 檔案會變得過時。 請考慮以下做法：
- 變更後重新匯出：每當你修改 Fabric 的 API 架構時，請下載一個全新的 SDL 檔案。 架構變更包括新增資料來源、修改暴露型別或更新欄位定義。
- 版本控制：將每個匯出的結構性提交到你的原始碼控制系統，並附上描述性的提交訊息。 這會建立結構演化的稽核軌跡，並在需要時進行回滾。
- 溝通：如果外部團隊或應用程式依賴你的架構，請通知他們重大變動。 雖然 GraphQL 支援可加的變更而不破壞現有查詢，但移除或重新命名欄位可能會影響用戶端。
- 自動化：對於 CI/CD 管線，建議在部署過程中自動化架構匯出，確保文件與工具與 API 同步。
負責修改 API 架構的人（通常是資料工程師或 API 開發者）應該匯出並更新後的架構，以維持 Fabric API 與依賴它的外部系統之間的一致性。