文档服务 API

🌐 Document Service API

文档服务 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.

documentId 解释：从 Strapi v4 替换 id

在以前的 Strapi 版本中，id 的概念（既用于内容 API，也用作数据库行标识符）并不总是稳定：单个条目可能有多个版本或本地化，其数字标识符 id 在复制或导入/导出操作等情况下可能会发生变化。

🌐 In previous Strapi versions, the concept of id (used both in the Content API and as the database row identifier) was not always stable: a single entry could have multiple versions or localizations, and its numeric identifier id could change in cases such as duplication or import/export operations.

为了解决这一限制，Strapi 5 引入了 documentId，一个由 24 个字符组成的字母数字字符串，作为内容条目的唯一且持久的标识符，独立于其物理记录。

🌐 To address this limitation, Strapi 5 introduced documentId, a 24-character alphanumeric string, as a unique and persistent identifier for a content entry, independent of its physical records.

这个新的标识符在 Strapi 5 内部用于管理关系、发布、本地化和版本历史，因为内容条目的所有可能变体现在都被归类在单一的文档概念下。

🌐 This new identifier is used internally in Strapi 5 to manage relationships, publishing, localization, and version history, as all possible variations of a content entry are now grouped under a single document concept.

因此，从 Strapi 5 开始，许多 API 和服务依赖 documentId 而不是 id 来确保操作的一致性。一些 API 可能仍会返回 documentId 和 id 以便过渡，但强烈建议在内容查询中使用 documentId，因为 documentId 可能是未来 Strapi 版本中唯一使用的标识符。

🌐 As a result, starting with Strapi 5, many APIs and services rely on documentId instead of id to ensure consistency across operations. Some APIs may still return both documentId and id to ease the transition, but using documentId for content queries is strongly recommended, as documentId might be the only identifier used in future Strapi versions.

有关从 id 过渡到 documentId 的更多详细信息，请参阅重大更改页面和从实体服务到文档服务 API 的迁移指南。

🌐 For more details on the transition from id to documentId, refer to the breaking change page and the migration guide from Entity Service to Document Service API.

Entity Service API is deprecated in Strapi 5

文档服务 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.

Note

关系也可以通过文档服务 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).

配置

🌐 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() | 计算有多少文档符合参数条件。 |

`findOne()`

查找与传入的 documentId 和参数匹配的文档。

🌐 Find a document matching the passed documentId and parameters.

语法：findOne(parameters: Params) => Document

🌐 Syntax: findOne(parameters: Params) => Document

参数

🌐 Parameters | 参数 | 描述 | 默认值 | 类型 ||-----------|-------------|---------|------|| documentId | 文档 ID | | ID || locale | 要查找的文档的语言环境 | 默认语言环境 | 字符串或 undefined || status | 如果内容类型启用了草稿 & 发布：
发布状态，可选：

'published' 仅查找已发布文档
'draft' 仅查找草稿文档

| 'draft' | 'published' 或 'draft' || fields | 要返回的选择字段 | 所有字段
(默认未填充的字段除外) | 对象 || populate | 使用额外字段填充结果 | null | 对象 |

例子

🌐 Example

如果仅传递 documentId 而没有其他参数，findOne() 会返回默认语言环境下文档的草稿版本：

🌐 If only a documentId is passed without any other parameters, findOne() returns the draft version of a document in the default locale:

通过传递其 documentId 查找文档

await strapi.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm'
})

Example response

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: null, // draft version (default)
  locale: "en", // default locale
  // …
}

findOne() 方法在找到时返回匹配的文档，否则返回 null。

🌐 The findOne() method returns the matching document if found, otherwise returns null.

`findFirst()`

查找与参数匹配的第一个文档。

🌐 Find the first document matching the parameters.

语法：findFirst(parameters: Params) => Document

🌐 Syntax: findFirst(parameters: Params) => Document

参数

🌐 Parameters

