使用实体服务 API 的 CRUD 操作

🌐 CRUD operations with the Entity Service API

Page summary:

实体服务 API 通过 findOne()、findMany()、create()、update() 和 delete() 方法对内容执行 CRUD 操作，支持过滤、分页、关联和本地化。

🌐 The Entity Service API performs CRUD operations on content through findOne(), findMany(), create(), update(), and delete() methods, supporting filtering, pagination, relations, and localization.

Caution

在 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。
• 上传插件的一个可能的 uid 可以是 plugin::upload.file。
• 由于用户定义的自定义内容类型的 uid 遵循 api::[content-type] 语法，如果存在内容类型 article，则通过 api::article.article 进行引用。

Tip

在终端中运行 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	要 填充 的关系、组件和动态区域	PopulateParameter
locale	当启用国际化插件时的语言代码（例如 fr-FR）。针对本地化变体而非默认语言。	string

例子

🌐 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	要跳过的条目数量（参见 分页）	Number
limit	要返回的条目数量（参见 分页）	Number
sort	订单 定义	OrderByParameter
populate	关系、组件和动态区域以 填充	PopulateParameter
publicationState	发布状态，可以是： live 仅返回已发布条目 preview 返回草稿条目和已发布条目（默认）	PublicationStateParameter
locale	当启用国际化插件时的语言环境代码。将结果限制为该语言环境（默认语言环境请省略）。	string

例子

🌐 Example

const entries = await strapi.entityService.findMany('api::article.article', {
  fields: ['title', 'description'],
  filters: { title: 'Hello World' },
  sort: { createdAt: 'DESC' },
  populate: { category: true },
});

Tip

要仅检索草稿条目，请结合使用 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
locale	Locale code when the Internationalization plugin is enabled. Creates the entry for that locale.	string
data	Input data	Object

Tip

在 data 对象中，可以使用 connect、disconnect 和 set 参数按照 REST API 描述的语法管理关系（参见 管理关系）。

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

Note

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

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

Tip

在 data 对象中，可以使用 connect、disconnect 和 set 参数按照 REST API 描述的语法管理关系（参见 管理关系）。

🌐 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

Parameter	Description	Type
fields	Attributes to return	String[]
populate	Relations, components and dynamic zones to populate	PopulateParameter
locale	Locale code when the Internationalization plugin is enabled. Updates the matching localized variant.	string
data	Input data	object

Example

const entry = await strapi.entityService.update('api::article.article', 1, {
  data: {
    title: 'xxx',
  },
});

delete()

Deletes one entry and returns it.

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

Parameters

Parameter	Description	Type
fields	Attributes to return	String[]
populate	Relations, components and dynamic zones to populate	PopulateParameter
locale	Locale code when the Internationalization plugin is enabled. Deletes the localized variant that matches this locale.	string

Example

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