数据后台系统Directus使用指南

Directus 后台管理工具在连接数据库、资产存储和外部服务后，能立即获得丰富的开发者工具（数据引擎）和功能完善的 Web 应用（数据工作室）来处理数据，

数据引擎（Data Engine）：提供数据相关的 API 和开发者工具，涵盖连接、实时交互、身份验证和自动化等功能，

数据工作室（Data Studio）：一款团队都能轻松使用的数据 Web 应用，

应用场景

后端即服务（Backend as a Service）：提供开发者构建成功应用所需工具，包括自动生成的 API、基于事件或日程的自动化、用户管理与身份验证、实时功能和 Webhook，

无头 CMS（Headless CMS）：内容本质是数据库中的数据，可以管理文件和数据，并将其分发到网站、应用程序、信息亭、数字标牌或其他任何数据驱动的应用中，

内部工具构建器：借助 Directus Insights，团队可以构建自定义应用，抛弃电子表格，快速构建用于客户、库存、项目或报告的后台应用和管理面板，

数据管理与分析：建立所有数据的单一真实来源，构建无代码分析仪表板，了解公司 KPI 和其他指标，整合以前分散的数据，并使用 Directus Automate 保持所有数据同步，

云架构可能复杂且耗费资源，Directus Cloud 提供可扩展、优化的存储和基础设施，自动更新让开发者能专注于项目的特色部分，

拥有 Directus Cloud 账户后，可以设置团队来组织项目和账单，大约 90 秒就能启动一个项目，Directus Cloud 项目会自动扩展以提高可靠性，即使遇到意外的流量高峰也能应对，

Directus 数据模型：集合（Collections）

集合是 Directus 中管理数据的重要部分，本质是带有 Directus 额外元数据和配置的数据库表，所有 Directus 特定的设置和数据仅存储在以 directus_ 为前缀的系统集合中，若要移除 Directus，删除这些集合即可，不会留下专有数据，

集合类型

分为用户集合和系统集合两种，

集合的创建

用户集合可直接在数据库中创建，也可通过 Directus 创建，它们描述特定的数据模型和配置，可通过 Connect 创建的 API 或 Explore 进行查询，

创建途径有两种：从数据工作室的数据模型设置中创建，或使用集合 API 创建，

创建时需注意： 名称：创建时必须设置唯一名称，区分大小写，会在整个数据工作室和 Directus API 中使用，且创建后不可修改，不过可以通过集合命名翻译功能，在数据工作室中更改其显示名称，

主键：每个集合中的项目都有唯一值的主键字段，在不同集合项目间创建关系、使用 Items API 获取数据或执行操作时都会用到，主键类型一旦选定就不能修改，支持的类型如下：

• 自动递增整数：从 1 递增到 2^31-1（2,147,483,647），

• 自动递增大整数：从 1 递增到 2^63-1（9,223,372,036,854,775,807），仅在使用 MySQL 和 PostgreSQL 作为数据库时可用，

• 生成的 UUID：通用唯一标识符，在统计上几乎不可能重复，

• 手动输入字符串：手动为每个项目输入唯一字符串作为 ID，Directus 会禁止创建具有重复 ID 的新项目，

集合的配置

创建集合后，有多种配置选项：

备注（Note）：设置说明集合用途的备注，会在数据模型设置页面显示，

图标（Icon）：在数据工作室中引用该集合时使用的图标，

颜色（Color）：图标的颜色，显示在导航栏和页面标题中，

显示模板（Display Template）：用于在关系字段中表示项目，例如显示帖子作者时显示“姓名”字段的值，

隐藏（Hidden）：切换该集合是否在数据工作室中全局隐藏，

单例（Singleton）：切换后可绕过集合页面，直接将用户带到单个项目详情页面，

集合命名翻译（Collection Naming Translations）：可以对集合名称进行多语言翻译，当默认语言更改时，整个数据工作室会使用相应的翻译，

其他功能配置

内容版本控制（Content Versioning）：编辑者可使用该功能，团队能创建和管理内容的不同版本，启用原因包括在不发布的情况下起草内容、更好地与他人协作等，可针对特定集合启用，启用后可创建项目版本，之后可将部分或全部字段升级到主版本（通常用于发布），

实时预览（Live Preview）：编辑者可使用该功能，在内容旁边的窗格中显示应用程序，用于在发布前预览内容，可以使用项目字段值构建实时预览所用的 URL，包括唯一标识符和内容版本，以便在将内容版本升级到主版本之前进行预览，