参数	描述	默认值	类型
`locale`	要查找的文档的语言环境。	默认语言环境	字符串或 `undefined`
`status`	如果内容类型启用了 Draft & Publish: 发布状态，可以是： `'published'` 仅查找已发布文档 `'draft'` 仅查找草稿文档	`'draft'`	`'published'` 或 `'draft'`
`filters`	使用的筛选器	`null`	对象
`fields`	选择返回的字段	所有字段（除默认未填充的字段外）	对象
`populate`	Populate 用额外的字段填充结果。	`null`	对象

例子

🌐 Examples

通用示例

🌐 Generic example

默认情况下，findFirst() 会返回传入唯一标识符（集合类型 ID 或单类型 ID）的第一个文档的草稿版本，使用默认语言环境：

🌐 By default, findFirst() returns the draft version, in the default locale, of the first document for the passed unique identifier (collection type id or single type id):

找到第一份文件

await strapi.documents('api::restaurant.restaurant').findFirst()

Example response

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Restaurant Biscotte",
  publishedAt: null,
  locale: "en"
  // …
}

查找符合参数的第一个文档

🌐 Find the first document matching parameters

向 findFirst() 传递一些参数以返回与之匹配的第一个文档。

🌐 Pass some parameters to findFirst() to return the first document matching them.

如果未传入 locale 或 status 参数，结果将返回默认语言环境的草稿版本：

🌐 If no locale or status parameters are passed, results return the draft version for the default locale:

查找符合定义筛选条件的第一个文档

await strapi.documents('api::restaurant.restaurant').findFirst(
  {
    filters: {
      name: {
        $startsWith: "Pizzeria"
      }
    }
  }
)

Example response

{
  documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
  name: "Pizzeria Arrivederci",
  publishedAt: null,
  locale: "en"
  // …
}

`findMany()`

查找与参数匹配的文档。

🌐 Find documents matching the parameters.

语法：findMany(parameters: Params) => Document[]

🌐 Syntax: findMany(parameters: Params) => Document[]

参数

🌐 Parameters

参数	描述	默认值	类型
`locale`	要查找的文档的区域设置。	默认区域设置	字符串或 `undefined`
`status`	如果内容类型启用了 Draft & Publish: 发布状态，可以是： `'published'` 仅查找已发布文档 `'draft'` 仅查找草稿文档	`'draft'`	`'published'` 或 `'draft'`
`filters`	使用的筛选器	`null`	对象
`fields`	选择返回的字段	所有字段（除默认未填充的字段外）	对象
`populate`	Populate 用额外的字段填充结果。	`null`	对象
`pagination`	分页结果
`sort`	排序结果

例子

🌐 Examples

通用示例

🌐 Generic example

当没有传入参数时，findMany() 会返回每个文档在默认语言环境下的草稿版本：

🌐 When no parameter is passed, findMany() returns the draft version in the default locale for each document:

查找符合特定筛选条件的文档

await strapi.documents('api::restaurant.restaurant').findMany()

Example response

[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: null, // draft version (default)
    locale: "en" // default locale
    // …
  },
  {
    documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
    name: "Pizzeria Arrivederci",
    publishedAt: null,
    locale: "en"
    // …
  },
]

查找符合参数的文档

🌐 Find documents matching parameters

可用的过滤器详细信息请参见文档服务 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:

查找符合特定筛选条件的文档

await strapi.documents('api::restaurant.restaurant').findMany(
  {
    filters: {  
      name: {
        $startsWith: 'Pizzeria'
      }
    }
  }
)

Example response

[
  {
    documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
    name: "Pizzeria Arrivederci",
    locale: "en", // default locale
    publishedAt: null, // draft version (default)
    // …
  }, 
  // …
]

`create()`

创建草稿文档并返回它。

🌐 Creates a drafted document and returns it.

传递字段以在 data 对象中创建内容。

🌐 Pass fields for the content to create in a data object.

语法：create(parameters: Params) => Document

🌐 Syntax: create(parameters: Params) => Document

参数

