使用实体服务 API 进行 CRUD 操作

¥CRUD operations with the Entity Service API

提醒

Strapi v5 中的实体服务 API 已弃用。请考虑改用 文档服务 API。

¥The Entity Service API is deprecated in Strapi v5. Please consider using the Document Service API instead.

实体服务 API 构建在 查询引擎 API 之上，并使用它对实体执行 CRUD 操作。

¥The Entity Service API is built on top of the the Query Engine API and uses it to perform CRUD operations on entities.

该 API 的函数调用中使用的 uid 参数是使用以下格式构建的 string：[category]::[content-type]，其中 category 是以下之一：admin、plugin 或 api。

¥The uid parameter used in function calls for this API is a string built with the following format: [category]::[content-type] where category is one of: admin, plugin or api.

示例：

¥Examples:

• 获取 Strapi 管理面板用户的正确 uid 是 admin::user。

  ¥A correct uid to get users of the Strapi admin panel is admin::user.

• 上传插件的 uid 可能是 plugin::upload.file。

  ¥A possible uid for the Upload plugin could be plugin::upload.file.

• 由于用户定义的自定义内容类型的 uid 遵循 api::[content-type] 语法，因此如果内容类型 article 存在，则 api::article.article 会引用它。

  ¥As the uids for user-defined custom content-types follow the api::[content-type] syntax, if a content-type article exists, it is referenced by api::article.article.

提示

在终端中运行 strapi content-types:list 命令以显示特定 Strapi 实例的所有可能内容类型的 uid。

¥Run the strapi content-types:list command in a terminal to display all possible content-types' uids for a specific Strapi instance.

findOne()

查找与参数匹配的第一个条目。

¥Finds the first entry matching the parameters.

语法：findOne(uid: string, id: ID, parameters: Params) ⇒ Entry

¥Syntax: findOne(uid: string, id: ID, parameters: Params) ⇒ Entry

参数

¥Parameters

范围	描述	类型
fields	要返回的属性	String[]
populate	与 populate 的关系、组件和动态区域	PopulateParameter

示例

¥Example

const entry = await strapi.entityService.findOne('api::article.article', 1, {


  fields: ['title', 'description'],
  populate: { category: true },
});

findMany()

查找与参数匹配的条目。

¥Finds entries matching the parameters.

语法：findMany(uid: string, parameters: Params) ⇒ Entry[]

¥Syntax: findMany(uid: string, parameters: Params) ⇒ Entry[]

参数

¥Parameters

范围	描述	类型
fields	要返回的属性	String[]
filters	使用 过滤器	FiltersParameters
start	要跳过的条目数（参见 pagination）	Number
limit	要返回的条目数（参见 pagination）	Number
sort	命令 定义	OrderByParameter
populate	与 populate 的关系、组件和动态区域	PopulateParameter
publicationState	发布状态，可以是： live 仅返回已发布的条目 preview 返回草稿条目和已发布的条目（默认）	PublicationStateParameter

示例

¥Example

const entries = await strapi.entityService.findMany('api::article.article', {


  fields: ['title', 'description'],
  filters: { title: 'Hello World' },
  sort: { createdAt: 'DESC' },
  populate: { category: true },
});

提示

要仅检索草稿条目，请组合 preview 发布状态和 publishedAt 字段：

¥To retrieve only draft entries, combine the preview publication state and the publishedAt fields:

const entries = await strapi.entityService.findMany('api::article.article', {


  publicationState: 'preview',
  filters: {
    publishedAt: {
      $null: true,
    },
  },
});

create()

Creates one entry and returns it

Syntax: create(uid: string, parameters: Params) ⇒ Entry

Parameters

Parameter	Description	Type
fields	Attributes to return	String[]
populate	Relations, components and dynamic zones to populate	PopulateParameter
data	Input data	Object

提示

在 data 对象中，可以使用 REST API 描述的语法通过 connect、disconnect 和 set 参数来管理关系（请参阅 管理关系）。

¥In the data object, relations can be managed with the connect, disconnect, and set parameters using the syntax described for the REST API (see managing relations).

Example

const entry = await strapi.entityService.create('api::article.article', {


  data: {
    title: 'My Article',
  },
});

update()

更新一项并返回它。

¥Updates one entry and returns it.

注意

update() 仅执行部分更新，因此未包含的现有字段不会被替换。

¥update() only performs a partial update, so existing fields that are not included won't be replaced.

语法：update(uid: string, id: ID, parameters: Params) ⇒ Entry

¥Syntax: update(uid: string, id: ID, parameters: Params) ⇒ Entry

提示

在 data 对象中，可以使用 REST API 描述的语法通过 connect、disconnect 和 set 参数来管理关系（请参阅 管理关系）。

¥In the data object, relations can be managed with the connect, disconnect, and set parameters using the syntax described for the REST API (see managing relations).

参数

¥Parameters

范围	描述	类型
fields	要返回的属性	String[]
populate	与 populate 的关系、组件和动态区域	PopulateParameter
data	输入数据	object

示例

¥Example

const entry = await strapi.entityService.update('api::article.article', 1, {


  data: {
    title: 'xxx',
  },
});

delete()

删除一项并将其返回。

¥Deletes one entry and returns it.

语法：delete(uid: string, id: ID, parameters: Params) ⇒ Entry

¥Syntax: delete(uid: string, id: ID, parameters: Params) ⇒ Entry

参数

¥Parameters

范围	描述	类型
fields	要返回的属性	String[]
populate	与 populate 的关系、组件和动态区域	PopulateParameter

示例

¥Example

const entry = await strapi.entityService.delete('api::article.article', 1);