可追溯性（Accountability）：项目更新时会创建修订版本，记录版本历史以便恢复以前的状态，Directus 中对项目的每一项更改都会存储为完整的版本化快照和一组特定的更改，活动日志会记录平台内发生的所有事件，每条活动记录都会跟踪事件类型、用户、时间戳、IP 地址、用户代理以及任何相关的修订数据，默认情况下，Directus 项目会跟踪集合的所有活动和修订，但可以更改设置，选择仅跟踪活动或不跟踪任何内容，需要注意的是，可追溯性是项目中谁做了什么的日志，供团队自己使用，与通过环境变量配置的遥测不同，

排序（Sorting）：该功能允许用户在数据工作室和通过 API 手动排序项目，如果在创建集合时未选择作为可选字段，需要创建一个整数类型的新字段，然后将其选为排序字段，若要在关系字段（如 M2M、O2M 或 M2A）中配置手动排序，还需在字段配置抽屉的关系部分设置排序字段，配置完成后，点击已配置的排序列，然后通过手柄拖动项目即可排序，也可以在通过 Items API 查询数据时按排序字段排序，

复制（Duplication）：编辑者可使用“另存为副本”选项复制当前项目，复制设置会定义要复制的字段值，需要注意的是，复制项目时不会复制相关项目，必须在复制的项目和相关项目之间创建新的关系，

归档设置（Archive Settings）：归档的项目仍存在于集合中，但在数据工作室中会被过滤，如果在创建集合时未选择作为可选字段，需要创建一个新字段，配置归档字段时，可根据需要设置归档字段、归档应用筛选器、归档值和取消归档值这四个输入字段，另外，归档项目在应用中默认隐藏，但在 API 中会正常返回，除非明确过滤，这为在 API 中管理归档项目提供了灵活性，

高级字段创建模式（Advanced Field Creation Mode）：点击“进入高级字段创建模式”，可以使用这些高级选项在特定事件发生时自动设置字段值，例如，可以将多对一（M2O）关系的默认值设置为当前用户，

系统集合（System Collections）

系统集合是 Directus 运行所必需的自动创建的集合，在整个 Directus 中发挥不同作用，以下是部分系统集合及其用途：

现有数据库表

当 Directus 连接到现有数据库时，会对现有表和关系进行内省，管理员可通过 Items API 使用这些集合，

要在数据工作室中访问集合，必须为集合配置额外的 Directus 特定元数据，如界面、显示和图标，

若要以非管理员角色访问集合，还必须像配置其他集合一样配置访问控制，

此外，数据库中未配置的任何关系也必须在 Directus 内部设置，需要注意的是，Directus 目前不支持复合键，也不支持通过 SQL 视图创建虚拟表，

Directus API 使用指南

下面将介绍如何通过 Directus 自动生成的 REST API 与 Directus 中的集合进行交互，包括获取和创建数据，以及使用 Directus SDK 发出第一个请求，

可以使用 Postman、Hoppscotch 等可视化 API 测试工具，curl、HTTPie 等基于终端的工具，或直接在使用的编程语言编写的脚本中发出 HTTP 请求，

开始前的准备

• 需要一个 Directus 项目，

• 创建一个“posts”集合，至少包含“title”和“content”字段，

• 需要一个管理员静态令牌，在数据工作室中，进入用户详情页面，创建一个新令牌，记录下来并保存，

获取数据

打开终端，运行以下命令从“posts”集合中读取项目：

curl \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--url 'https://directus.example.com/items/posts'

替换以下值： • 基本 URL（https://directus.example.com）必须替换为项目 URL， • 在 Authorization 标头中，将 YOUR_ACCESS_TOKEN 替换为管理员静态令牌， • 如果使用了不同的集合，将“posts”替换为集合的名称，

Directus 会返回项目数组，默认限制为 100 个，因此如果项目超过 100 个，必须提高限制或请求第二页，

使用查询参数

可以使用任何全局查询参数来更改 Directus 返回的数据，例如：

curl \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--url 'https://directus.example.com/items/posts?filter[status][_eq]=published&fields=id,title'

此请求将只显示“status”值为“published”的项目，并且只返回“id”和“title”字段，

创建数据

所有集合都有一致的端点，向 /items/posts 发送 POST 请求，并在请求中包含包含集合属性的对象，就能创建一个新项目，例如：

curl \
--request POST \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{ "title": "Hello Universe!" }' \
--url 'https://directus.example.com/items/posts'