文档服务 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() | 删除文档或特定区域版本。 |
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.- Request
await strapi.documents('api::restaurant.restaurant').findOne({
documentId: 'a1b2c3d4e5f6g7h8i9j0klmn'
})
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"name": "Biscotte Restaurant",
"publishedAt": null,
"locale": "en"
}
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.- Generic example
- With filters
await strapi.documents('api::restaurant.restaurant').findFirst()
await strapi.documents('api::restaurant.restaurant').findFirst(
{
filters: {
name: {
$startsWith: "Pizzeria"
}
}
}
)
- 200 Generic
- 200 With filters
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"name": "Restaurant Biscotte",
"publishedAt": null,
"locale": "en"
}
{
"documentId": "j9k8l7m6n5o4p3q2r1s0tuvw",
"name": "Pizzeria Arrivederci",
"publishedAt": null,
"locale": "en"
}
如果未传入 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.- Generic example
- With filters
await strapi.documents('api::restaurant.restaurant').findMany()
await strapi.documents('api::restaurant.restaurant').findMany(
{
filters: {
name: {
$startsWith: 'Pizzeria'
}
}
}
)
- 200 Generic
- 200 With filters
[
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"name": "Biscotte Restaurant",
"publishedAt": null,
"locale": "en"
},
{
"documentId": "j9k8l7m6n5o4p3q2r1s0tuvw",
"name": "Pizzeria Arrivederci",
"publishedAt": null,
"locale": "en"
}
]
[
{
"documentId": "j9k8l7m6n5o4p3q2r1s0tuvw",
"name": "Pizzeria Arrivederci",
"locale": "en",
"publishedAt": null
}
]
可用的过滤器详细信息请参见文档服务 API 参考中的 filters 页面。
🌐 Available filters are detailed in the filters page of the Document Service API reference.
如果未传入 locale 或 status 参数，结果将 返回默认语言环境的草稿版本。
🌐 If no locale or status parameters are passed, results return the draft version for the default locale.
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.- Request
await strapi.documents('api::restaurant.restaurant').create({
data: {
name: 'Restaurant B'
}
})
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"name": "Restaurant B",
"publishedAt": null,
"locale": "en"
}
如果在内容类型上启用了草稿与发布功能，你可以在创建文档的同时自动发布它（参见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.- Request
await strapi.documents('api::restaurant.restaurant').update({
documentId: 'a1b2c3d4e5f6g7h8i9j0klmn',
data: { name: "New restaurant name" }
})
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"name": "New restaurant name",
"locale": "en",
"publishedAt": null
}
已发布的版本是只读的，因此你不能从技术上更新文档的已发布版本。 要更新文档并立即发布新版本，你可以：
🌐 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:
不推荐通过重复使用已发布的组件 id 来更新可重复使用的组件（详情和解决方法请看相关的 破坏性变更条目）。最好是替换掉不含 id 的完整组件数组，或者使用草稿组件 ID 进行更新。
🌐 It's not recommended to update repeatable components by reusing published component ids (see the related breaking change entry for details and workarounds). Prefer replacing the full component array without ids, or updating against draft component ids.
delete()
语法：delete(parameters: Params): Promise<{ documentId: ID, entries: Document[] }>
🌐 Syntax: delete(parameters: Params): Promise<{ documentId: ID, entries: Document[] }>
strapi.documents().delete()delete()
删除文档或特定语言版本。如果未传递语言参数，delete() 仅删除文档的默认语言版本。这会删除草稿版和已发布版。
null (deletes only the default locale). See locale docs.- Request
await strapi.documents('api::restaurant.restaurant').delete({
documentId: 'a1b2c3d4e5f6g7h8i9j0klmn',
})
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"entries": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"name": "Biscotte Restaurant",
"publishedAt": "2024-03-14T18:30:48.870Z",
"locale": "en"
}
]
}
publish()
语法：publish(parameters: Params): Promise<{ documentId: ID, entries: Document[] }>
🌐 Syntax: publish(parameters: Params): Promise<{ documentId: ID, entries: Document[] }>
strapi.documents().publish()publish()
发布文档的草稿版本。仅当内容类型启用了“草稿与发布”时，此方法才可用。如果未传入 locale 参数，publish() 只会发布文档的默认语言版本。
- Request
await strapi.documents('api::restaurant.restaurant').publish({
documentId: 'a1b2c3d4e5f6g7h8i9j0klmn',
});
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"entries": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"name": "Biscotte Restaurant",
"publishedAt": "2024-03-14T18:30:48.870Z",
"locale": "en"
}
]
}
unpublish()
语法：unpublish(parameters: Params): Promise<{ documentId: ID, entries: Document[] }>
🌐 Syntax: unpublish(parameters: Params): Promise<{ documentId: ID, entries: Document[] }>
strapi.documents().unpublish()unpublish()
将已发布的文档移回草稿状态。仅当内容类型启用了草稿和发布时，才可以使用此方法。如果未传递 locale 参数，unpublish() 仅会取消发布文档的默认语言版本。
- Request
await strapi.documents('api::restaurant.restaurant').unpublish({
documentId: 'a1b2c3d4e5f6g7h8i9j0klmn'
});
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"entries": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"name": "Biscotte Restaurant",
"publishedAt": null,
"locale": "en"
}
]
}
discardDraft()
语法：discardDraft(parameters: Params): Promise<{ documentId: ID, entries: Document[] }>
🌐 Syntax: discardDraft(parameters: Params): Promise<{ documentId: ID, entries: Document[] }>
strapi.documents().discardDraft()discardDraft()
删除草稿数据，仅保留已发布的版本。只有在内容类型启用了“草稿与发布”功能时，此方法才可用。如果未传递 locale 参数，discardDraft() 将删除草稿数据，并仅在默认语言环境下用已发布的版本覆盖它。
- Request
strapi.documents('api::restaurant.restaurant').discardDraft({
documentId: 'a1b2c3d4e5f6g7h8i9j0klmn',
});
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"entries": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klmn",
"name": "Biscotte Restaurant",
"publishedAt": null,
"locale": "en"
}
]
}
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.- Generic example
- Count published
- With filters
await strapi.documents('api::restaurant.restaurant').count()
strapi.documents('api::restaurant.restaurant').count({ status: 'published' })
/**
* Count number of draft documents (default if status is omitted)
* in English (default locale)
* whose name starts with 'Pizzeria'
*/
strapi.documents('api::restaurant.restaurant').count({ filters: { name: { $startsWith: "Pizzeria" }}})
由于已发布的文档必然也有草稿副本，因此已发布的文档仍算作具有草稿版本。
🌐 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'.