文档服务 API

¥Document Service API

文档服务 API 建立在查询引擎 API 之上

¥The Document Service API is built on top of the Query Engine API

并用于对文档执行 CRUD（create、retrieve、update 和 delete）操作。

¥and used to perform CRUD (create, retrieve, update, and delete) operations on documents .

使用文档服务 API，你还可以 count 文档，如果内容类型上启用了起草并发布，还可以执行 Strapi 特定的功能，例如 publishing/unpublishing 文档和丢弃草稿。

¥With the Document Service API, you can also count documents and, if Draft & Publish is enabled on the content-type, perform Strapi-specific features such as publishing/unpublishing documents and discarding drafts.

🤓 实体服务 API 在 Strapi 5 中已弃用

文档服务 API 旨在取代 Strapi v4（查看 Strapi v4 文档）中使用的实体服务 API。有关如何从实体服务 API 过渡到文档服务 API 的更多信息，请参阅相关的迁移参考。

¥The Document Service API is meant to replace the Entity Service API used in Strapi v4 (see Strapi v4 documentation). Additional information on how to transition away from the Entity Service API to the Document Service API can be found in the related migration reference.

✏️ 注意

内容类型之间的关系可以通过 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).

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

Find a document by passing its 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
  // …
}

`findFirst()`

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

¥Find the first document matching the parameters.

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

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

参数

¥Parameters

范围	描述	默认	类型
`locale`	要查找的文档的语言环境。	默认语言环境	字符串或 `undefined`
`status`	如果为内容类型启用了起草并发布：发布状态，可以是： `'published'` 仅查找已发布的文档 `'draft'` 仅查找草稿文档	`'draft'`	`'published'` 或 `'draft'`
`filters`	使用过滤器	`null`	目的
`fields`	选择字段返回	所有字段（默认情况下未填充的字段除外）	目的
`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):

Find the first document

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:

Find the first document that matches the defined filters

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`	如果为内容类型启用了起草并发布：发布状态，可以是： `'published'` 仅查找已发布的文档 `'draft'` 仅查找草稿文档	`'draft'`	`'published'` 或 `'draft'`
`filters`	使用过滤器	`null`	目的
`fields`	选择字段返回	所有字段（默认情况下未填充的字段除外）	目的
`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:

Find documents that match a specific filter

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:

Find documents that match a specific filter

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:

Create a new 'Restaurant B' document

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

Example response

{
  documentId: "ln1gkzs6ojl9d707xn6v86mw",
  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()`

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

¥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`	目的

💡 提示

发布你的文档（请参阅），要更新文档并立即发布新版本，你可以：

¥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() 更新发布它，
¥update its draft version with update(), then publish it with publish(),
或直接添加 status: 'published' 以及传递给 update() 的其他参数（参见 status 文档）。
¥or directly add status: 'published' along with the other parameters passed to update() (see status documentation).

示例

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

Discard draft for the default locale of a document

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`	目的

✏️ 注意

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

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

这意味着使用 status: 'draft' 参数计数仍会返回与其他参数匹配的文档总数，即使某些文档已经发布并且不再在内容管理器中显示为 "draft" 或 "modified"。目前没有办法阻止已发布的文档被计算在内。

¥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() 方法将返回默认语言环境的文档总数：

¥If no parameter is passed, the count() method the total number of documents for the default locale:

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

文档服务 API

findOne()​

参数​

示例​

findFirst()​

参数​

示例​

通用示例​

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

findMany()​

参数​

示例​

通用示例​

查找与参数匹配的文档​

create()​

参数​

示例​

update()​

参数​

示例​

delete()​

参数​

示例​

publish()​

参数​

示例​

unpublish()​

参数​

示例​

discardDraft()​

参数​

示例​

count()​

参数​

示例​

通用示例​

计数已发布的文档​

使用过滤器计数文档​

`findOne()`

参数

示例

`findFirst()`

参数

示例

通用示例

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

`findMany()`

参数

示例

通用示例

查找与参数匹配的文档

`create()`

参数

示例

`update()`

参数

示例

`delete()`

参数

示例

`publish()`

参数

示例

`unpublish()`

参数

示例

`discardDraft()`

参数

示例

`count()`

参数

示例

通用示例

计数已发布的文档

使用过滤器计数文档