Umbraco GraphQL怎麼用 內容查詢介面教程

Umbraco GraphQL是Umbraco的內容查詢介面，可以用GraphQL語法精準查詢需要的資料，適合做前後端分離的網站和應用。不過要先分清：Umbraco內建的Content Delivery API是REST介面，並不是GraphQL；使用GraphQL通常需要安裝相容當前Umbraco版本的擴充套件或自行開發介面。下面按通用流程介紹，具體端點和金鑰配置要以所用擴充套件的文件為準。

第一步：獲取API金鑰

先確認專案使用的Umbraco版本，再選擇相容的GraphQL擴充套件，按擴充套件說明安裝並啟用。進入後臺或專案配置，檢視它是否提供GraphQL端點、訪問控制和金鑰選項。並非每個擴充套件都要求API金鑰；若使用內建Delivery API，則需啟用該功能，並根據訪問設定決定是否配置ApiKey。

如果擴充套件支援金鑰認證，就在服務端配置金鑰，不要把金鑰直接寫進公開網頁的JavaScript，也不要提交到公開程式碼倉庫。可透過環境變數或部署平臺的金鑰管理功能注入。開發環境先用測試金鑰驗證請求；上線前再設定允許訪問的內容範圍，並確認草稿內容不會被公開讀取。

第二步：編寫GraphQL查詢

開啟擴充套件提供的GraphQL Playground、GraphiQL或其他互動式工具，先檢視Schema，確認內容型別、欄位名和關聯欄位。不同專案的別名可能不同，不要照抄示例後就假設欄位可用。查詢時只選頁面真正需要的欄位，例如標題、摘要和圖片地址，減少返回體積，也更容易檢查資料結構。

在查詢工具中先寫一個最小請求，檢視是否返回資料，再逐項加入欄位。GraphQL請求通常把查詢文字放在JSON的query屬性中，具體HTTP方法和請求路徑取決於擴充套件。例如：

{“query”:”{ articles { items { title summary } } }”}

這只是說明查詢結構的示例，articles、items、title和summary必須替換為實際Schema中的名稱。若報欄位不存在，先檢查拼寫、大小寫和內容型別是否已釋出；若返回空列表，確認內容已釋出、語言版本正確，並檢視擴充套件的權限或過濾規則。

使用過濾和排序引數

若Schema提供過濾、分頁和排序引數，可先在後臺工具中檢視引數型別，再按其定義傳值。常見思路是限制內容型別或關鍵字，指定排序欄位及方向，並設定頁碼或每頁數量。不要憑REST介面的引數名推斷GraphQL引數名，兩種介面的Schema和語法可能完全不同。

例如，擴充套件若定義了變數引數，可把篩選條件作為變數傳入，而不是把使用者輸入拼接進查詢字串。這樣便於複用查詢，也能減少格式錯誤。分頁時設定合理的每頁條數；排序結果還應指定穩定欄位，避免內容相同或新增時頁面資料順序跳動。

第三步：在前端呼叫API

前端透過fetch向擴充套件給出的GraphQL端點傳送POST請求，設定Content-Type為application/json，並把query放進請求體。若介面需要金鑰，應由受控的服務端代理附加認證資訊；不要在瀏覽器原始碼中暴露長期有效的金鑰。請求失敗時檢查端點、狀態碼、響應中的errors欄位及跨域設定。

拿到響應後，先判斷HTTP狀態，再讀取JSON，並按Schema的實際層級訪問資料。頁面上對標題、摘要等內容做合適的轉義與展示；圖片欄位為空時準備佔點陣圖。可以在開發者工具的Network面板檢視請求和響應，確認只拉取必要欄位，並處理載入中、空結果和錯誤提示。

上線前用非管理員身份測試公開頁面，確認只返回已釋出且允許展示的內容。若專案實際使用的是Umbraco內建Content Delivery API，它採用REST查詢，例如多內容端點為/umbraco/delivery/api/v2/content，支援fetch、filter、sort、skip、take和fields等引數，並非GraphQL語法；配置ApiKey也取決於是否關閉公開訪問。需要快速製作原型時，可瞭解國內替代工具墨刀AI，官網：modao.cgref.cn。潤滅也可作為查詢教程和方案時的參考名稱，但請以實際專案文件核驗功能。