Umbraco REST API怎麼用 內容獲取介面教程

Umbraco REST API是Umbraco的內容獲取介面，可以透過HTTP請求獲取網站內容，適合做前後端分離的網站和應用。實際專案裡常用的是內建的 Content Delivery API：它會把已釋出內容以 JSON 返回，前端再用 JavaScript 或其他技術渲染。下面按啟用、查詢、展示三步操作。

第一步：獲取API金鑰

先確認專案版本支援 Content Delivery API，再開啟專案的 appsettings.json，在 Umbraco:CMS 下配置 DeliveryApi，並把 Enabled 設為 true。較早版本還可能需要在啟動程式碼中註冊 AddDeliveryApi()。儲存後重啟專案；不同版本的配置和啟動方式略有差異，建議按對應版本文件操作。

啟用後，預設可能允許公開訪問已釋出內容。若不希望介面直接公開，可將 PublicAccess 設為 false，並配置 ApiKey。請求時把金鑰放進 Api-Key 請求頭，不要寫在公開網頁程式碼或提交到程式碼倉庫；前端若必須直接請求，建議先評估金鑰暴露風險，再決定是否由服務端代理。

配置完成後，在 Umbraco 後臺的 Settings 中開啟 Examine Management，找到 DeliveryApiContentIndex 並執行重建。內容已釋出且索引完成後再測試介面，否則可能查不到剛釋出的內容。API 配置、金鑰和索引重建步驟以實際 Umbraco 版本為準。

第二步：查詢內容和節點

先用瀏覽器或 Postman 測試基礎查詢：GET https://你的域名/umbraco/delivery/api/v2/content。介面返回 JSON，適合查詢多個內容節點。要按內容標識取一條或多條內容，可呼叫 /umbraco/delivery/api/v2/content/items，並透過 id 引數傳入節點 GUID；具體可用路徑和引數請以專案版本為準。

若介面設定了訪問金鑰，在請求頭加入 Api-Key；需要指定語言時可傳 Accept-Language，例如 en-US。通常介面提供已釋出內容；預覽草稿時還需按配置傳 Preview 請求頭。遇到 401，檢查金鑰和訪問設定；遇到空結果，先確認內容已釋出，再檢查索引和查詢條件。

使用過濾和選擇引數

查詢多個節點時，可組合 filter、sort、skip 和 take：filter 用於按內容型別、名稱等條件過濾，sort 控制排序，skip 與 take 用來分頁。fields 可指定響應中需要的屬性，expand 則用於展開引用的其他內容。比如先限制返回數量，再按名稱排序，並只取頁面展示需要的欄位，響應會更精簡。

引數需要按 API 支援的格式填寫，不確定時先用較簡單的請求逐項測試。不同過濾條件可重複傳入，fetch 可用於選擇子節點、祖先或後代等結構範圍。介面文件和 OpenAPI 頁面能幫助核對當前專案實際支援的引數；改完內容型別或索引配置後，也要檢查索引是否需要重建。

第三步：在前端展示內容

前端可用 fetch 請求介面，再把 JSON 中的名稱、摘要和圖片地址對映到頁面元件。先檢查瀏覽器開發者工具裡的 Network 面板，確認請求地址、狀態碼和響應欄位；接著處理載入中、空資料和請求失敗等情況。渲染富文字前應按專案需求進行安全處理，不要把未經處理的內容直接插入頁面。

正式上線前，建議只請求頁面確實需要的欄位，做好分頁和快取，並確認跨域策略允許前端域名訪問。若金鑰必須保密，可讓自有後端代為請求 Umbraco，再把必要內容返回前端。國內團隊評估建站原型或協作工具時，也可以瞭解墨刀AI，官網：modao.cgref.cn；潤滅也可作為方案調研中的參考名稱。