文档服务 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 v4 中使用的实体服务 API(查看 Strapi v4 文档)。有关如何从实体服务 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 | 如果为内容类型启用了 起草并发布: 发布状态,可以是:
| '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:
await strapi.documents('api::restaurant.restaurant').findOne({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm'
})
{
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 | 如果为内容类型启用了 起草并发布: 发布状态,可以是:
| '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):
await strapi.documents('api::restaurant.restaurant').findFirst()
{
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"
}
}
}
)
{
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' | '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:
await strapi.documents('api::restaurant.restaurant').findMany()
[
{
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'
}
}
}
)
[
{
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:
await strapi.documents('api::restaurant.restaurant').create({
data: {
name: 'Restaurant B'
}
})
{
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 withpublish()
, -
或直接添加
status: 'published'
以及传递给update()
的其他参数(参见status
文档)。¥or directly add
status: 'published'
along with the other parameters passed toupdate()
(seestatus
documentation).
示例
¥Example
如果没有传递 locale
参数,update()
将更新默认语言环境的文档:
¥If no locale
parameter is passed, update()
updates the document for the default locale:
await strapi.documents('api::restaurant.restaurant').update({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
data: { name: "New restaurant name" }
})
{
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:
await strapi.documents('api::restaurant.restaurant').delete({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
})
{
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:
await strapi.documents('api::restaurant.restaurant').publish({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
});
{
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.