使用实体服务 API 的 CRUD 操作

🌐 CRUD operations with the Entity Service API

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 |

例子

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

例子

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

Example

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