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。