🌐 Parameters | 参数 | 描述 | 默认值 | 类型 ||-----------|-------------|---------|------|| locale | 要创建的文档的语言环境。 | 默认语言环境 | 字符串或 undefined || fields | 要返回的选择字段 | 所有字段
(默认未填充的字段除外) | 对象 || status | 如果内容类型启用了草稿与发布：
可以设置为 'published'，以在创建文档时自动发布草稿版本 | - | 'published' || populate | 使用附加字段填充结果。 | null | 对象 |

例子

🌐 Example

如果没有传入 locale 参数，create() 会为默认语言创建文档的草稿版本：

🌐 If no locale parameter is passed, create() creates the draft version of the document for the default locale:

创建一个新的『餐厅 B』文档

await strapi.documents('api::restaurant.restaurant').create({
  data: {
    name: 'Restaurant B'
  }
})

Example response

{
  documentId: "ln1gkzs6ojl9d707xn6v86mw",
  name: "Restaurant B",
  publishedAt: null,
  locale: "en",
}

Tip

如果在内容类型上启用了草稿与发布功能，你可以在创建文档的同时自动发布它（参见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()`

更新文档版本并返回它们。

🌐 Updates document versions and returns them.

语法：update(parameters: Params) => Promise<Document>

🌐 Syntax: update(parameters: Params) => Promise<Document>

参数

🌐 Parameters | 参数 | 描述 | 默认值 | 类型 ||-----------|-------------|---------|------|| documentId | 文档 ID | | ID || locale | 要更新的文档的语言环境 | 默认语言环境 | 字符串或 null || filters | 使用的过滤器 | null | 对象 || fields | 要返回的选择字段 | 所有字段
（默认未填充的字段除外） | 对象 || status | 如果内容类型启用了草稿与发布:
可以设置为 'published'，在更新文档时自动发布草稿版本 | - | 'published' || populate | 使用额外字段填充结果 | null | 对象 |

Tip

已发布的版本是只读的，因此你不能从技术上更新文档的已发布版本。要更新文档并立即发布新版本，你可以：

🌐 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:

使用 update() 更新其草稿版本，然后使用 publish() 发布它，
或者直接将 status: 'published' 与传递给 update() 的其他参数一起添加（参见 status 文档）。

Caution

不建议使用文档服务 API 更新可重复组件（更多详情请参见相关的重大更改条目）。

🌐 It's not recommended to update repeatable components with the Document Service API (see the related breaking change entry for more details).

例子

🌐 Example

如果没有传入 locale 参数，update() 会更新默认语言环境的文档：

🌐 If no locale parameter is passed, update() updates the document for the default locale:

Example request

await strapi.documents('api::restaurant.restaurant').update({ 
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    data: { name: "New restaurant name" }
})

Example response

{
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  name: "New restaurant name",
  locale: "en",
  publishedAt: null, // draft
  // …
}

`delete()`

删除一个文档或其特定语言环境。

🌐 Deletes one document, or a specific locale of it.

语法：delete(parameters: Params): Promise<{ documentId: ID, entries: Number }>

🌐 Syntax: delete(parameters: Params): Promise<{ documentId: ID, entries: Number }>

参数

🌐 Parameters | 参数 | 描述 | 默认值 | 类型 ||-----------|-------------|---------|------|| documentId | 文档 ID | | ID || locale | 要删除的文档的本地化版本。 | null
(仅删除默认语言) | 字符串, '*', 或 null || filters | 要使用的筛选器 | null | 对象 || fields | 要返回的选择字段 | 所有字段
(默认未填充的除外) | 对象 || populate | 使用附加字段填充结果。 | null | 对象 |

例子

🌐 Example

如果没有传递 locale 参数，delete() 只会删除文档的默认语言版本。这会删除草稿和已发布的版本：

🌐 If no locale parameter is passed, delete() only deletes the default locale version of a document. This deletes both the draft and published versions:

Example request

await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
})

Example response

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  entries: [
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "name": "Biscotte Restaurant",
      "publishedAt": "2024-03-14T18:30:48.870Z",
      "locale": "en"
      // …
    }
  ]
}

`publish()`

已发布的版本是只读的，因此你无法从技术上更新文档的已发布版本。

🌐 Publishes one or multiple locales of a document.

只有在内容类型上启用了草稿与发布时，此方法才可用。

🌐 This method is only available if Draft & Publish is enabled on the content-type.

语法：publish(parameters: Params): Promise<{ documentId: ID, entries: Number }>

🌐 Syntax: publish(parameters: Params): Promise<{ documentId: ID, entries: Number }>

参数

🌐 Parameters | 参数 | 描述 | 默认值 | 类型 ||-----------|-------------|---------|------|| documentId | 文档 ID | | ID || locale | 要发布的文档的语言环境 | 仅默认语言环境 | 字符串, '*', 或 null || filters | 使用的过滤器 | null | 对象 || fields | 返回的选择字段 | 所有字段
（默认未填充的字段除外） | 对象 || populate | 使用额外字段填充结果 | null | 对象 |

例子

🌐 Example

如果没有传递 locale 参数，publish() 只会发布文档的默认语言版本：

🌐 If no locale parameter is passed, publish() only publishes the default locale version of the document:

Example request

await strapi.documents('api::restaurant.restaurant').publish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
});

Example response

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  entries: [
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "name": "Biscotte Restaurant",
      "publishedAt": "2024-03-14T18:30:48.870Z",
      "locale": "en"
      // …
    }
  ]
}

`unpublish()`

取消发布文档的一个或所有语言环境版本，并返回未发布的语言环境版本数。

🌐 Unpublishes one or all locale versions of a document, and returns how many locale versions were unpublished.

只有在内容类型上启用了草稿与发布时，此方法才可用。

🌐 This method is only available if Draft & Publish is enabled on the content-type.

语法：unpublish(parameters: Params): Promise<{ documentId: ID, entries: Number }>

🌐 Syntax: unpublish(parameters: Params): Promise<{ documentId: ID, entries: Number }>

参数

🌐 Parameters | 参数 | 描述 | 默认值 | 类型 ||-----------|-------------|---------|------|| documentId | 文档 ID | | ID || locale | 要取消发布的文档的语言环境。 | 仅默认语言环境 | 字符串, '*' 或 null || filters | 使用的过滤器 | null | 对象 || fields | 要返回的选择字段 | 所有字段
（默认未填充的字段除外） | 对象 || populate | 用额外字段填充结果。 | null | 对象 |

例子

🌐 Example

如果没有传入 locale 参数，unpublish() 只会取消发布文档的默认语言版本：

🌐 If no locale parameter is passed, unpublish() only unpublishes the default locale version of the document:

Example request

await strapi.documents('api::restaurant.restaurant').unpublish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm' 
});

Example response

{
  documentId: "lviw819d5htwvga8s3kovdij",
  entries: [
    {
      documentId: "lviw819d5htwvga8s3kovdij",
      name: "Biscotte Restaurant",
      publishedAt: null,
      locale: "en"
      // …
    }
  ]
}

`discardDraft()`

丢弃草稿数据并用已发布的版本覆盖它。

🌐 Discards draft data and overrides it with the published version.

只有在内容类型上启用了草稿与发布时，此方法才可用。

🌐 This method is only available if Draft & Publish is enabled on the content-type.

语法：discardDraft(parameters: Params): Promise<{ documentId: ID, entries: Number }>

🌐 Syntax: discardDraft(parameters: Params): Promise<{ documentId: ID, entries: Number }>

参数

🌐 Parameters | 参数 | 描述 | 默认值 | 类型 ||-----------|-------------|---------|------|| documentId | 文档ID | | ID || locale | 要丢弃的文档的语言环境 | 仅默认语言 | 字符串，'*' 或 null || filters | 使用的过滤器 | null | 对象 || fields | 要返回的选择字段 | 所有字段
（默认未填充的字段除外） | 对象 || populate | 使用附加字段填充结果 | null | 对象 |

例子

🌐 Example

如果没有传递 locale 参数，discardDraft() 将丢弃草稿数据，并仅使用默认语言版本的已发布内容进行覆盖：

🌐 If no locale parameter is passed, discardDraft() discards draft data and overrides it with the published version only for the default locale:

放弃文档默认语言的草稿

strapi.documents.discardDraft({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', 
});

Example response

{
  documentId: "lviw819d5htwvga8s3kovdij",
  entries: [
    {
      documentId: "lviw819d5htwvga8s3kovdij",
      name: "Biscotte Restaurant",
      publishedAt: null,
      locale: "en"
      // …
    }
  ]
}

`count()`

计算与提供的参数匹配的文档数量。

🌐 Count the number of documents that match the provided parameters.

语法：count(parameters: Params) => number

🌐 Syntax: count(parameters: Params) => number

参数

🌐 Parameters | 参数 | 描述 | 默认值 | 类型 ||-----------|-------------|---------|------|| locale | 要计数的文档的区域设置 | 默认区域设置 | 字符串或 null || status | 如果内容类型启用了草稿与发布：
发布状态，可为：

'published' 仅查找已发布文档
'draft' 查找草稿文档（将返回所有文档）

| 'draft' | 'published' 或 'draft' || filters | 要使用的过滤器 | null | 对象 |

Note

由于已发布的文档必然也有草稿副本，因此已发布的文档仍算作具有草稿版本。

🌐 Since published documents necessarily also have a draft counterpart, a published document is still counted as having a draft version.

这意味着，即使某些文档已经发布并且在内容管理器中不再显示为“草稿”或“已修改”，使用 status: 'draft' 参数进行计数仍会返回符合其他参数的文档总数。目前没有方法可以阻止已发布的文档被计入统计。

🌐 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. There currently is no way to prevent already published documents from being counted.

例子

🌐 Examples

通用示例

🌐 Generic example

如果未传递参数，count() 方法将返回默认语言环境的文档总数：

Example request

await strapi.documents('api::restaurant.restaurant').count()

统计已发布的文件

🌐 Count published documents

要仅计算已发布的文档，请将 status: 'published' 与其他参数一起传递给 count() 方法。

🌐 To count only published documents, pass status: 'published' along with other parameters to the count() method.

如果没有传入 locale 参数，将会统计默认语言环境的文档。

🌐 If no locale parameter is passed, documents are counted for the default locale.

Example request

strapi.documents('api::restaurant.restaurant').count({ status: 'published' })

使用筛选条件计数文档

🌐 Count documents with filters

任何 filters 都可以传递给 count() 方法。

🌐 Any filters can be passed to the count() method.

如果没有传入 locale 和 status 参数，则草稿文档（即该语言环境的所有可用文档总数，因为即使已发布的文档也被视为有草稿版本）仅会计算默认语言环境：

🌐 If no locale and no status parameter is passed, draft documents (which is the total of available documents for the locale since even published documents are counted as having a draft version) are counted only for the default locale:

/**
 * 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" }}})`

配置​

文档对象​

方法概述​

findOne()​

参数​

例子​

findFirst()​

参数​

例子​

通用示例​

查找符合参数的第一个文档​

findMany()​

参数​

例子​

通用示例​

查找符合参数的文档​

create()​

参数​

例子​

update()​

参数​

例子​

delete()​

参数​

例子​

publish()​

参数​

例子​

unpublish()​

参数​

例子​

discardDraft()​

参数​

例子​

count()​

参数​

例子​

通用示例​

统计已发布的文件​

使用筛选条件计数文档​

配置

文档对象

方法概述

`findOne()`

参数

例子

`findFirst()`

参数

例子

通用示例

查找符合参数的第一个文档

`findMany()`

参数

例子

通用示例

查找符合参数的文档

`create()`

参数

例子

`update()`

参数

例子

`delete()`

参数

例子

`publish()`

参数

例子

`unpublish()`

参数

例子

`discardDraft()`

参数

例子

`count()`

参数

例子

通用示例

统计已发布的文件

使用筛选条件计数文档