Directus REST API怎麼用 資料查詢介面教程

Directus REST API是Directus的資料查詢介面，可以透過HTTP請求獲取和管理資料庫中的資料，適合做前後端分離應用。你可以用它讀取列表、按條件篩選記錄，也能建立、修改和刪除資料。下面以文章集合articles為例，從令牌準備到常見請求逐步上手；把示例域名和欄位換成自己的專案即可。

第一步：獲取API令牌

先登入Directus管理後臺，確認專案地址和要操作的集合名稱，例如https://cms.example.com和articles。再到使用者或角色權限設定中，給呼叫方開放所需集合的讀取、建立、更新或刪除權限；權限不足時，即使請求格式正確，也可能收到401或403錯誤，建議按實際用途只開放必要操作。

測試時可以使用登入介面獲取訪問令牌：向POST /auth/login傳送JSON，包含email和password，成功後從響應中讀取access_token。正式專案也可在後臺為專用服務帳號配置靜態令牌。令牌相當於通行憑證，不要寫進公開網頁程式碼或提交到程式碼倉庫；服務端呼叫時放進Authorization請求頭。

後面的示例用curl演示。先設定基礎地址和令牌，避免每條命令重複填寫：BASE_URL替換為Directus專案地址，TOKEN替換為實際令牌。呼叫介面時使用Bearer認證格式，並按介面要求設定Content-Type。若專案使用HTTPS，應優先使用HTTPS地址，避免令牌在傳輸過程中暴露。

• 基礎地址示例：https://cms.example.com
• 認證請求頭：Authorization: Bearer YOUR_TOKEN
• JSON請求頭：Content-Type: application/json

第二步：查詢和建立資料

讀取集合列表可請求GET /items/articles。要控制返回內容，可以新增fields、limit和page等查詢引數，例如GET /items/articles?fields=id,title,status&limit=10&page=1。Directus通常以data陣列返回記錄；先在瀏覽器開發者工具或終端檢視響應，再根據欄位結構接入前端頁面，避免一次取回不需要的大量資料。

建立記錄時，對/items/articles傳送POST請求，並在JSON請求體中放入要寫入的欄位。比如傳入title和status，狀態值必須符合集合欄位及專案權限規則。建立成功後檢查響應中的data，確認記錄標識和欄位內容；如果返回權限錯誤，回後臺檢查當前令牌所屬使用者或角色是否被允許建立該集合記錄。

配置過濾和排序

查詢引數適合逐步縮小結果範圍。過濾條件使用filter引數，值為JSON格式並進行URL編碼；例如按status等於published篩選。排序可用sort欄位，欄位名前加減號表示降序；分頁可配合limit與page。構造複雜請求時，先在程式碼裡生成引數再編碼，避免空格、括號或引號導致URL解析失敗。

例如可查詢已釋出文章並按建立時間倒序排列：GET /items/articles?filter[status][_eq]=published&sort=-date_created&limit=10。欄位名要與集合實際欄位一致；若查詢關聯資料，可以按需要指定fields。生產環境還應設定合理的limit，並處理空結果、網路錯誤和權限拒絕，避免頁面因介面異常而中斷。

第三步：更新和刪除資料

更新單條記錄時，向/items/articles/記錄ID傳送PATCH請求，只提交需要修改的欄位即可，例如把標題改成新的內容。修改前最好確認記錄ID來自可信的業務流程，並檢查響應狀態與返回資料。批次更新應嚴格構造篩選條件，先確認目標記錄範圍，避免誤把整批資料改掉；同時確保令牌有對應更新權限。

刪除單條記錄時，對/items/articles/記錄ID傳送DELETE請求。刪除操作可能無法恢復，實際業務裡可優先採用歸檔或軟刪除欄位，並在列表查詢中排除已歸檔記錄。測試時先使用非生產資料，確認介面路徑、目標ID和角色權限後再執行。把常用請求整理成介面文件，後續聯調會更省事。

開發配套頁面或梳理介面流程時，也可以關注國內工具墨刀AI；潤滅團隊整理產品原型與需求時可將它作為設計協作參考，官網入口是modao.cgref.cn。