文档服务 API
🌐 Document Service API
Page summary:文档服务 API 是与内容交互的推荐后端 API，提供
findOne、findMany、create、update和delete方法，这些方法可与稳定的documentId标识符一起使用，并支持草稿与发布操作。🌐 The Document Service API is the recommended backend API for interacting with content, providing
findOne,findMany,create,update, anddeletemethods that work with stabledocumentIdidentifiers and support Draft & Publish operations.
文档服务 API 建立在 查询引擎 API 之上 并用于对 文档 执行 CRUD（创建、检索、更新 和 删除）操作 。
文档服务 API 还支持计数文档，并且如果内容类型启用了草稿与发布，可以执行 Strapi 特定操作，例如发布、取消发布以及丢弃草稿。
🌐 The Document Service API also supports counting documents and, if Draft & Publish is enabled on the content-type, performing Strapi-specific operations such as publishing, unpublishing, and discarding drafts.
在 Strapi 5 中，文档在 API 级别上通过它们的 documentId 唯一标识。
🌐 In Strapi 5, documents are uniquely identified by their documentId at the API level.
文档服务 API 取代了 Strapi v4 (see Strapi v4 documentation) 中使用的实体服务 API。
有关如何从实体服务 API 迁移到文档服务 API 的更多信息，请参阅 迁移参考。
🌐 Additional information on how to migrate from the Entity Service API to the Document Service API can be found in the migration reference.
关系也可以通过文档服务 API 进行连接、断开和设置，就像使用 REST API 一样（示例见 REST API 关系文档）。
🌐 Relations can also be connected, disconnected, and set through the Document Service API, just like with the REST API (see the REST API relations documentation for examples).
文档服务是一个数据访问层：它与数据库交互，并且不知道用户权限或字段可见性。结果可能包含私有字段、密码和受限制的关系。
🌐 The Document Service is a data-access layer: it interacts with the database and is not aware of user permissions or field visibility. Results may include private fields, passwords, and restricted relations.
内置的 REST 和 GraphQL API 会在将响应发送给客户端之前自动进行清理。但是，如果你构建自定义控制器或插件路由并直接调用文档服务方法，你必须在返回输出之前自己进行清理。在你的控制器中使用 strapi.contentAPI.sanitize.output()（详情和代码示例请参阅 构建自定义控制器时的清理和验证）。
🌐 The built-in REST and GraphQL APIs automatically sanitize responses before sending them to the client. But if you build custom controllers or plugin routes that call Document Service methods directly, you must sanitize the output yourself before returning it. Use strapi.contentAPI.sanitize.output() in your controller (see Sanitization and validation when building custom controllers for details and code examples).
配置
🌐 Configuration
documents.strictParams 选项启用对传递给 Document Service 方法（如 findMany 和 findOne）的参数的严格验证。可以在 API 配置 文件（./config/api.js 或 ./config/api.ts）中进行配置。有关 documents.strictParams 的详细信息，请参阅 API 配置 表。
🌐 The documents.strictParams option enables strict validation of parameters passed to Document Service methods such as findMany and findOne. Configure it in the API configuration file (./config/api.js or ./config/api.ts). See the API configuration table for details on documents.strictParams.
文档对象
🌐 Document objects
文档方法返回一个文档对象或文档对象列表，这些对象表示在稳定的 documentId 下分组的内容条目的一个版本。返回的对象通常包括：
🌐 Document methods return a document object or a list of document objects, which represent a version of a content entry grouped under a stable documentId. Returned objects typically include:
documentId：跨语言环境和草稿/已发布版本的条目持久标识符。id：特定语言环境/版本记录的数据库标识符。- 模型字段：内容类型架构中定义的所有字段。关系、组件和动态区域不会被填充，除非你选择使用
populate（参见 填充字段）或使用fields限制字段（参见 选择字段）。 - 元数据：
publishedAt、createdAt、updatedAt，以及在可用时的createdBy/updatedBy。
可选地，如果为内容类型启用了 Draft & Publish 和 Internationalization，文档对象也可以包含 status 和 locale 属性。
🌐 Optionally, document objects can also include a status and locale property if Draft & Publish and Internationalization are enabled for the content-type.
方法概述
🌐 Method overview
以下各节分别介绍 特定方法的参数和示例：
🌐 Each section below documents the parameters and examples for a specific method:
| 方法 | 目的 |
|---|---|
findOne() | 通过 documentId 获取文档，可选择限定到特定语言或状态。 |
findFirst() | 返回第一个匹配过滤条件的文档。 |
findMany() | 列出符合过滤条件的文档，并支持排序和分页。 |
create() | 创建文档，可选择针对特定语言。 |
update() | 通过 documentId 更新文档。 |
delete() | 删除文档或特定语言版本。 |
deleteMany() | 删除符合过滤条件和关系参数的多个文档。 |
publish() | 发布文档的草稿版本。 |
unpublish() | 将已发布的文档移回草稿状态。 |
discardDraft() | 删除草稿数据，仅保留已发布版本。 |
count() | 统计有多少文档符合参数条件。 |
publish()、unpublish() 和 discardDraft() 方法仅在内容类型启用了“草稿与发布”功能时可用。在未启用“草 稿与发布”的内容类型上调用这些方法将会抛出错误。要启用“草稿与发布”，请参阅 草稿与发布文档。
🌐 The publish(), unpublish(), and discardDraft() methods are only available when the Draft & Publish feature is enabled on the content-type. Calling these methods on a content-type that does not have Draft & Publish enabled will throw an error. To enable Draft & Publish, see the Draft & Publish documentation.
findOne()
语法：findOne(parameters: Params) => Document
🌐 Syntax: findOne(parameters: Params) => Document
strapi.documents().findOne()findOne()
查找与传入的 documentId 和参数匹配的文档。如果仅传入 documentId 而没有其他参数，findOne() 将返回默认语言环境下文档的草稿版本。如果找到匹配的文档，则返回该文档，否则返回 null。
published or draft. Default: draft. See status docs.status. See publicationFilter docs.findFirst()
语法：findFirst(parameters: Params) => Document
🌐 Syntax: findFirst(parameters: Params) => Document
strapi.documents().findFirst()findFirst()
查找与参数匹配的第一个文档。默认情况下，findFirst() 返回传入唯一标识符（集合类型 ID 或单类型 ID）的第一个文档的草稿版本，使用默认语言环境。
published or draft. Default: draft. See status docs.status. See publicationFilter docs.如果未传入 locale 或 status 参数，结果将返回默认语言环境的草稿版本。
🌐 If no locale or status parameters are passed, results return the draft version for the default locale.
findMany()
语法：findMany(parameters: Params) => Document[]
🌐 Syntax: findMany(parameters: Params) => Document[]
strapi.documents().findMany()findMany()
查找与参数匹配的文档。当未传递参数时，findMany() 会返回每个文档在默认语言环境下的草稿版本。
published or draft. Default: draft. See status docs.status. See publicationFilter docs.create()
语法：create(parameters: Params) => Document
🌐 Syntax: create(parameters: Params) => Document
strapi.documents().create()create()
创建一个新文档。如果没有传递 locale 参数，create() 会为默认语言环境创建文档的草稿版本。
published to automatically publish the draft version of a document while creating it. See status docs.如果在内容类型上启用了草稿与发布功能，你可以在创建文档的同时自动发布它（参见status 文档`）。
🌐 If the Draft & Publish feature is enabled on the content-type, you can automatically publish a document while creating it (see status documentation).
update()
语法：update(parameters: Params) => Promise<Document>
🌐 Syntax: update(parameters: Params) => Promise<Document>
strapi.documents().update()update()
通过 documentId 更新文档。如果未传递 locale 参数，update() 将更新默认语言环境的文档。
published to automatically publish the draft version of a document while updating it. See status docs.已发布的版本是只读的，因此你不能从技术上更新文档的已发布版本。 要更新文档并立即发布新版本，你可以：
🌐 Published versions are read-only, so you can not technically update the published version of a document. To update a document and publish the new version right away, you can:
不建议使用文档服务 API 更新可重复组件（更多详情请参见相关的重大更改条目）。
🌐 It's not recommended to update repeatable components with the Document Service API (see the related breaking change entry for more details).
delete()
语法：delete(parameters: Params): Promise<{ documentId: ID, entries: Number }>
🌐 Syntax: delete(parameters: Params): Promise<{ documentId: ID, entries: Number }>
strapi.documents().delete()delete()
删除文档或特定语言版本。如果未传递语言参数，delete() 仅删除文档的默认语言版本。这会删除草稿版和已发布版。
null (deletes only the default locale). See locale docs.deleteMany()
语法：deleteMany(parameters: Params): Promise<{ documentId: ID, entries: Number }>
🌐 Syntax: deleteMany(parameters: Params): Promise<{ documentId: ID, entries: Number }>
strapi.documents().deleteMany()deleteMany()
删除符合过滤器和关联参数的多个文档。
publish()
语法：publish(parameters: Params): Promise<{ documentId: ID, entries: Number }>
🌐 Syntax: publish(parameters: Params): Promise<{ documentId: ID, entries: Number }>
strapi.documents().publish()publish()
发布文档的草稿版本。仅当内容类型启用了“草稿与发布”时，此方法才可用。如果未传入 locale 参数，publish() 只会发布文档的默认语言版本。
unpublish()
语法：unpublish(parameters: Params): Promise<{ documentId: ID, entries: Number }>
🌐 Syntax: unpublish(parameters: Params): Promise<{ documentId: ID, entries: Number }>
strapi.documents().unpublish()unpublish()
将已发布的文档移回草稿状态。仅当内容类型启用了草稿和发布时，才可以使用此方法。如果未传递 locale 参数，unpublish() 仅会取消发布文档的默认语言版本。
discardDraft()
语法：discardDraft(parameters: Params): Promise<{ documentId: ID, entries: Number }>
🌐 Syntax: discardDraft(parameters: Params): Promise<{ documentId: ID, entries: Number }>
strapi.documents().discardDraft()discardDraft()
删除草稿数据，仅保留已发布的版本。只有在内容类型启用了“草稿与发布”功能时，此方法才可用。如果未传递 locale 参数，discardDraft() 将删除草稿数据，并仅在默认语言 环境下用已发布的版本覆盖它。
count()
语法：count(parameters: Params) => number
🌐 Syntax: count(parameters: Params) => number
strapi.documents().count()count()
计算有多少文档符合参数。如果未传递参数，count() 方法将返回默认语言环境的文档总数。
published to count only published documents, draft to count draft documents (returns all documents). Default: draft. See status docs.status. See publicationFilter docs.由于已发布的文档必然也有草稿副本，因此已发布的文档仍算作具有草稿版本。
🌐 Since published documents necessarily also have a draft counterpart, a published document is still counted as having a draft version.
这意味着使用 status: 'draft' 参数计数仍然会返回符合其他参数的文档总数，即使某些文档已经发布，并且在内容管理器中不再显示为“草稿”或“已修改”。要仅计数从未发布过的草稿，请传递 publicationFilter 值，如 'never-published' 或 'never-published-document'。
🌐 This means that counting with the status: 'draft' parameter still returns the total number of documents matching other parameters, even if some documents have already been published and are not displayed as "draft" or "modified" in the Content Manager anymore. To count only never-published drafts, pass a publicationFilter value such as 'never-published' or 'never-published-document'.